A resposta curta: grave um endereço HTTPS seu com PUT /v1/sms/webhook e, a partir daí, sempre que uma mensagem fica enviada ou falha, enviamos um aviso assinado para esse endereço. O seu sistema marca o aviso como enviado, ou tenta outro canal, sem ninguém ter de abrir o histórico.
Como funciona
| 1 |
O seu sistema pede o envio à API, com o número, o texto e, se quiser, a hora marcada.
|
|
| 2 |
A mensagem entra na fila: fica scheduled ou queued e sai na sua vez.
|
|
| 3 |
Sai ou falha. Quando fica sent ou failed, enviamos um POST para o seu endereço.
|
|
| 4 |
O seu sistema reage: atualiza o estado do aviso, ou passa para o e-mail se falhou.
|
|
Gravar o endereço
| Campo |
O que é |
| url |
O seu endereço HTTPS, na porta 443. Endereços internos ou privados são recusados. |
| events |
Os acontecimentos que quer receber: sms.sent, sms.failed ou os dois (por padrão, os dois). |
| rotate_secret |
Com true, cria um segredo novo. |
O segredo da assinatura só aparece quando o webhook é criado, ou quando pede um novo com rotate_secret: guarde-o logo. A permissão da chave para gravar é sms:write; para consultar, GET /v1/sms/webhook com sms:read mostra o endereço, os acontecimentos e a última entrega, nunca o segredo.
O que chega ao seu endereço
POST https://o-seu-sistema/webhook
X-Webhook-Signature: t=1763625600,v1=...
{"event": "sms.sent",
"created_at": "...",
"data": {"id": "412", "status": "sent", ...}}
O campo data traz os mesmos campos que a consulta de uma mensagem. Antes de confiar no aviso, confira a assinatura do cabeçalho X-Webhook-Signature: veja receber um webhook em PHP e conferir a assinatura e, se algo não chegar, o webhook do SMS não chega.
|
Só conta daqui para a frente. O webhook avisa sobre as mensagens criadas depois de ele ser gravado. As anteriores consultam-se com GET /v1/sms/messages/{id}.
|
Testar e desligar
POST /v1/sms/webhook/test envia já um aviso assinado webhook.test e devolve o que o seu servidor respondeu. DELETE /v1/sms/webhook desliga o webhook e cancela as entregas que estavam por fazer.
|
«Enviado» quer dizer que saiu para a operadora, não que foi lido. Para o seu sistema, sms.sent é «o aviso partiu» e sms.failed é «tenho de fazer outra coisa». Porquê avisar em vez de perguntar está em webhook ou consulta periódica.
|
|
Quer que o seu sistema saiba sozinho o que aconteceu a cada aviso? Veja a página da API.
Ver a página da API
|
Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
