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

cURL

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

Ruby

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

Python

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

PHP

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

Java

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

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