> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 (`testMode: true`).
Uma solicitação para qualquer outro número retorna `400 Bad Request` e não envia
nada.

## Antes de começar

* A sua equipe tem acesso a números de teste. Consulte [O que é o Sandbox?](/pt-br/sandbox/introduction).
* O projeto tem um número de teste. Use o nome da sessão dele em cada solicitação.
* Você tem uma chave de projeto, ou uma chave de equipe, com o escopo
  `sandbox:write`. Listar fixtures exige `sandbox:read`. Tokens de cliente não
  podem disparar eventos de teste.

## Disparar um evento

Envie o nome do fixture em `event` e o número de teste em `session`:

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

A API retorna `202 Accepted`:

```json theme={null}
{
  "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](/api/events). Os eventos de teste trazem
`source: "test"` e `environment: "development"`, então você consegue
diferenciá-los dos eventos produzidos por atividade do WhatsApp.

Com o SDK de TypeScript:

```typescript theme={null}
import { MessagingClient } from "@polymorfa/sdk";

const client = new MessagingClient({
  credential: { type: "apiKey", value: process.env.POLYMORFA_KEY! },
});

const result = await client.testing.triggerEvent(process.env.PROJECT_ID!, {
  session: "my-test-number",
  event: "message.received",
  overrides: { text: "hi" },
});
console.log(result.data.eventId);
```

## 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/testing/{projectId}/events/fixtures`.

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 `fromSession`
em uma solicitação `message.received`:

```json theme={null}
{
  "session": "my-test-number",
  "event": "message.received",
  "fromSession": "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. `fromSession` 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](/pt-br/console/audit-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.

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

## Erros

| Status | Causa |
| - | - |
| `400` | A sessão não é um número de teste do projeto, o fixture ou uma substituição é inválido, ou `fromSession` não é um número de teste conectado. |
| `403` | A sua equipe não tem acesso a números de teste, ou a solicitação usou um token de cliente. |
| `404` | O projeto não existe na sua equipe ou não corresponde à 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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.