Links

WhatsApp API

Documentación técnica: WhatsApp API.

API de WhatsApp

Esta documentación proporciona información sobre cómo su aplicación puede enviar mensajes de Whatsapp a través de la API utilizando la plataforma Sinch Messaging.
También encontrará información aquí sobre Webhooks, que son devoluciones de llamada HTTP definidas por el usuario que se desencadenan por eventos específicos. Cada vez que ocurra un evento desencadenante, la API de Sinch recopilará los datos e inmediatamente enviará una notificación (solicitud HTTP) a la URL elegida por el cliente, actualizando el estado de los mensajes enviados o indicando cuándo recibe un mensaje.
La API Sinch Messaging permite enviar mensajes individuales o por lotes.
La API tiene integración REST, utilizando el protocolo HTTP con TLS, soportando el método POST con los parámetros enviados en formato JSON.

Requisitos previos

  1. 1.
    Para utilizar la API de mensajería de Sinch, primero debe tener una cuenta activa en la plataforma de mensajería de Sinch.
  2. 2.
    También debe tener un nombre de usuario y un token válidos asociados con esta cuenta.
  3. 3.
    Aprenda cómo crear su usuario en nuestra guía Agregar usuarios. Con las credenciales anteriores, puede comenzar a usar Sinch Messaging API.

Detalhes da conexão

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

Realización de llamadas a la API Sinch Messaging

Para realizar tus primeras llamadas te recomendamos utilizar la aplicación “Cartero” con solicitudes en formato JSON en lugar de empezar a escribir códigos en otros lenguajes.
Nota: Para enviar mensajes de prueba, debe tener una plantilla de mensaje aprobada en su cuenta de WhatsApp Business. Consulte nuestra documentación de creación de plantillas de mensajes de WhatsApp para crear sus primeras plantillas.
Si aún no tiene ningún modelo de mensaje aprobado, aún puede enviar mensajes de prueba, siempre que el destinatario interactúe con el número de origen.
De esta forma, se activará una ventanilla de atención al cliente. Le permite enviar cualquier tipo de mensaje dentro de una ventana de 24 horas. Si el mensaje llega, su solicitud a Sinch Messaging API fue exitosa. De lo contrario, revise su Webhook para ver si hay notificaciones que puedan indicar un problema.

Mensajes:

Las llamadas a la API Sinch Messaging se envían a: https://api-messaging.wavy.global/v1/whatsapp/send en formato POST independientemente del tipo de mensaje, pero el contenido del cuerpo del mensaje JSON varía para cada tipo de mensaje. Los campos de autenticación en el encabezado también seguirán el mismo formato independientemente del tipo de mensaje:
POST /v1/whatsapp/send HTTP/1.1 Host: api-messaging.wavy.global UserName: user_name AuthenticationToken: aaaaaa-bbbbbbbbbbbbbXXXXX12 Content-Type: application/json

Envío de plantilla

Destinations
Nome
Obligatorio
Descripción
destinations
Si
Detalles sobre identificadores de envío y destino
message
Si
Detalles sobre el objeto MESSEGE que se enviará

Destination

Nome
Obligatorio
Descripción
correlationId
No
Id definido por el cliente que será devuelto en el estado del mensaje (devolución de llamada). Puede utilizar esta identificación para realizar un seguimiento de los envíos de mensajes de forma personalizada.
destination
Sim
Número de teléfono que recibirá el mensaje (código de país (55 para Brasil) y código de área son obligatorios). Ejemplos: 5519900001111, +5519900001111, +55(19) 900001111.

Message

Nome
Obligatorio
Descripción
TTL
No
Vida útil en días. Define el número máximo de días que se debe entregar el mensaje. Válido de 1 a 30. Valor por defecto 7 si no se define
Template
Sim
Detalles sobre el objeto TEMPLATE que se enviará

Template

Nome
Obligatorio
Descripción
Namespace
Si
Id. del espacio de nombres que se utilizará. NOTA: Los parámetros namespace y element_name deben coincidir con el Business Manager al que está asociado el número de origen, o el mensaje no se podrá enviar
ElementName
Si
Nombre del modelo registrado y aprobado.
header
Sí, cuando la plantilla tiene un parámetro en el encabezado
Objetos de encabezado con sus parámetros
LanguageCode
Si
Nombre del modelo registrado y aprobado.

