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. Para utilizar la API de mensajería de Sinch, primero debe tener una cuenta activa en la plataforma de mensajería de Sinch.

2. También debe tener un nombre de usuario y un token válidos asociados con esta cuenta.

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, [phone], [phone].

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":"[e-mail]",
                          "type":"WORK"
                       },
                       {  
                          "email":"[e-mail]",
                          "type":"WORK"
                       }
                    ],
                    "name":{  
                       "first_name":"John",
                       "formatted_name":"John Smith",
                       "last_name":"Smith"
                    },
                    "org":{  
                       "company":"WhatsApp",
                       "department":"Design",
                       "title":"Manager"
                    },
                    "phones":[  
                       {  
                          "phone":"[phone]",
                          "type":"HOME"
                       },
                       {  
                          "phone":"[phone]",
                          "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
emails	No	Dirección(es) de correo electrónico de contacto.	Email[]
name	No	Nombre completo del contacto.	Name
org	No	Información de contacto de la organización.	Org
phones	No	Teléfono(s) de contacto.	Phone[]
urls	No	URL de contacto.	Url[]

Address:

Campo	Obligatorio	Detalles	Tipo
street	No	Nombre y número de la calle.	String
city	No	Nombre de la ciudad.	String
state	No	símbolo del estado.	String
zip	No	CÓDIGO POSTAL.	String
country	No	Nombre completo del país.	String
country_code	No	Abreviatura del país (Dos letras).	String
type	No	Valores por defecto: CASA, TRABAJO.	String

Email:

Campo	Obligatorio	Detalles	Tipo
email	No	Dirección de correo electrónico.	String
type	No	Valores por defecto: CASA, TRABAJO.	String

Name:

Campo	Obligatorio	Detalles	Tipo
first_name	No	Primer nombre.	String
last_name	No	Ultimo nombre.	String
middle_name	No	Nombre del medio.	String
name_suffix	No	Sufijo de nombre.	String
name_prefix	No	Prefijo del nombre.	String
formatted_name	No	Nombre completo como aparece normalmente.	String

Org:

Campo	Obligatorio	Detalles	Tipo
company	No	Nombre de la organización del contacto.	String
department	No	Nombre del departamento del contacto.	String
title	No	Título corporativo del contacto.	String

Phone:

Campo	Obligatorio	Detalles	Tipo
phone	No	Número de teléfono formateado.	String
type	No	Valores predeterminados: CELULAR, PRINCIPAL, IPHONE, CASA, TRABAJO.	String
wa_id	No	Identificador de WhatsApp.	String

Url:

Campo	Obligatorio	Detalles	Tipo
phone	No	URL de contacto.	String
type	No	Valores por defecto: CASA, TRABAJO.	String

Para los objetos que contienen un campo de tipo, los valores enumerados simplemente se consideran los valores predeterminados que se pueden ver, sin embargo, puede establecer el campo en cualquier valor descriptivo que elija.

API SFTP WhatsApp

Detalles de conexión

Campo	Descripción
Hostname	ftp-messaging.wavy.global
Porta	2222
Protocolo	SFTP (transferencia a través de ssh, que proporciona cifrado cliente-servidor)
Autenticação	nombre de usuario + contraseña (proporcionado por soporte)

Es necesario liberar tus IPs en los firewalls de Sinch. Si es necesario liberar el firewall para salida hacia el puerto 2222, debe liberar el DNS, o las IPs 200.219.220.54, 200.189.169.53 y 45.236.179.22

Envío de mensajes a través de SFTP

Para disparar mensajes a través de FTP, es necesario generar un archivo con formato siguiendo el ejemplo a continuación: Mensaje HSM:

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

1ª Línea

Fecha de presentación (para casos de programación)

Hora de inicio de envío (para casos de programación)

Hora de envío final (para casos de programación)

El tipo de mensaje debe ser: HSM

Nombre (elementName) del HSM

Idioma (languageLocale) del HSM

Determinista o Fallback del lenguaje del HSM (languagePolicy)

Nombre de parámetros de HSM

Notas para la primera línea::

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

2. La información que no se va a utilizar se puede dejar en blanco, pero el punto y coma se debe utilizar como separación. Ejemplo de un caso donde no usamos scheduling (los campos iniciales están entre punto y coma y sin información adentro): ; ; ; HSM;chatclub_welcome;en_BR;DETERMINISTIC;nombre|empresa

3. De forma predeterminada (predeterminada), languagePolicy será determinista.

4. Los nombres de los parámetros de HSM deben estar separados por “ | ” y no por “ ; ”

2ª Linha
nombres de columnas

3ª y otras lineas:
Valores de parámetros de destinatario y HSM

Consulta de lista a través de API

Pedido

Con GET, puede realizar una solicitud enviando todos los parámetros en la cadena de consulta

http://api-messaging.wavy.global/v1/list/{listType}?customerId={customerId}&subAccountId={subAccountId}

Tipo de Lista	Valor pasado en {listType}
Whatsapp OPT-OUT List	OPTOUT
Whatsapp OPT-IN List	OPTIN
Whatsapp Blacklist	BLACKLIST
Whatsapp Whitelist (para MT)	WHITELIST

El parámetro customerId es obligatorio, mientras que subAccountId es opcional.

Atención: las llaves '{' y '}' también deben reemplazarse.

Por ejemplo, "{listType}" se convierte en "OPTIN". Todavía es necesario pasar los siguientes encabezados:

Header	Valor
Content-Type	application/json
authenticationToken	Token do Messaging
userName	Nombre de usuario de mensajería

Respuesta

En caso de éxito, si hay datos asociados con customerId y subAccountId, la solicitud devolverá un JSON con 3 atributos:

Atributo	Valor
success	true
status	200
data	Enlace para descargar un archivo csv que contiene los campos "fuente" y "creado en" de todos los destinos encontrados

La columna "creado en" está en la zona horaria de América/Sao_Paulo, UTC-3 o UTC-2 en horario de verano.

Si no hay datos asociados, solo se devolverá un JSON similar, pero sin el campo de datos, lo que significa que no hubo problemas con la solicitud, pero no hubo datos relacionados con los parámetros pasados.

Ejemplo de respuesta:

{
    "success": true,
    "status": 200,
    "data": "https://chatclub-cdn.wavy.global/2019/02/12/f2b8effb-d0bc-4327-86c2-48fedcb01b1b/list-42-4330544192402746957.csv"
}

Consultar sesiones abiertas a través de API

Pedido

Para consultar las sesiones abiertas a través de nuestra API, debe realizar una solicitud GET a la dirección:

GET http://api-messaging.wavy.global/v1/session?customerId={customerId}&subAccountId={subAccountId}

El parámetro customerId es obligatorio, mientras que subAccountId es opcional.

Atención: Las llaves '{' y '}' también deben reemplazarse. Por ejemplo, “={customerId}” se convierte en “=42”.

Todavía es necesario pasar los siguientes encabezados

Header	Valor
Content-Type	application/json
authenticationToken	Token
userName	Nombre de usuario

El usuario y el token se pueden obtener a través de nuestra plataforma: Mi Perfil

Respuesta

En caso de éxito, si hay sesiones abiertas para el ID de cliente y el ID de subcuenta especificados, la solicitud devolverá un JSON con el atributo:

Atributo	Valor
file_url	Enlace para descargar un archivo csv que contiene los campos "fuente" y "session_created_at" de todos los destinos encontrados

Si no hay datos asociados con customerId y subAccountId, el archivo devuelto estará vacío, con solo el encabezado.

Ejemplo de respuesta:

{
    "file_url": "https://chatclub-cdn.wavy.global/2019/02/13/633e33fc-3a3f-4ca5-a8b0-4b747fb67137/5bd46e2b-5990-4681-9b29-98ab6598960e"
}

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, [phone], [phone].	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": "Sinch",
                    "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":"[e-mail]",
                          "type":"WORK"
                       },
                       {  
                          "email":"[e-mail]",
                          "type":"WORK"
                       }
                    ],
                    "name":{  
                       "first_name":"John",
                       "formatted_name":"John Smith",
                       "last_name":"Smith"
                    },
                    "org":{  
                       "company":"WhatsApp",
                       "department":"Design",
                       "title":"Manager"
                    },
                    "phones":[  
                       {  
                          "phone":"[phone]",
                          "type":"HOME"
                       },
                       {  
                          "phone":"[phone]",
                          "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, [phone], [phone].	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, [phone], [phone].	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

{
  "total": 1,
  "data": [
    {