WhatsApp API
Documentación técnica: WhatsApp API.
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.
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 |
| |
Nombre del host | api-messaging.wavy.global |
Puerto | 443 (https) |
Protocolo | HTTPS (TLS encryption) |
Autenticación | username + token |
Codificación | UTF-8 |
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 |
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 |
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’
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
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"messageText": "Mensaje de prueba"
}
}
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)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"image": {
"type": "JPG",
"url": "http://...jpg",
"caption": "image description"
}
}
}
Ejemplo de envío de imagen (Base64)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"image": {
"type": "JPG",
"data": "ZmlsZQ=="
}
}
}
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
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)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"audio": {
"type": "MP3",
"url": "http://...mp3"
}
}
}
Ejemplo de envío de audio (Base64)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"audio": {
"type": "MP3",
"data": "ZmlsZQ=="
}
}
}
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)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"document": {
"type": "PDF",
"url": "http://...pdf",
"caption": "pdf description"
}
}
}
Ejemplo de envío de documento (Base64)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"document": {
"type": "PDF",
"data": "ZmlsZQ=="
}
}
}
Ejemplo de envío de ubicacion
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"location": {
"geoPoint": "-22.894180,-47.047960",
"name": "Wavy",
"address": "Av. Cel. Silva Telles"
}
}
}
Campo | Necesario | Detalles | Tipo |
addresses | No | Direcciones de contacto completas. | Address[] |
birthday | No | Fecha de cumpleaños como cadena con formato YYYY-MM-DD. | String |
emails | No | Direcciones de correo electrónico de contacto. | Email[] |
name | No | Nombre completo de contacto. | Name |
org | No | Información de la organización de contacto. | Org |
phones | No | Teléfonos de contacto. | Phone[] |
urls | No | URLs de los contactos. | Url[] |
Ejemplo de envio de contactos
{
"destinations":[
{
"correlationId":"MyCorrelationId",
"destination":"5519900001111"
}
],
"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"
}
]
}
]
}
}
Campo | Necesario | Detalles | Tipo |
street | No | Número y nombre de la calle. | String |
city | No | Nombre de la ciudad. | String |
state | No | Abreviatura del estado. | String |
zip | No | Código postal. | String |
country | No | Nombre completo del país. | String |
country_code | No | Abreviatura de país de dos letras. | String |
type | No | Valores estándar: HOME, WORK. | String |
Campo | Necesario | Detalles | Tipo |
email | No | Correo electrónico. | String |
type | No | Valores estándar: HOME, WORK. | String |
Campo | Necesario | Detalles | Tipo |
first_name | No | Primer nombre. | String |
last_name | No | Apellido. | String |
middle_name | No | Segundo nombre. | String |
name_suffix | No | Sufijo del nombre. | String |
name_prefix | No | Prefijo del nombre. | String |
formatted_name | No | Nombre completo como aparece normalmente. | String |
Campo | Necesario | Detalles | Tipo |
company | No | Nombre de la empresa del contacto. | String |
department | No | Nombre del departamento de contacto. | String |
title | No | Título comercial de contacto. | String |
Campo | Necesario | Detalles | Tipo |
phone | No | Número de teléfono formateado. | String |
type | No | Valores estándar: CELL, MAIN, IPHONE, HOME, WORK. | String |
wa_id | No | Identificador de WhatsApp. | String |
Campo | Necesario | Detalles | Tipo |
phone | No | URL del contacto. | String |
type | No | Valores estándar: HOME, WORK. | String |
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..
Ejemplo de solicitud HSM
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"ttl": 1,
"hsm": {
"namespace": "namespace",
"elementName": "elementName",
"parameters":[
"MyParam1",
"MyParam2"
]
}
}
}
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 |
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 |
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 |
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. | String |
Ejemplo de solicitud template
{
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"template": {
"namespace" : "aaaaaaaa_bbbb_cccc_dddd_eeeeeeeeeeee",
"elementName" : "some_approved_image_hsm",
"header": {
"image": {
"url": "https://upload.wikimedia.org/wikipedia/commons/c/c3/Arquivo.jpg",
"type": "JPG"
}
},
"bodyParameters": [
"https://upload.wikimedia.org/wikipedia/commons/c/c3/Arquivo.jpg"
],
"languagePolicy": "DETERMINISTIC",
"languageCode": "pt_BR"
}
}
}
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 |
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 |
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 |
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 |
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 |
Si tiene éxito, se espera una lista de destinatarios (“destinos”) con uuids generados desde el lado de la aplicación:
{
"Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
"destinations": [{
"id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
"correlationId": "MyCorrelationId",
"destination": "5519900001111."
}]
}
Si hay un problema en la autenticación del usuario, se espera el siguiente mensaje de error:
{
"errorCode": 401,
"errorMessage": "Authentication Error: No se encontró ningún usuario con esta combinación de nombre de usuario y token de autenticación."
}
Ejemplo