Webhooks
Webhooks (ou callbacks) são retornos de chamada de HTTP definidos pelo usuário, que são acionados por eventos específicos. Sempre que ocorrer um evento de acionamento, a API da Sinch coletará os dados e imediatamente enviará uma notificação (solicitação HTTP) a URL escolhida pelo cliente atualizando o status das mensagens enviadas ou indicando quando você receber uma mensagem.
Quando o cliente enviar uma mensagem a você, API da Sinch Messaging enviará uma notificação de solicitação HTTP POST à URL do Webhook com os detalhes.
É importante que seu Webhook retorne uma resposta HTTPS 200 OK às notificações (em até 200 ms ou de maneira assíncrona). Caso contrário, a API da Sinch Messaging considerará essa notificação com falha e tentará novamente após um atraso.
Importante: A URL onde você irá receber os Webhooks precisa ser configurado por nosso time de suporte.
O formato do retorno seguirá a seguinte descrição:
| Campo | Detalhes | Tipo |
|---|---|---|
total | Número de callbacks retornados. | String |
data | Dados retornados no Callback. | Data[] |
clientInfo | Informações do cliente. | ClientInfo |
conversationID | String |
Data:
| Campo | Detalhes | Tipo |
|---|---|---|
id | id da mensagem. | String |
correlationId | Caso tenha sido especificado um correlationId no envio da mensagem, ele irá aparecer aqui. | String |
destination | Número do telefone que a mensagem foi enviada (incluindo código de pais). Exemplo: 5511900000000. | String |
origin | Número da Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. | String |
campaignId | Caso tenha sido especificado um campaignID no envio da mensagem, ele irá aparecer aqui. | String |
campaignAlias | Caso tenha sido especificado um campaignAlias no envio da mensagem, ele irá aparecer aqui. | String |
extraInfo | Informação extra enviada com a mensagem original. | String |
sent | Indica se a mensagem foi enviada. | Boolean |
sentStatusCode | Código de Status gerado pela Sinch Messaging WhatsApp API para a mensagem indicando o status de envio. | Number |
sentStatus | Descrição do status de envio. | Boolean |
sentDate | Data em que a mensagem foi enviada. Formato: yyyy-MM-dd’T'HH:mm:ssZ. | String |
sentAt | Horário em que a mensagem foi enviada, usando Unix_time format | Number |
delivered | Indica se a mensagem foi entregue no destino. | Boolean |
deliveredStatusCode | Código de Status gerado pela Sinch Messaging WhatsApp API indicando se a mensagem foi entregue. | Number |
deliveredStatus | Descrição do status de entrega. | String |
deliveredDate | Data em que a mensagem foi entregue. Formato:: yyyy-MM-dd’T'HH:mm:ssZ | String |
deliveredAt | Horário em que a mensagem foi entregue, usando Unix_time format | Number |
read | Indica se a mensagem foi lida pelo destinatário. | Boolean |
readDate | Data em que a mensagem foi lida. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
readAt | Horário em que a mensagem foi lida, usando Unix_time format | String |
updatedDate | Data em que o status da mensagem foi atualizado. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
updatedAt | Horário em que o status da mensagem foi atualizado, usando Unix_time format | String |
type | O tipo de entidade a que se refere este objeto de status. Atualmente, a única opção disponível é “mensagem”. | String |
Exemplo de requisição com Webhook
ClientInfo:
| Campo | Detalhes | Tipo |
|---|---|---|
customerId | Código de identificação do cliente. | Number |
subAccountId | Código de identificação da subconta. | Number |
userId | Código de identificação do usuário. | Number |
Status
Descrição dos Status que podem ser enviados no callback:
| Status | Descrição | Equivalente ao WhatsApp para dispositivos móveis |
|---|---|---|
SENT_SUCCESS | Mensagem recebida pelo servidor do WhatsApp | Uma marca de seleção |
DELIVERED_SUCCESS | Mensagem entregue para o destinatário | Duas marcas de seleção |
READ_SUCCESS | Mensagem lida pelo destinatário | Duas marcas de seleção azuis |
Outros Status
Esses são os códigos retornados nos campos sentStatusCode e deliveredStatusCode.
| Código de envio | Código de entrega | Status | Significado |
|---|---|---|---|
102 | CARRIER COMMUNICATION ERROR | Erro ao fazer upload de mídia para o WhatsApp | |
103 | REJECTED_BY_CARRIER | Ocorreu erro de comunicação com o WhatsApp. | |
2 | 101 | EXPIRED | Mensagem expirada. |
2 | 104 | NOT_DELIVERED | Possíveis Causas: Limite atingido - muitos envios de mensagens tentados; Ou falha ao enviar mensagem porque o número de telefone de destino é parte de um experimento; Ou a estrutura do template não existe; Ou falhou ao enviar mensagem pois o número de destino está fora da janela de atendimento de 24h para receber mensagens de forma livre; Ou houve erro de upload de mídia (erro desconhecido); Ou falha ao enviar mensagem porque sua conta é inelegível no Facebook Business Manager; Ou houve falha temporária de upload. Tente novamente mais tarde. |
2 | 105 | WA_MO_MEDIA_UNRETRYABLE_EXCEPTION | |
202 | EXPIREDINVALID_DESTINATION_NUMBER | Contato de WhatsApp inválido. | |
204 | DESTINATION_BLOCKED_BY_OPTOUT | Destino bloqueado por Opt-Out. | |
207 | INVALID_MESSAGE_TEXT | Valor de parâmetro inválido. | |
209 | INVALID_CONTENT | Tipo de mensagem UNKNOWN inválido. | |
210 | INVALID_SESSION | Sessão ou janela de atendimento não está aberta e nenhum Template de fallback está configurado. | |
301 | INTERNAL_ERROR | Não foi possível verificar o contato na API do WhatsApp. |
Erros
HTTP Code | Description |
2xx | Success |
200 | Success (OK) |
201 | Successfully created (For POST requests) |
302 | Found |
4xx | Client Errors |
400 | Request was invalid |
401 | Unauthorized |
403 | Forbidden |
404 | Not found |
405 | Method not allowed |
412 | Precondition failed |
429 | Too many requests |
5xx | Server Errors |
500 | Internal server error |
504 | Timeout |
Last updated