# Teste a sua integração com trigger

> Envie eventos de teste assinados de um número de teste para os seus webhooks e para a API de eventos.

Dispare um evento de teste nomeado para um número de teste e confira como a sua
integração o trata. A Polymorfa entrega o evento aos seus webhooks e à API de
eventos no mesmo formato dos eventos de produção, assinado com o segredo de
assinatura do seu endpoint. Você não precisa de um telefone, de uma segunda
pessoa nem de uma conta real do WhatsApp.

Os eventos de teste funcionam apenas para números de teste. A solicitação
indica o número de teste no caminho, e o número define o projeto. Um número
real, ou um número de teste fora do projeto da sua chave, retorna
`404 resource_not_found` e não envia nada.

## Antes de começar

- A sua equipe tem acesso a números de teste. Consulte [O que é o Sandbox?](https://docs.polymorfa.com/pt-br/testing).
- O projeto tem um número de teste. Use o valor `session` dele no caminho da
  solicitação.
- Disparar exige `sandbox:write` e listar fixtures exige `sandbox:read`. Use a
  chave de teste do projeto, ou um token de projeto ou uma chave de equipe com esses
  escopos. Tokens de cliente não podem disparar eventos de teste nem listar
  fixtures.

## Disparar um evento

Envie o nome do fixture em `event`. `my-test-number` é o valor `session` do
número de teste:

```bash
curl -X POST "https://api.polymorfa.com/messaging/my-test-number/test-events" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "message.received",
    "overrides": { "text": "hi", "from": "+15550100001" }
  }'
```

A API retorna `202 Accepted`:

```json
{
  "event": "message.received",
  "session": "my-test-number",
  "delivery": "generated",
  "eventId": "0199f1c2-7a4e-7c55-9d1e-3f0b8a2c6d10",
  "source": "test"
}
```

Os assinantes de webhook de `message.received` recebem o evento com o mesmo
envelope e os mesmos cabeçalhos de assinatura de qualquer outro evento. Consulte
o evento pelo `eventId` com `GET /platform/projects/{projectId}/events/{eventId}`;
veja [Histórico de eventos](https://docs.polymorfa.com/development/events). Os eventos de teste trazem
`source: "test"` e `environment: "development"`, então você consegue
diferenciá-los dos eventos produzidos por atividade do WhatsApp.

## Fixtures

O nome de cada fixture é o tipo de evento que ele produz.

| Fixture | Produz | Substituições |
| --- | --- | --- |
| `message.received` | Uma mensagem recebida de texto ou mídia | `text`, `from`, `pushName`, `mediaType`, `caption` |
| `message.ack` | Uma confirmação de uma mensagem enviada | `from`, `ackStatus`, `messageId` |
| `message.failed` | Um envio que falhou | `from`, `failureReason` |
| `call.received` | Uma oferta de chamada recebida | `from`, `video` |
| `call.missed` | Uma chamada recebida não atendida | `from` |
| `call.ended` | Uma chamada encerrada | `from`, `video`, `durationSeconds`, `callEndReason` |
| `session.status` | Uma mudança no status da conexão | `status`, `statusReason` |
| `session.restriction_updated` | Uma restrição do WhatsApp para iniciar novas conversas e chamadas | `restrictionActive` |
| `template.status` | A aprovação ou rejeição de um modelo | `templateName`, `templateStatus`, `reason` |

Liste os fixtures e as substituições deles com
`GET /messaging/test-events/fixtures`. A lista é a mesma para todos os
projetos, então a solicitação não indica projeto nem número:

```bash
curl "https://api.polymorfa.com/messaging/test-events/fixtures" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

Um fixture rejeita com `400 Bad Request` uma substituição que ele não lista.
Sem substituições, cada fixture usa estes valores:

- `message.received`: uma mensagem de texto de `+15550100001`. Defina
  `mediaType` como `image`, `video`, `audio`, `document` ou `sticker` para
  enviar metadados de mídia, com um `caption` opcional para imagens, vídeos e
  documentos. Os eventos de mídia gerados não contêm arquivo para download.
- `message.ack`: `ackStatus` é `delivered`. Também aceita `read`, `played` ou
  `error`.
- `message.failed`: `failureReason` é `send_failed`.
- `session.status`: `DISCONNECTED` com `STREAM_ERROR`.
- `session.restriction_updated`: a restrição começa e termina em 24 horas.
  Defina `restrictionActive` como `false` para o evento que a encerra.
- `template.status`: `APPROVED`. Defina `templateStatus` como `REJECTED` e um
  `reason` opcional para testar uma rejeição.

## O que os eventos de teste não mudam

Um evento de teste chega apenas aos seus webhooks e à API de eventos. Ele não
muda o número de teste: um evento `session.status` não o desconecta, um evento
`session.restriction_updated` não o restringe e os eventos de chamada não fazem
tocar os clientes do Calls. Os eventos de teste não contam nas métricas de
respostas de campanhas.

Os IDs de contato e de mensagem nos eventos gerados são aleatórios. Eles não se
referem a uma conversa, então você não pode responder a eles.

## Enviar uma mensagem simulada entre números de teste

Para testar o ciclo completo, incluindo respostas, envie uma mensagem simulada
real de outro número de teste conectado no mesmo projeto. Defina `fromNumber`
com o valor `session` do remetente em uma solicitação `message.received`. O
número de teste do caminho recebe a mensagem:

```bash
curl -X POST "https://api.polymorfa.com/messaging/my-test-number/test-events" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "message.received",
    "fromNumber": "my-other-test-number",
    "overrides": { "text": "hi" }
  }'
```

A resposta tem `"delivery": "simulated"` e `"eventId": null`. O evento
`message.received` chega logo depois como atividade comum do número de teste,
com `source: "runtime"`, e você pode responder a ele. Os dois números de teste
precisam estar conectados. `fromNumber` aceita apenas a substituição `text`.

## Limites

Cada projeto pode disparar 30 eventos de teste por minuto. As solicitações
seguintes retornam `429 Too Many Requests` com um cabeçalho `Retry-After` que
informa quantos segundos esperar. Cada disparo fica registrado no
[log de auditoria](https://docs.polymorfa.com/pt-br/development/logs) da sua equipe como
`testing.event.trigger`.

## Tentar novamente com segurança

Envie um cabeçalho `Idempotency-Key`, com até 255 caracteres ASCII imprimíveis,
para poder tentar novamente um disparo com segurança. Uma solicitação repetida
com a mesma chave e o mesmo corpo recebe o mesmo `eventId`, então o seu
histórico de eventos e os seus webhooks recebem o evento uma única vez. Um corpo
diferente com a mesma chave cria um evento separado. Isso não se aplica a
solicitações com `fromNumber`.

```bash
curl -X POST "https://api.polymorfa.com/messaging/test-a/test-events" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY" \
  -H "Idempotency-Key: order-flow-check-1" \
  -H "Content-Type: application/json" \
  -d '{"event": "message.received"}'
```

## Erros

| Status | Causa |
| --- | --- |
| `400` | O fixture ou uma substituição é inválido. Com `fromNumber`: o evento não é `message.received`, foi enviada uma substituição diferente de `text`, `fromNumber` indica o número de teste do caminho ou um dos números de teste não está conectado. |
| `403` | A sua equipe não tem acesso a números de teste, a chave não tem o escopo ou a solicitação usou um token de cliente. |
| `404` | `resource_not_found`: o número do caminho, ou `fromNumber`, é um número real ou não é um número de teste do projeto da sua chave. |
| `429` | O projeto atingiu 30 eventos de teste por minuto. |
| `502` | A entrega de eventos de teste ou a verificação de acesso está temporariamente indisponível. Tente novamente a solicitação com a mesma `Idempotency-Key`. |