Header

Nome
Obligatorio
Descripción
Title
Opcional
El título debe tener hasta 60 caracteres.
Element
Si
Opções:
text (padrão),
image,
audio,
document,
hsm,
video.

Element

Nome
Obligatorio
Descripción
Url
Si
URL de medios. Úselo solo con URL HTTP/HTTPS.
Type
Si
Tipo de medio (JPEG, MP3, PDF, etc.)
Caption
Si
nombre de los medios

Webhooks

Los webhooks (o devoluciones de llamada) son devoluciones de llamada HTTP definidas por el usuario que se desencadenan por eventos específicos. Cada vez que ocurra un evento desencadenante, la API de Sinch recopilará los datos e inmediatamente enviará una notificación (solicitud HTTP) a la URL elegida por el cliente, actualizando el estado de los mensajes enviados o indicando cuándo recibe un mensaje.
Cuando el cliente le envía un mensaje, Sinch Messaging API enviará una notificación de solicitud HTTP POST a la URL del webhook con los detalles.
Es importante que su webhook devuelva una respuesta HTTPS 200 OK a las notificaciones (dentro de 200 ms o de forma asíncrona). De lo contrario, Sinch Messaging API considerará que esta notificación ha fallado y volverá a intentarlo después de un retraso.
Importante: Nuestro equipo de soporte debe configurar la URL donde recibirá los Webhooks.

Formato geral de um Webhook

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

Estado

Estado
Descripción
Equivalente móvil de WhatsApp
SENT_SUCCESS
Mensaje recibido por el servidor de WhatsApp
una marca de verificación
DELIVERED_SUCCESS
Mensaje entregado al destinatario
dos marcas de verificación
READ_SUCCESS
Mensaje leído por el destinatario
Dos marcas de verificación azules

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 envío
código de entrega
Estado
Significado
102
CARRIER COMMUNICATION ERROR
Error al cargar medios a WhatsApp
103
REJECTED_BY_CARRIER
Ocurrió un error en la base de datos
2
101
EXPIRED
mensaje caducado
2
104
NOT_DELIVERED
Posibles Causas: Se ha alcanzado el límite: se han intentado demasiados envíos de mensajes. o no se pudo enviar el mensaje porque el número de teléfono objetivo es parte de un experimento, o la estructura de la plantilla no existe, o no se pudo enviar el mensaje porque el número de destino está fuera de la ventana de servicio de 24 horas para recibir mensajes de formato libre. o hubo un error de carga de medios (error desconocido), o no pudo enviar el mensaje porque su cuenta no es elegible en Facebook Business Manager, o hubo un error de carga temporal. Vuelva a intentarlo más tarde.
202
INVALID_DESTINATION_NUMBER
Contacto de WhatsApp inválido
204
DESTINATION_BLOCKED_BY_OPTOUT
Destino bloqueado por exclusión voluntaria
206
INVALID_MESSAGE_LENGTH
mensaje demasiado largo
207
INVALID_MESSAGE_TEXT
El valor del parámetro no es válido
209
INVALID_CONTENT
Tipo de mensaje DESCONOCIDO no válido
210
INVALID_SESSION
La ventana de sesión o de escucha no está abierta y no se ha configurado ninguna plantilla alternativa
311
INTERNAL_ERROR
No se pueden verificar los contactos de la API de WhatsApp

Mensajes (MO)

Cuando el cliente le envía un mensaje, Sinch Messaging API enviará una notificación de solicitud HTTP POST a la URL del webhook con los detalles.
Cuando el cliente le envía un mensaje, Sinch Messaging API enviará una notificación de solicitud HTTP POST a la URL del webhook con los detalles. Es importante que su webhook devuelva una respuesta HTTPS 200 OK a las notificaciones (dentro de 200 ms o de forma asíncrona). De lo contrario, Sinch Messaging API considerará que esta notificación ha fallado y volverá a intentarlo después de un retraso.
Importante: Nuestro equipo de soporte debe configurar la URL donde recibirá los Webhooks.

Respuesta de código de estado HTTP común

Solicitud de respuesta exitosa (200)

