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.
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
        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "messageText": "Mensaje de prueba"
            }
        }
​
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)
        {
            "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
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)
        {
            "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=="
                }
            }
        }
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)
        {
            "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"
                }
            }
        }
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.
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"
                       }
                    ]
                 }
              ]
           }
        }
Address:
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
Email:
Campo
Necesario
Detalles
Tipo
email
No
Correo electrónico.
String
type
No
Valores estándar: HOME, WORK.
String
Name:
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
Org:
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
Phone:
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
Url:
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..
Envío de mensajes HSM
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
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.
String
Envío de mensajes template
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
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:
{
 "Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "destinations": [{
  "id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "correlationId": "MyCorrelationId",
  "destination": "5519900001111."
}]
}
Respuesta de error de autenticación (401)
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."
}
Callback de actualización de estado
Ejemplo
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
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
WhatsApp API

Autenticacion de usuario

Detalles de la conexión

Enviar mensajes

Envío de mensajes de texto

Destino:

Mensaje:

Texto:

Imagen:

Audio:

Documento:

Contact:

Address:

Email:

Name:

Org:

Phone:

Url:

Envío de mensajes HSM

Destino:

Mensaje:

HSM:

Envío de mensajes template

Destino:

Mensaje:

Template:

Header:

​

Códigos comunes de respuesta de estado HTTP

Respuesta de envio exitoso (200)

Respuesta de error de autenticación (401)

Callback de actualización de estado
