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?.
- O projeto tem um número de teste. Use o valor
sessiondele no caminho da solicitação. - Disparar exige
sandbox:writee listar fixtures exigesandbox: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:
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:
{
"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 API Get project event; veja Histórico de eventos. 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 API List test event fixtures. A lista é a mesma para todos os projetos, então a solicitação não indica projeto nem número:
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. DefinamediaTypecomoimage,video,audio,documentoustickerpara enviar metadados de mídia, com umcaptionopcional 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 aceitaread,playedouerror.message.failed:failureReasonésend_failed.session.status:DISCONNECTEDcomSTREAM_ERROR.session.restriction_updated: a restrição começa e termina em 24 horas. DefinarestrictionActivecomofalsepara o evento que a encerra.template.status:APPROVED. DefinatemplateStatuscomoREJECTEDe umreasonopcional 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:
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 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.
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. |