Si la solicitud se ejecuta con éxito, se devolverá la lista de destinos con los uuid generados:
{
"Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
"destination": [{
"id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
"correlationId": "MyCorrelationId",
"destination": "5519900001111."
}]
}

Respuesta de error de autenticación (401)

Si hay un problema con la autenticación, se devolverá el siguiente mensaje:
{
"errorCode": 401,
"errorMessage": "Autenticação Error: No user was found with this combination of username and Autenticação token."
}

Actualización de estado de devolución de llamada

Ejemplo
{
"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
}
],
"clientInfo": {
"customerId": 42,
"subAccountId": 1291,
"userId": 1
}
}
Cada actualización del estado de los mensajes enviados (confirmación de entrega al usuario final, lectura de mensajes, etc.), se envía una devolución de llamada/webhook. Las devoluciones de llamada se envían por lotes.
Importante: Nuestro equipo de soporte y operaciones debe configurar el punto final que usará el webhook para enviar los estados.
El formato de devolución seguirá la siguiente descripción:
Campo
Detalles
Tipo
total
Número de devoluciones de llamada en la llamada.
String
data
Lista de devolución de llamada.
Data[]
clientInfo
Información al cliente.
ClientInfo

Dados:

Campo
Detalles
Tipo
id
identificación del último mensaje
String
correlationId
Una ID única definida por usted para que coincida con el estado del mensaje (Devolución de llamada y DLR). Este parámetro es opcional y puede utilizar el ID generado por Sinch Messaging para realizar la comparación.
String
destination
Número de teléfono al que se envió el mensaje (incluido el código de país). Ejemplo: 5511900000000.
String
origin
Número de telefone que Número de teléfono al que se envió el mensaje (incluido el código de país). Ejemplo: 5511900000000.
String
campaignId
ID de campaña definido anteriormente.
String
campaignAlias
Alias ​​de campaña definido anteriormente.
String
extraInfo
Información adicional enviada con el mensaje original.
String
sent
Indica si el mensaje fue enviado.
Boolean
sentStatusCode
Código de estado generado por Sinch Messaging para el mensaje que indica el estado de envío.
Number
sentStatus
Descripción del estado del envío.
Boolean
sentDate
Fecha en que se envió el mensaje. formato: aaaa-MM-dd'T'HH:mm:ssZ.
String
sentAt
Hora en que se envió el mensaje, utilizando el formato de hora Unix
Number
delivered
Indica si el mensaje se entregó en el destino.
Boolean
deliveredStatusCode
Código de estado generado por Sinch Messaging que indica si el mensaje fue entregado.
Number
deliveredStatus
Descripción del estado de entrega.
String
deliveredDate
Fecha en que se entregó el mensaje. formato:: aaaa-MM-dd'T'HH:mm:ssZ
String
deliveredAt
Tempo em que a mensagem foi entregue, usando Unix_time format
Number
read
Indica si el destinatario ha leído el mensaje.
Boolean
readDate
Fecha en que se leyó el mensaje. formato: aaaa-MM-dd'T'HH:mm:ssZ
String
readAt
Hora en que se leyó el mensaje, utilizando el formato Unix Time
String
updatedDate
Fecha en que se actualizó el estado del mensaje. Formato: aaaa-MM-dd'T'HH:mm:ssZ
String
updatedAt
Fecha en que se actualizó el estado del mensaje, utilizando el formato Unix_time
String

ClientInfo

Campo
Detalhes
Tipo
customerId
Identificación del cliente.
Number
subAccountId
ID de subcuenta.
Number
userId
Identificación de usuario.
Number

Status

Status que podem ser enviados no callback:
Status
Código de envio
Código de entrega
Significado
CARRIER_COMMUNICATION_ERROR
102
Error al cargar medios a WhatsApp.
REJECTED_BY_CARRIER
103
Ocurrió un error en la base de datos.
SENT_SUCCESS
2
EXPIRED
2
101
Mensaje caducado.
No se pudo enviar el mensaje porque es demasiado antiguo.
NOT_DELIVERED
2
104
Se alcanzó el límite: se intentaron demasiados envíos de mensajes.
DELIVERED_SUCCESS
2
4
READ_SUCCESS
2
5
INVALID_DESTINATION_NUMBER
202
Contacto de WhatsApp no ​​válido.
DESTINATION_BLOCKED_BY_OPTOUT
204
Destino bloqueado por OptOut.
INVALID_MESSAGE_LENGTH
206
Mensaje demasiado largo.
INVALID_MESSAGE_TEXT
207
El valor del parámetro no es válido.
INVALID_CONTENT
209
Tipo de mensaje DESCONOCIDO no válido.
INVALID_SESSION
210
La sesión no está abierta y no se ha configurado ningún HSM de respaldo.
DESTINATION_BLOCKED_BY_OPTIN
211
DESTINATION_BLOCKED_BY_WHITELIST
212
INTERNAL_ERROR
311
No es posible verificar los contactos de la API de WhatsApp.

