Callbacks de Eventos¶
A DUO pode avisar a sua aplicação quando acontece algo a uma mensagem enviada: entrega, bounce,
abertura, clique ou cancelamento da subscrição. Indique um URL no parâmetro event_callback e a
DUO envia um pedido POST para esse URL com o evento e os contactos a que diz respeito.
Onde definir o URL¶
| Tipo de envio | Onde | Parâmetro |
|---|---|---|
| Campanhas (email e SMS) | POST /campaign ou PUT /campaign/<campaign> |
event_callback |
| Mensagens transacionais | Cada pedido de envio | event_callback |
Aviso
Nas mensagens transacionais, o URL tem de ser enviado em cada pedido de envio. O campo
event_callback da própria mensagem transacional é guardado, mas não é usado nos callbacks.
O URL tem de usar http ou https e incluir um anfitrião e um caminho, p. ex.
https://example.com/duo/events. Use https.
Eventos¶
event |
Significado | SMS | |
|---|---|---|---|
submitted |
A mensagem foi submetida para entrega | ✓ | |
delivered |
A mensagem foi entregue | ✓ | ✓ |
bounced |
A mensagem não foi entregue por um erro permanente | ✓ | ✓ |
opened |
A mensagem foi aberta | ✓ | |
clicked |
Foi clicado um link da mensagem | ✓ | |
unsubscribed |
O contacto cancelou a subscrição através do link de cancelamento | ✓ |
Não há evento para queixas de spam.
O pedido¶
A DUO envia um POST com Content-Type: application/x-www-form-urlencoded para o URL, sem a
query string. O corpo tem estes campos:
| Campo | Tipo | Descrição |
|---|---|---|
event |
string | O evento, como na tabela acima |
when |
int | Unix timestamp do evento, arredondado ao minuto |
email[<n>] |
string | Email de cada contacto a que o evento diz respeito. Vazio se o contacto não tiver email. |
telephone[<n>] |
string | Telefone de cada contacto. Vazio se o contacto não tiver telefone. |
Os eventos são agrupados antes do envio. Cada pedido diz respeito a um tipo de evento de uma
campanha ou mensagem transacional, e inclui todos os contactos a que se aplica nesse período,
com o mesmo índice <n> em email[], telephone[] e em qualquer campo por contacto. O pedido
pode chegar até cinco minutos depois do evento.
Exemplo de corpo do pedido (descodificado):
event=delivered
when=1793701080
email[0]=ana@example.com
telephone[0]=351910000001
email[1]=bruno@example.com
telephone[1]=
Acrescentar campos seus¶
Os parâmetros da query string do URL do event_callback passam para o corpo do pedido.
- Um valor fixo é enviado sem alterações, uma vez por pedido. Use-o para identificar a origem ou para enviar um token secreto (ver Entrega e segurança).
- Um marcador é substituído pelo valor de cada contacto e enviado como array, com o mesmo índice
do
email[].
| Marcador | Valor |
|---|---|
%CustomField:<id>% |
O valor do contacto no campo personalizado <id> da lista |
%List:ID% |
O ID da lista de contactos |
%EventPayload:externalid% |
Só SMS transacional: o valor de externalid[] enviado com a mensagem |
Os marcadores têm de estar codificados no URL: %CustomField:42% escreve-se
%25CustomField%3A42%25.
Exemplo: com este URL de callback
a DUO envia POST https://example.com/duo/events com:
source=newsletter
token=s3cr3t
event=opened
when=1793701080
email[0]=ana@example.com
telephone[0]=351910000001
customer[0]=C-1001
Entrega e segurança¶
- Sem novas tentativas. Cada pedido é enviado uma vez. A DUO não lê a resposta e um pedido falhado não é repetido. Se precisar de todos os eventos, use também os endpoints de estatísticas, como Estatísticas da Campanha ou Estatísticas Transacionais.
- Sem assinatura. Os pedidos não são assinados. Para confirmar que um pedido vem da DUO, ponha um token secreto na query string do URL, como no exemplo acima, e compare-o do seu lado.
- Responda depressa com qualquer estado
2xxe processe os eventos depois. - Conte com duplicados e falhas. Prepare o recetor para que processar o mesmo evento duas vezes não cause problemas.