Comment on page
WhatsApp API
Documentação técnica: WhatsApp API
Esta documentação fornece informações sobre como sua aplicação poderá enviar as mensagens de Whatsapp via API utilizando a plataforma Sinch Messaging.
Você também encontrará aqui informações sobre Webhooks que 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.
A API da Sinch Messaging permite o envio de mensagens únicas ou em lote.
A API possui integração REST, utilizando o protocolo HTTP com TLS, suportando o método POST com os parâmetros enviados em formato JSON.
- 1.Para utilizar a API da Sinch Messaging, primeiro você deve ter uma conta ativa na plataforma Sinch messaging.
- 2.Você também deverá ter usuário e token válidos associados a essa conta. Saiba como criar seu usuário no nosso guia Adicionar usuários.
- 3.Com as credenciais acima, você ja poderá começar a utilizar a API da Sinch Messaging.
Campo | Descrição |
|---|---|
Hostname | api-messaging.wavy.global |
Porta | 443 (https) |
Protocolo | HTTPS (TLS encryption) |
Autenticação | username + token |
Encoding | UTF-8 |
Para fazer suas primeiras chamadas, recomendamos o uso do aplicativo “Postman” com requisições no formato JSON ao invés de já iniciar escrevendo códigos em outras linguagens.
Nota: Para enviar mensagens de teste, você precisa ter um modelo de mensagem aprovado na sua conta do WhatsApp Business. Consulte nossa documentação sobre Criação de modelo de mensagem WhatsApp para criar seus primeiros modelos.
Caso você ainda não tenha nenhum modelo de mensagem aprovado você ainda pode enviar mensagens teste, desde que o destinatário faça uma interação com o número de origem.
Dessa forma, uma janela de atendimento ao cliente será ativada. Ela permite que você envie qualquer tipo de mensagem em uma janela de 24 horas. Se a mensagem chegar, significará que sua requisição à API da Sinch Messaging foi bem-sucedida. Caso contrário, verifique seu Webhook em busca de notificações que possam indicar algum problema.
As chamadas para a API da Sinch Messaging são enviadas para:
https://api-messaging.wavy.global/v1/whatsapp/send
no formato POST independentemente do tipo de mensagem, mas o conteúdo do corpo da mensagem JSON varia para cada tipo de mensagem.
Os campos de autenticação no header também seguirão o mesmo formato em independentemente do tipo de mensagem:
POST /v1/whatsapp/send HTTP/1.1
Host: api-messaging.wavy.global
UserName: user_name
AuthenticationToken: aaaaaa-bbbbbbbbbbbbbXXXXX12
Content-Type: application/json
Nome | Obrigatório | Descrição |
destinations | Sim | Detalhes sobre os identificadores do envio e destino |
message | Sim | Detalhes sobre o objeto MESSAGE que será enviado |
Nome | Obrigatório | Descrição |
correlationId | Não | Id definido pelo cliente que será retornado no status da mensagem (callback). Você pode usar esse id para rastrear envios de mensagens de maneira personalizada. |
destination | Sim | Número de telefone que receberá a mensagem (código do país (55 para Brasil) e DDD são obrigatórios). Exemplos: 5519900001111, +5519900001111, +55(19) 900001111. |
Nome | Obrigatório | Descrição |
ttl | Não | Tempo de vida em dias. Define o número máximo de dias em que a mensagem deve ser entregue. Válido de 1 a 30. Valor padrão 7 se não definido. |
template | Sim | Detalhes sobre o objeto TEMPLATE que será enviado |
Nome | Obrigatório | Descrição |
namespace | Sim | ID do namespace que será usado. NOTA: Os parâmetros namespace e element_name devem corresponder ao Business Manager que o número de origem está associado, ou a mensagem terá falha no envio. |
elementName | Sim | Nome do modelo cadastrado e aprovado. |
header | Sim, quando o Template possuir parametro no header | Objetos do cabeçalho com seus parâmetros |
languageCode | Sim | Nome do modelo cadastrado e aprovado. |
Nome | Obrigatório | Descrição |
title | Opcional | O título deve ter até 60 caracteres |
element | Sim | Opções: text (padrão), image, audio, document, hsm, video. |
Nome | Obrigatório | Descrição |
url | Sim | URL da mídia. Use somente com URLs HTTP/HTTPS. |
type | Sim | Tipo da mídia (JPEG, MP3, PDF, etc) |
caption | Sim | Nome da mídia |
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.
Nome | Conteúdo do objeto |
messages | Notificações de mensagens de entrada |
statuses | Atualizações de status das mensagens |
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 |
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 |
420 | Message is rate limited |
429 | Too many requests |
5xx | Server Errors |
500 | Internal server error |
504 | Timeout |
Código de envio | Código de entrega | Status | Descrição |
102 | | CARRIER COMMUNICATION ERROR | Erro ao fazer upload de mídia para o WhatsApp |
103 | | REJECTED_BY_CARRIER | Ocorreu erro de banco de dados |
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 porque 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.
|
202 | | INVALID_DESTINATION_NUMBER | Contato de WhatsApp inválido |
204 | | DESTINATION_BLOCKED_BY_OPTOUT | Destino bloqueado por Opt-Out |
206 | | INVALID_MESSAGE_LENGTH | Mensagem muito longa |
207 | | INVALID_MESSAGE_TEXT | Valor de parâmetro não é vá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 |
311 | | INTERNAL_ERROR | Não é possível verificar contatos da API do WhatsApp |
| | | |
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.
{
"Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
"destination": [{
"id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
"correlationId": "MyCorrelationId",
"destination": "5519900001111."
}]
}
Se a requisição for executada com sucesso, a lista de destinos com os uuids gerados será retornado:
{
"errorCode": 401,
"errorMessage": "Autenticação Error: No user was found with this combination of username and Autenticação token."
}
Se ocorrer um problema com a autenticação, a seguinte mensagem será retornada:
Exemplo
{
"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
"templateInfo": {
"status": "APPROVED",
"quality": "GREEN"
}
}
],
"clientInfo": {
"customerId": 42,
"subAccountId": 1291,
"userId": 1
}
}
Toda atualização do status de mensagens enviadas (confirmação de entrega ao usuário final, leitura da mensagem, etc), um callback/webhook é enviado. Callbacks são enviados em lote.
Importante: O endpoint em que o webhook utilizará para enviar os status precisa ser configurado por nosso time de suporte e operações.
O formato do retorno seguirá a seguinte descrição:
Campo | Detalhes | Tipo |
total | Número de callbacks na ligação. | String |
data | Lista de Callbacks. | Data[] |
clientInfo | Informações do cliente. | ClientInfo |
Campo | Detalhes | Tipo |
id | Último id da mensagem | String |
correlationId | Um ID unico definido por voce para comparar com o status da mensagem (Callback and DLR). Este parametro é opcional, e voce pode usar o ID gerado pelo Sinch Messaging para fazer a comparação. | String |
destination | Número de telefone que a mensagem foi enviada (incluindo código de pais). Exemplo: 5511900000000. | String |
origin | Número de telefone que identifica a Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. | String |
campaignId | campaignID definido anteriormente. | String |
campaignAlias | Campaign alias definido anteriormente. | String |
extraInfo | Informação extra enviada com a mensagem original. | String |
sent | Indica se a mensagem foi enviada. | Boolean |
sentStatusCode | Code de Status gerado pelo Sinch Messaging 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 | Tempo 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 pelo Sinch Messaging 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 | Tempo 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 | Tempo 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 | Data em que o status da mensagem foi atualizado, usando Unix_time format | String |
Campo | Detalhes | Tipo |
customerId | Identificação do cliente. | Number |
subAccountId | Identificação da subconta. | Number |
userId | Identificação do usuário. | Number |
Status que podem ser enviados no callback:
Status | Código de envio | Código de entrega | Significado |
CARRIER_COMMUNICATION_ERROR | 102 | | Erro ao fazer upload de mídia para o WhatsApp. |
REJECTED_BY_CARRIER | 103 | | Ocorreu erro de banco de dados. |
SENT_SUCCESS | 2 | | |
EXPIRED | 2 | 101 | Mensagem expirada. |
| | | Falhou ao enviar mensagem porque ela é muito antiga. |
NOT_DELIVERED | 2 | 104 | Limite atingido - muitos envios de mensagens tentados. |
| | | Falhou ao enviar mensagem porque o número de telefone deste usuário é parte de um experimento. |
| | | Estrutura indisponível: Cliente não é capaz de mostrar HSM. |
| | | Falhou ao enviar mensagem porque você está fora da janela de suporte para mensagens de forma livre para este usuário. Por favor use uma notificação HSM válida ou reconsidere. |
| | | Erro de upload de mídia (erro desconhecido). |
| | | Falha ao enviar mensagem porque sua conta é inelegível.Por favor verifique sua conta WhatsApp Business. |
| | | Falha temporária de upload. Tente novamente mais tarde. |
DELIVERED_SUCCESS | 2 | 4 | |
READ_SUCCESS | 2 | 5 | |
INVALID_DESTINATION_NUMBER | 202 | | Contato de WhatsApp inválido. |
DESTINATION_BLOCKED_BY_OPTOUT | 204 | | Destino bloqueado por OptOut. |
INVALID_MESSAGE_LENGTH | 206 | | Mensagem muito longa. |
INVALID_MESSAGE_TEXT | 207 | | Valor de parâmetro não é válido. |
INVALID_CONTENT | 209 | | Tipo de mensagem UNKNOWN inválido. |
INVALID_SESSION | 210 | | Sessão não está aberta e nenhum HSM de fallback está configurado. |
DESTINATION_BLOCKED_BY_OPTIN | 211 | | |
DESTINATION_BLOCKED_BY_WHITELIST | 212 | | |
INTERNAL_ERROR | 311 | | Não é possível verificar contatos da API do WhatsApp. |
PAUSED_TEMPLATE | 113 | | O template está pausado devido a baixa qualidade e não pode ser enviado. |
Exemplo de mensagem de texto:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"type": "TEXT",
"messageText": "Olá, essa é uma mensagem do usuário."
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de Extra Info:
{
"segmentation_list":[
{
"id":26,
"customerId":42,
"subAccountId":0,
"name":"Sinch WhatsApp Segmentation List",
"active":true
},
{
"id":27,
"customerId":43,
"subAccountId":0,
"name":"Sinch WhatsApp Segmentation List 2",
"active":true
}
]
}
Exemplo de mensagem de mídia
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"type": "IMAGE",
"mediaUrl": "https://...",
"mimeType": "image/jpg",
"caption": "..."
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de mensagem de localização:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"location": {
"geoPoint": "-22.894180,-47.047960",
"name": "Sinch",
"address": "Av. Cel. Silva Telles"
}
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de mensagem de contato:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"contacts":[
{
"addresses":[
{
"city":"Menlo Park",
"country":"United States",
"country_code":"us",
"state":"CA",
"street":"1 Hacker Way",
"type":"HOME",
"zip":"94025"
},
{
"city":"Menlo Park",
"country":"United States",
"country_code":"us",
"state":"CA",
"street":"200 Jefferson Dr",
"type":"WORK",
"zip":"94025"
}
],
"birthday":"2012-08-18",
"emails":[
{
"email":"[email protected]",
"type":"WORK"
},
{
"email":"[email protected]",
"type":"WORK"
}
],
"name":{
"first_name":"John",
"formatted_name":"John Smith",
"last_name":"Smith"
},
"org":{
"company":"WhatsApp",
"department":"Design",
"title":"Manager"
},
"phones":[
{
"phone":"+1 (940) 555-1234",
"type":"HOME"
},
{
"phone":"+1 (650) 555-1234",
"type":"WORK",
"wa_id":"16505551234"
}
],
"urls":[
{
"url":"https://www.fb.com",
"type":"WORK"
}
]
}
]
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Cada resposta do usuário final (MO ou Mobile Originated) um callback/webhook é enviado. Essas MOs são enviadas em lote.
Importante: O endpoint em que o webhook utilizará para enviar os status precisa ser configurado por nosso time de suporte e operações.
O formato do retorno seguirá a seguinte descrição:
Campo | Detalhes | Tipo |
total | Números de callbacks para a ligação. | String |
data | Lista de mensagens Mobile Originated (MO). | Data[] |
Campo | Detalhes | Tipo |
id | Última identificação da mensagem | String |
source | Número de telefone do remetente | String |
origin | Número de telefone que identifica a Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. | String |
userProfile | Perfil do usuário que enviou a mensagem | UserProfile |
correlationId | Um ID único definido por voce para comparar com o status da mensagem (Callback and DLR). Este parâmetro é opcional, e voce pode usar o ID gerado pelo Sinch Messaging para fazer a comparação. | String |
campaignId | campaignID definido anteriormente. | String |
campaignAlias | Campaign alias definido anteriormente. | String |
mensagem | Mensagem MO. | mensagem |
receivedAt | Data em que a mensagem foi recebida. Format: yyyy-MM-dd’T'HH:mm:ssZ | String |
receivedDate | Data em que a mensagem foi recebida, usando Unix_time format | String |
extraInfo | Informação extra relacionada com a mensagem. Formato: Json | String |
A mensagem terá uma lista de listas de segmentação no campo de extraInfo. Nossos parceiros a utilizam para direcionar as mensagens para certos fluxos. O nome da chave é segmentation_lists e ela contém uma lista de SegmentationList.
Campo | Detalhes | Tipo |
id | Identificador da lista de segmentação | Integer |
customerId | Identificador do cliente | Integer |
subAccountId | Identificador da subconta | Integer |
name | Nome da lista de segmentação | String |
active | Status da lista de segmentação | Boolean |
Campo | Detalhes | Tipo |
type | Tipo de mensagem enviada para o usuário final: TEXT - IMAGE - AUDIO - DOCUMENT | String |
messageText | A mensagem de texto (MO) enviada pelo usuário final. | String |
waGroupId | Grupo ao qual a mensagem foi enviada. | String |
mediaUrl | Url para download da mídia enviada pelo usuário final. | String |
mimeType | Mime type do arquivo enviado pelo usuário final. | String |
caption | Media label enviada pelo usuário final. |