Links
Comment on page

WhatsApp API

Documentação técnica: WhatsApp API

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.

Pré Requisitos

  1. 1.
    Para utilizar a API da Sinch Messaging, primeiro você deve ter uma conta ativa na plataforma Sinch messaging.
  2. 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. 3.
    Com as credenciais acima, você ja poderá começar a utilizar a API da Sinch Messaging.

Detalhes da conexão

Campo
Descrição
Hostname
api-messaging.wavy.global
Porta
443 (https)
Protocolo
HTTPS (TLS encryption)
Autenticação
username + token
Encoding
UTF-8

Fazendo chamadas para a API da Sinch Messaging

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.

Mensagens:

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

Envio Template

Destinations

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

Destination

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.

Message

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

Template

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.

Element

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

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.

Formato geral de um Webhook

Nome
Conteúdo do objeto
messages
Notificações de mensagens de entrada
statuses
Atualizações de status das mensagens

Status

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

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
420
Message is rate limited
429
Too many requests
5xx
Server Errors
500
Internal server error
504
Timeout

Outros status

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

Mensagens (MO)

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.

HTTP Status Code Response Comuns

Request response com sucesso (200)

{
"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:

Autenticação error response (401)

{
"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:

Atualização de status Callback

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

Dados:

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

ClientInfo

Campo
Detalhes
Tipo
customerId
Identificação do cliente.
Number
subAccountId
Identificação da subconta.
Number
userId
Identificação do usuário.
Number

Status

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.

MO (mensagens enviadas pelo usuário final para a conta do Whatsapp)

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

Controle de Fluxo de MO- Listas de Segmentação

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

Mensagem:

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.