Esta documentación le proporciona información para la integrarse con la plataforma ChatClub para enviar y recibir mensajes a través de la integración WhatsApp de Wavy, así como información para recibir notificaciones de estado (CallBack - WebHook). La plataforma ChatClub permite enviar mensajes simples y masivos de WhatsApp. La API tiene una integración REST, usando el protocolo HTTP con TLS, que admite el método POST con parámetros enviados en formato JSON.
Autenticacion de usuario
Para utilizar con éxito nuestra API, debe disponer de un nombre de usuario o correo electrónico válidos y el token de autenticación asociado. Al crear la solicitud, debe proporcionar los siguientes parámetros en los encabezados:
Campo
Detalles
Tipo
UserName
Nombre o correo electrónico válido para la identificación del usuario en ChatClub.
String
AuthenticationToken
Token de autenticación generado por nuestra plataforma. Encuéntrelo aquí o consulte a soporte. aquí
String
Detalles de la conexión
Nombre del host
api-messaging.wavy.global
Puerto
443 (https)
Protocolo
HTTPS (TLS encryption)
Autenticación
username + token
Codificación
UTF-8
Enviar mensajes
Envío de mensajes de texto
Permite que los mensajes se envíen a través de la plataforma de WhatsApp a uno o más destinatarios.
POST https://api-messaging.wavy.global/v1/whatsapp/send
El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:
Campo
Necesario
Detalles
Tipo
destinations
Si
Lista de destinatarios
Destination
message
Si
Mensaje de texto que se enviará a la lista de destinatarios
Message
flowId
No
Identificación del flujo de Bot
String
defaultExtraInfo
No
Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje
String
campaignAlias
No
ID de campaña, está vinculado a todos los mensajes del envío
String
Destino:
Campo
Necesario
Detalles
Tipo
correlationId
No
Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos.
String
destination
Si
Número de teléfono (código de país y estado deben estar presentes) o el WhatsApp group ID al que se enviará el mensaje. Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111.
String
recipientType
No
Debe ser "individual" o "group", dependiendo de si el campo destination es un número de teléfono o un group ID.
String
Mensaje:
Campo
Necesario
Detalles
Tipo
messageText
Si
Campo utilizado en caso de que desee enviar un mensaje personalizado como respuesta a un mensaje recibido.
text
image
Si
Campo utilizado en caso de que desee enviar un contenido de imagen.
Image
audio
Si
Campo utilizado en caso de que desee enviar un contenido de audio.
Audio
document
Si
Campo utilizado en caso de que desee enviar un archivo o documento.
Document
contacts
Si
Campo utilizado en caso de que desee enviar contactos.
Contact[]
previewFirstUrl
No
Controla la vista previa de la aplicación de la primera URL enviada
Boolean
location
Si
Campo utilizado en caso de que desee enviar una ubicacion.
Location
Solo una de las siguientes opciones de midia debe ser especificado, ya sea ‘messageText’, ‘image’, ‘audio’, ‘document’, ‘location’ o ‘contacts’
Texto:
Solo se debe enviar un mensaje personalizado como respuesta a un mensaje recibido por el usuario siempre cuando la sesión se encuentre abierta. Si la sesión no está abierta o el usuario no envió un mensaje deberá utilizase el HSM.
Ejemplo de envío de texto
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"messageText": "Mensaje de prueba"
8
}
9
}
10
Copied!
Imagen:
Campo
Necesario
Detalles
Tipo
type
Si
Tipo / extensión de la imagen que se enviará en el mensaje. Opciones disponibles: JPG, JPEG, PNG.
String
caption
No
Texto que se mostrara al usuario debajo de la imagen en Whatsapp
String
url
Si
URL donde se aloja el contenido que se enviará.
String
data
Si
Base64 contenido codificado
String
Ejemplo de envío de imagen (URL)
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"image": {
8
"type": "JPG",
9
"url": "http://...jpg",
10
"caption": "image description"
11
}
12
}
13
}
14
Copied!
Ejemplo de envío de imagen (Base64)
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"image": {
8
"type": "JPG",
9
"data": "ZmlsZQ=="
10
}
11
}
12
}
Copied!
Solo se debe especificar una de las siguientes opciones, ya sea ‘url’, en caso de que desee enviar usando un archivo, o ‘datos’, en caso de que desee enviar una imagen usando la codificación base64
Audio:
Campo
Necesario
Detalles
Tipo
type
Si
Tipo/Extensión de audio que se enviará en el mensaje. Opciones disponibles: AAC, MP4, AMR, MP3, OGG.
String
url
Si
URL donde se aloja el contenido que se enviará.
String
data
Si
Base64 contenido codificado
String
Solo se debe especificar una de las siguientes opciones, ya sea ‘url’, en caso de que desee enviar usando un archivo, o ‘datos’, en caso de que desee enviar un audio usando la codificación base64
Ejemplo de envío de audio (URL)
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"audio": {
8
"type": "MP3",
9
"url": "http://...mp3"
10
}
11
}
12
}
Copied!
Ejemplo de envío de audio (Base64)
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"audio": {
8
"type": "MP3",
9
"data": "ZmlsZQ=="
10
}
11
}
12
}
Copied!
Documento:
Campo
Necesario
Detalles
Tipo
type
Si
Tipo/Extensión de documento que se enviará en el mensaje. Opciones disponibles: PDF.
String
caption
No
Texto que se mostrara al usuario debajo del documento en Whatsapp
String
url
Si
URL donde se aloja el contenido que se enviará.
String
data
Si
Base64 contenido codificado
String
Solo se debe especificar una de las siguientes opciones, ya sea ‘url’, en caso de que desee enviar usando un archivo, o ‘datos’, en caso de que desee enviar un documento usando la codificación base64 encoding
Ejemplo de envío de documento (URL)
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"document": {
8
"type": "PDF",
9
"url": "http://...pdf",
10
"caption": "pdf description"
11
}
12
}
13
}
Copied!
Ejemplo de envío de documento (Base64)
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"document": {
8
"type": "PDF",
9
"data": "ZmlsZQ=="
10
}
11
}
12
}
Copied!
Ejemplo de envío de ubicacion
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"location": {
8
"geoPoint": "-22.894180,-47.047960",
9
"name": "Wavy",
10
"address": "Av. Cel. Silva Telles"
11
}
12
}
13
}
Copied!
Contact:
Campo
Necesario
Detalles
Tipo
addresses
No
Direcciones de contacto completas.
Address[]
birthday
No
Fecha de cumpleaños como cadena con formato YYYY-MM-DD.
Para los objetos que contienen un campo de tipo, los valores listados se consideran simplemente los valores estándar que se pueden ver, sin embargo, puede establecer el campo en cualquier valor descriptivo que elija..
Envío de mensajes HSM
Ejemplo de solicitud HSM
1
{
2
"destinations": [{
3
"correlationId": "MyCorrelationId",
4
"destination": "5519900001111"
5
}],
6
"message": {
7
"ttl": 1,
8
"hsm": {
9
"namespace": "namespace",
10
"elementName": "elementName",
11
"parameters":[
12
"MyParam1",
13
"MyParam2"
14
]
15
}
16
}
17
}
Copied!
También es posible enviar una base de mensajes en plantillas previamente definidas (también llamado HSM), con la adición de placeholders (“parámetros”). El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:
Campo
Necesario
Detalles
Tipo
destinations
Si
Lista de destinatarios
Destination
message
Si
Mensaje de texto que se enviará a la lista de destinatarios
Message
flowId
No
Identificación del flujo de Bot
String
defaultExtraInfo
No
Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje
String
campaignAlias
No
ID de campaña, está vinculado a todos los mensajes del envío
String
Destino:
Campo
Necesario
Detalles
Tipo
correlationId
No
Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos.
String
destination
Si
Número de teléfono al que se enviará el mensaje (código de país y estado deben estar presentes). Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111.
String
Mensaje:
Campo
Necesario
Detalles
Tipo
ttl
No
Tiempo de vida en días. Define el número máximo de días en que el mensaje debe entregarse. Válido de 1 a 30. Valor predeterminado 7 si no está configurado.
long
hsm
Si
Contenido del mensaje HSM.
HSM
HSM:
Campo
Necesario
Detalles
Tipo
namespace
Si
El espacio de nombres que se usará
String
elementName
Si
El nombre del elemento que indica qué plantilla usar dentro del espacio de nombres
String
parameters
Si, si la plantilla del mensaje tiene variables
Este campo es una matriz de valores para aplicar a las variables en la plantilla
String
languagePolicy
No
Parámetro que identifica cómo se seleccionará el lenguaje HSM. Opciones Disponibles: FALLBACK: Cuando la plantilla de HSM no tenga una versión para el idioma del dispositivo del usuario, se usará el idioma definido. DETERMINISTIC: El mensaje siempre se enviará en el código de idioma, independientemente del idioma en que esté configurado el dispositivo del usuario final.
String
languageCode
Obligatorio si languagePolicy está presente
Código de idioma o configuración regional, acepta ambos formatos: lenguaje (en) o lenguaje_local (es_AR). Para confirmar todos los idiomas disponibles para un HSM en particular, contáctese con nuestro equipo de Soporte.
También es posible enviar una base de mensajes en plantillas previamente definidas (también llamado templates), con la adición de placeholders (“parámetros”). El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:
Campo
Necesario
Detalles
Tipo
destinations
Si
Lista de destinatarios
Destination
message
Si
Mensaje de texto que se enviará a la lista de destinatarios
Message
flowId
No
Identificación del flujo de Bot
String
defaultExtraInfo
No
Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje
String
campaignAlias
No
ID de campaña, está vinculado a todos los mensajes del envío
String
Destino:
Campo
Necesario
Detalles
Tipo
correlationId
No
Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos.
String
destination
Si
Número de teléfono al que se enviará el mensaje (código de país y estado deben estar presentes). Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111.
String
Mensaje:
Campo
Necesario
Detalles
Tipo
ttl
No
Tiempo de vida en días. Define el número máximo de días en que el mensaje debe entregarse. Válido de 1 a 30. Valor predeterminado 7 si no está configurado.
long
template
Si
Contenido del template del mensaje.
Template
Template:
Campo
Necesario
Detalles
Tipo
namespace
Si
Valor que identifica la cuenta de registro del modelo de Facebook
String
elementName
Si
Valor que identifica el modelo registrado en Facebook
String
languageCode
Si
Uno de los idiomas definidos en el registro del template
String
languagePolicy
Si
Parámetro que identifica cómo se seleccionará el lenguaje HSM. Opciones Disponibles: FALLBACK: Cuando la plantilla de HSM no tenga una versión para el idioma del dispositivo del usuario, se usará el idioma definido. DETERMINISTIC: El mensaje siempre se enviará en el código de idioma, independientemente del idioma en que esté configurado el dispositivo del usuario final.
String
header
Si (caso lo template necessite)
Objetos de cabeçalho com sus parametros
Header
bodyParameters
Si (caso lo template use variaveis)
La suma de todos los caracteres del cuerpo, considerando los campos fijos y dinámicos, está limitada a 1024 caracteres si el template registrado solo tiene el cuerpo. Está limitado a 160 caracteres si tiene un header o footer.
Lista de strings
Header:
Campo
Necesario
Detalles
Tipo
parameters
No
Lista de parámetros para reemplazar en el texto del header.
Si está presente, el header no debe tener title ni elements
title
No
El título debe tener hasta 60 caracteres.
String [ ]
element
Si
Opciones:
TEXT, IMAGE, AUDIO, DOCUMENT, HSM, VIDEO.
Obs.: No es obligatorio en caso de pasar el campo parameters
Object
Códigos comunes de respuesta de estado HTTP
Respuesta de envio exitoso (200)
Si tiene éxito, se espera una lista de destinatarios (“destinos”) con uuids generados desde el lado de la aplicación:
1
{
2
"Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
3
"destinations": [{
4
"id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
5
"correlationId": "MyCorrelationId",
6
"destination": "5519900001111."
7
}]
8
}
Copied!
Respuesta de error de autenticación (401)
Si hay un problema en la autenticación del usuario, se espera el siguiente mensaje de error:
1
{
2
"errorCode": 401,
3
"errorMessage": "Authentication Error: No se encontró ningún usuario con esta combinación de nombre de usuario y token de autenticación."
4
}
Copied!
Callback de actualización de estado
Ejemplo
1
{
2
"total": 1,
3
"data": [
4
{
5
"id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
6
"correlationId": "...",
7
"destination": "5411900000000",
8
"origin": "5411900000000",
9
"campaignId": 100,
10
"campaignAlias": "...",
11
"flowId": "...",
12
"extraInfo": "...",
13
"sent": true,
14
"sentStatusCode": 1,
15
"sentStatus": "sent status",
16
"sentDate": "2017-12-18T17:09:31.891Z",
17
"sentAt": 1513616971891,
18
"delivered": true,
19
"deliveredStatusCode": 1,
20
"deliveredStatus": "delivered status",
21
"deliveredDate": "2017-12-18T17:09:31.891Z",
22
"deliveredAt": 1513616971891,
23
"read": true,
24
"readDate": "2017-12-18T17:09:31.891Z",
25
"readAt": 1513616971891,
26
"updatedDate": "2017-12-18T17:09:31.891Z",
27
"updatedAt": 1513616971891
28
}
29
],
30
"clientInfo": {
31
"customerId": 42,
32
"subAccountId": 1291,
33
"userId": 1
34
}
35
}
Copied!
Para cada actualización sobre el estado de los mensajes enviados (confirmación de entrega al usuario final, lectura de mensajes, etc.), se envíara un Callback / Webhook. Los callbacks se envían por lotes.
IMPORTANTE: El endpoint al que sera enviado el webhook debe configurarse previamente con el equipo de soporte / operaciones.
El formato de esta devolución será de acuerdo a la siguiente descripción:
Campo
Detalles
Tipo
total
Número de callbacks en la llamada.
String
data
Lista de callbacks.
Data[]
clientInfo
Información del cliente
ClientInfo
Datos:
Campo
Detalles
Tipo
id
ID del último mensaje
String
correlationId
Un ID único configurado por usted para coincidir con el estado del mensaje (callback y DLR). Este parámetro es opcional y puede usar el ID generado por ChatClub para esta coincidencia.
String
destination
Teléfono al que se envió el mensaje (incluido el código de país). Ejemplo: 5411900000000.
String
origin
Teléfono que identifica la cuenta de WhatsApp (incluido el código de país). Ejemplo: 5411900000000.
String
campaignId
ID de campaña previamente definido.
String
campaignAlias
Alias de campaña previamente definido.
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 ChatClub para un mensaje que indica el estado de envío.
Number
sentStatus
Descripción del estado enviado.
Boolean
sentDate
Fecha en que se envió el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ.
String
sentAt
Hora en que se envió el mensaje, utilizando el formato Unix_time
Number
delivered
Indica si el mensaje fue entregado al destino.
Boolean
deliveredStatusCode
Código de estado generado por ChatClub para indicar que el mensaje fue entregado.
Number
deliveredStatus
Descripción del estado de entrega
String
deliveredDate
Fecha en que se entregó el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ
String
deliveredAt
Hora en que se entregó el mensaje, utilizando el formato Unix_time
Number
read
Indica si el mensaje fue leído por el destinatario.
Boolean
readDate
Fecha en que se leyó el mensaje. Formato: yyyy-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: yyyy-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
Detalles
Tipo
customerId
Identificación del cliente.
Number
subAccountId
Identificación de la subcuenta.
Number
userId
Identificación del usuario.
Number
Estatus
Estatus que puedem ser enviados en el callback:
Estatus
Codigo de envio
Codigo de entrega
Significado
CARRIER_COMMUNICATION_ERROR
102
Error al subir el contenido multimedia a WhatsApp.