MO (mensajes enviados por el usuario final a la cuenta de Whatsapp)

Ejemplo de mensaje 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"
}
]
}
Ejemplo de información adicional:
{
"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
}
]
}
Ejemplo de mensaje multimedia
{
"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"
}
]
}
Ejemplo de mensaje de ubicación:
{
"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"
}
]
}
Ejemplo de mensaje de contacto:
{
"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 respuesta del usuario final (MO o Mobile Origined) se envía una devolución de llamada/webhook. Estos MO se envían por lotes.
Importante: Nuestro equipo de soporte y operaciones debe configurar el punto final que usará el webhook para enviar los estados.
Importante: Nuestro equipo de soporte y operaciones debe configurar el punto final que usará el webhook para enviar los estados.
Campo
Detalles
Tipo
total
Números de devolución de llamada para la llamada.
String
data
Lista de mensajes con origen móvil (MO).
Data[]

Dados

Campo
Detalles
Tipo
id
Identificación del último mensaje
String
source
Número de teléfono del remitente
String
origin
Número de teléfono que identifica la Cuenta de WhatsApp (incluyendo código de país). Ejemplo: 5511900000000.
String
userProfile
Perfil del usuario que envió el mensaje
UserProfile
correlationId
Una ID única definida por usted para que coincida con el estado del mensaje (Devolución de llamada y DLR). Este parámetro es opcional y puede usar la ID generada por Sinch Messaging para hacer la comparación.
String
campaignId
ID de campaña definido anteriormente.
String
campaignAlias
Alias ​​de campaña definido anteriormente.
String
mensagem
Mensaje MO.
mensagem
receivedAt
Fecha en que se recibió el mensaje. Formato: aaaa-MM-dd'T'HH:mm:ssZ
String
receivedDate
Fecha en que se recibió el mensaje, utilizando el formato de hora Unix
String
extraInfo
Información adicional relacionada con el mensaje. Formato: JSON
String

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

El mensaje tendrá una lista de listas de orientación en el campo extraInfo. Nuestros socios lo usan para dirigir mensajes a ciertos flujos. El nombre de la clave es segmentation_lists y contiene una lista de SegmentationList.
Campo
Detalles
Tipo
id
Identificador de lista de segmentación
Integer
customerId
identificador de cliente
Integer
subAccountId
identificador de subcuenta
Integer
name
Nombre de la lista de objetivos
String
active
Estado de la lista de objetivos
Boolean

Mensaje:

Campo
Detalles
Tipo
type
Tipo de mensaje enviado al usuario final: TEXTO - IMAGEN - AUDIO - DOCUMENTO
String
messageText
El mensaje de texto (MO) enviado por el usuario final.
String
waGroupId
Grupo al que se envió el mensaje.
String
mediaUrl
Url para descargar los medios enviados por el usuario final.
String
mimeType
Tipo Mime del archivo enviado por el usuario final.
String
caption
Etiqueta de medios enviada por el usuario final.
String
location
Ubicación enviada por el usuario final.
Location
contacts
Contactos enviados por el usuario final.
Contact[]

UserProfile:

Campo
Obligatorio
Detalles
Tipo
name
Não
Nombre de perfil de usuario
String

Location:

Campo
Detalles
Tipo
name
Nombre del lugar.
String
address
Dirección del sitio.
String
geoPoint
Geopunto enviado por el usuario final. Formato: "latitud, longitud"
String

Contact:

Campo
Obligatorio
Detalles
Tipo
addresses
No
Dirección(es) completa(s) del contacto.
Address[]
birthday
No
Cumpleaños en formato AAAA-MM-DD.
String