Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

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.

Ver em Markdown

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 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:

Shell
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 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.

FixtureProduzSubstituições
message.receivedUma mensagem recebida de texto ou mídiatext, from, pushName, mediaType, caption
message.ackUma confirmação de uma mensagem enviadafrom, ackStatus, messageId
message.failedUm envio que falhoufrom, failureReason
call.receivedUma oferta de chamada recebidafrom, video
call.missedUma chamada recebida não atendidafrom
call.endedUma chamada encerradafrom, video, durationSeconds, callEndReason
session.statusUma mudança no status da conexãostatus, statusReason
session.restriction_updatedUma restrição do WhatsApp para iniciar novas conversas e chamadasrestrictionActive
template.statusA aprovação ou rejeição de um modelotemplateName, 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:

Shell
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:

Shell
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.

Shell
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#

StatusCausa
400O 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.
403A 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.
404resource_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.
429O projeto atingiu 30 eventos de teste por minuto.
502A 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.