NAV Navbar

en es pt

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 presentar 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.movile.com
Puerto 443 (https)
Protocolo HTTPS (TLS encryption)
Autenticación username + token
Codificación UTF-8

Enviar mensajes

Envío de mensajes de texto

Ejemplo de solicitud de imagen (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "image": {
                    "type": "JPG",
                    "url": "http://...jpg"
                }
            }
        }

Ejemplo de solicitud de imagen (Base64)

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "image": {
                   "type": "JPG",
                   "data": "ZmlsZQ=="
               }
           }
       }

Ejemplo de solicitud de audio (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "url": "http://...mp3"
                }
            }
        }

Ejemplo de solicitud de audio (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "data": "ZmlsZQ=="
                }
            }
        }

Ejemplo de solicitud de documento (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "url": "http://...pdf"
                }
            }
        }

Ejemplo de solicitud de documento (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "data": "ZmlsZQ=="
                }
            }
        }

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.movile.com/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
previewFirstUrl No Controla la vista previa de la aplicación de la primera URL enviada Boolean

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
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

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

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

Documento:

Campo Necesario Detalles Tipo
type Si Tipo/Extensión de documento que se enviará en el mensaje. Opciones disponibles: PDF. String
url Si URL donde se aloja el contenido que se enviará. String
data Si Base64 contenido codificado String

Envío de mensajes HSM

Ejemplo de solicitud HSM

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "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 marcadores de posición (“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
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

Código 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

Example

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5411900000000",
      "origin": "5411900000000",
      "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
    }
  ]
}

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 Necesario Detalles Tipo
total Número de callbacks en la llamada. String
data Lista de callbacks. Data

Datos:

Campo Necesario 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

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": "5419900000000",
      "origin": "5419900000000",
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "TEXT",
"messageText": "Hola, este es un mensaje del usuario."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Ejemplo de mensaje multimedia

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5419900000000",
      "origin": "5419900000000",
      "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": "5419900000000",
      "origin": "5419900000000",
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "LOCATION",
"location": "lat,lng"
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

En cada respuesta del usuario final (MO) se envía un Callback / webhook. Estos MO se envían por lotes.

*** IMPORTANTE: *** El endpoint al que se enviará 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 mensajes originados en dispositivos móviles. Data
Campo Detalles Tipo
id Última identificación del mensaje String
source Teléfono del remitente String
origin Teléfono que identifica la cuenta de WhatsApp (incluido el código de país). Ejemplo: 5411900000000. 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
campaignId ID de campaña previamente definido. String
campaignAlias Alias de Campaña previamente definido. String
message Mensaje MO. Message
receivedAt Fecha en que se recibió el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ String
receivedDate Fecha en que se recibió el mensaje, utilizando el formato Unix_time String

Mensaje:

Campo Detalles Tipo
type Tipo de mensaje enviado por el usuario final: TEXT - IMAGE - AUDIO - DOCUMENT String
messageText El mensaje de texto (MO) enviado por el usuario final. String
mediaUrl Url para descargar la multimedia enviada por el usuario final. String
mimeType Tipo de archivo enviado por el usuario final. String
caption Etiqueta de multimedia enviada por el usuario final. String
location Ubicación enviada por el usuario final. Formato: “latitud, longitud” String

API SFTP WhatsApp

Detalhes de conexão

Hostname ftp-messaging.movile.com
Puerta 2222
Protocolo SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor)
Autenticación username + senha (provisto por soporte)

Envío de mensajes a través de SFTP

Para realizar el disparo de mensajes vía FTP es necesario generar un archivo con el formato siguiendo el ejemplo abajo: Mensaje HSM:

2018-10-16;10:00;20:00;HSM;chatclub_welcome;pt_BR;DETERMINISTIC;nome|empresa
telefone;nome;empresa
551999999999;Nome1;Wavy
551999999999;Nome2;Movile

1ª Línea
Fecha de envío (para casos de programación)
Hora inicial de envío (para casos de programación)
Hora final de envío (para casos de programación)
Tipo de mensaje debe ser: HSM
Nombre (elementName) del HSM
Idioma (languageLocale) de HSM
Determinante o Fallback del idioma de HSM (languagePolicy)
Nombre de los parámetros de HSM

** Observaciones para la primera línea: **

1 - Los nombres de los parámetros deben coincidir con los nombres de las columnas

2 - Las informaciones que no se utilicen se pueden dejar en blanco, pero deben mantener el punto y coma como separación. Ejemplo de un caso que no utilizamos programación (los campos iniciales quedan entre punto y coma y sin información dentro):; ; ; HSM; chatclub_welcome; es_ES; DETERMINISTIC; nombre | empresa

3 - Por defecto (predeterminado) la languagePolicy será determinante.

4 - Los nombres de los parámetros del HSM deben ser separados por “|” y no por “;”

2ª línea
Nombre de las columnas
3ª y demás líneas:
Destinatario y valores de los parámetros de HSM