WhatsApp API
Documentación técnica: WhatsApp API.
Last updated
Was this helpful?
Documentación técnica: WhatsApp API.
Last updated
Was this helpful?
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.
Para utilizar la API de mensajería de Sinch, primero debe tener una cuenta activa en la plataforma de mensajería de Sinch.
También debe tener un nombre de usuario y un token válidos asociados con esta cuenta.
Aprenda cómo crear su usuario en nuestra guía Agregar usuarios. Con las credenciales anteriores, puede comenzar a usar Sinch Messaging API.
Hostname
api-messaging.wavy.global
Porta
443 (https)
Protocolo
HTTPS (TLS encryption)
Autenticação
username + token
Encoding
UTF-8
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.
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.
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
Destinations
destinations
Si
Detalles sobre identificadores de envío y destino
message
Si
Detalles sobre el objeto MESSEGE que se enviará
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, +5519900001111, +55(19) 900001111.
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á
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.
Title
Opcional
El título debe tener hasta 60 caracteres.
Element
Si
Opções:
text (padrão),
image,
audio,
document,
hsm,
video.
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
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.
Nome
Conteúdo do objeto
messages
Notificações de mensagens de entrada
statuses
Atualizações de status das mensagens
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
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
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
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.
Si la solicitud se ejecuta con éxito, se devolverá la lista de destinos con los uuid generados:
Si hay un problema con la autenticación, se devolverá el siguiente mensaje:
Ejemplo
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:
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
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
customerId
Identificación del cliente.
Number
subAccountId
ID de subcuenta.
Number
userId
Identificación de usuario.
Number
Status que podem ser enviados no callback:
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.
Ejemplo de mensaje de texto:
Ejemplo de información adicional:
Ejemplo de mensaje multimedia
Ejemplo de mensaje de ubicación:
Ejemplo de mensaje de contacto:
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.
total
Números de devolución de llamada para la llamada.
String
data
Lista de mensajes con origen móvil (MO).
Data[]
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
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.
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
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[]
name
Não
Nombre de perfil de usuario
String
name
Nombre del lugar.
String
address
Dirección del sitio.
String
geoPoint
Geopunto enviado por el usuario final. Formato: "latitud, longitud"
String
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[]
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
No
Dirección de correo electrónico.
String
type
No
Valores por defecto: CASA, TRABAJO.
String
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
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
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
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.
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
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
Los nombres de los parámetros deben coincidir con los nombres de las columnas.
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
De forma predeterminada (predeterminada), languagePolicy será determinista.
Los nombres de los parámetros de HSM deben estar separados por “ | ” y no por “ ; ”
nombres de columnas
Valores de parámetros de destinatario y HSM
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}
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:
Content-Type
application/json
authenticationToken
Token do Messaging
userName
Nombre de usuario de mensajería
En caso de éxito, si hay datos asociados con customerId y subAccountId, la solicitud devolverá un JSON con 3 atributos:
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:
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
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
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:
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:
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
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
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)
Ejemplo de envío de imagen (Base64)
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
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)
Ejemplo de envío de audio (Base64)
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)
Ejemplo de envío de documento (Base64)
Ejemplo de envío de ubicacion
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
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
No
Correo electrónico.
String
type
No
Valores estándar: HOME, WORK.
String
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
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
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
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
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:
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
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
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
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
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:
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
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
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
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
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:
Si hay un problema en la autenticación del usuario, se espera el siguiente mensaje de error:
Ejemplo
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:
total
Número de callbacks en la llamada.
String
data
Lista de callbacks.
Data[]
clientInfo
Información del cliente
ClientInfo
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
customerId
Identificación del cliente.
Number
subAccountId
Identificación de la subcuenta.
Number
userId
Identificación del usuario.
Number
Estatus que puedem ser enviados en el callback:
CARRIER_COMMUNICATION_ERROR
102
Error al subir el contenido multimedia a WhatsApp.
REJECTED_BY_CARRIER
103
Se produjo un error en la base de datos.
SENT_SUCCESS
2
EXPIRED
2
101
Mensaje vencido.
Error al enviar el mensaje porque es demasiado viejo.
NOT_DELIVERED
2
104
Limitación activada - muchos envíos de mensajes intentaron.
Error al enviar el mensaje porque el número de teléfono de este usuario es parte de un experimento.
Estructura no disponible: El cliente no puede mostrar HSM.
Error al enviar el mensaje porque está fuera de la ventana de soporte de forma libre para este usuario. Utilice una notificación HSM válida o reconsidere.
Error de carga del medio (error desconocido).
Error al enviar el mensaje porque su cuenta no es elegible. Verifique su cuenta WhatsApp Business.
Fallo de carga temporal. Por favor, intente de nuevo más tarde.
DELIVERED_SUCCESS
2
4
READ_SUCCESS
2
5
INVALID_DESTINATION_NUMBER
202
Contacto 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 no válido UNKNOWN.
INVALID_SESSION
210
La sesión no está abierta y no se ha establecido un HSM de Fallback.
DESTINATION_BLOCKED_BY_OPTIN
211
DESTINATION_BLOCKED_BY_WHITELIST
212
INTERNAL_ERROR
311
No se pudieron verificar los contactos de la API de WhatsApp.
Ejemplo de mensaje de texto:
Ejemplo de Extra Info:
Ejemplo de mensaje multimedia
Ejemplo de mensaje de ubicación:
Ejemplo de mensaje de contacto:
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 la respuesta será de acuerdo a la siguiente descripción:
total
Número de callbacks en la llamada.
String
data
Lista de mensajes originados en dispositivos móviles.
Data
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
userProfile
Perfil del usuario que envió el mensaje
UserProfile
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
extraInfo
Información extra relacionada con el mensaje. Formato: Json
String
El mensaje tendrá una lista de listas de segmentaciones en el campo Información adicional. Nuestros asociados lo utilizan para redirigir los mensajes a través de ciertos flujos. El nombre de la clave es segmentation_lists y contiene una lista de SegmentationList.
id
Identificador de la lista de segmentación
Integer
customerId
Identificador de cliente
Integer
subAccountId
Identificador de subcuenta
Integer
name
Nombre de la lista de segmentación
String
active
Estado de la lista de segmentación
Boolean
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
waGroupId
El grupo al que se envió el mensaje.
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.
Location
contacts
Contactos enviados por el usuario final.
Contact[]
name
No
El nombre del perfil del usuario
String
name
Nombre del sitio.
String
address
Dirección del sitio.
String
geoPoint
Geopoint enviada por el usuario final. Formato: “latitud, longitud”
String
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[]
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
No
Correo electrónico.
String
type
No
Valores estándar: HOME, WORK.
String
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
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
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
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.
Hostname
ftp-messaging.wavy.global
puerto
2222
Protocolo
SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor)
Autenticación
username + senha (provisto por soporte)
Es necesaria la liberación de sus IPs en el firewalls de Wavy Si fuera necesario liberación del firewall para salida sentido puerto 2222, usted debe liberar los DNS, o las IPs 200.219.220.54, 200.189.169.53 e 45.236.179.22
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
Usando GET, puede hacer una solicitud enviando todos los parámetros en la query string (cadena de consulta)
GET http://api-messaging.wavy.global/v1/list/{listType}?customerId={customerId}&subAccountId={subAccountId}
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 el subAccountId es opcional.
Atención: Tenga cuidado de reemplazar ‘{’ y ‘}’ también. Por ejemplo, “{listType}” se convierte en “OPTIN”.
Todavía es necesario pasar los siguientes headers:
Content-Type
application/json
authenticationToken
Token de Messaging1
userName
Nombre de usuario de Messaging1
Puede obtener su nombre de usuario y su token a través de la plataforma: https://messaging.wavy.global
En caso de éxito, si hay datos asociados al customerId y al subAccountId, la solicitud devuelve un JSON con 3 atributos:
success
true
status
200
data
Link para descargar un archivo de tipo csv que contiene los campos “source” y “createdAt” de todos los destinos encontrados
La columna “createdAt” está en la zona horaria America/Sao_Paulo, UTC-3 o UTC-2 en el horario de verano
En caso de que no haya datos relacionados con customerId y subAccountId, sólo se devuelve un JSON similar, pero sin el campo “data”, lo que significa que no hubo problemas con la solicitud, pero no había datos relativos a los parámetros pasados.
Ejemplo de respuesta:
Para consultar sesiones abiertas a través de nuestra API, debe realizar una solicitud GET a la siguiente dirección:
GET http://api-messaging.wavy.global/v1/session?customerId={customerId}&subAccountId={subAccountId}
Pasar el parámetro customerId es obligatorio, mientras que subAccountId es opcional.
Atención: Tenga cuidado de reemplazar ‘{’ y ‘}’ también. Por ejemplo, “={customerId}” se convierte en “=42”.
También necesitará utilizar los siguientes headers:
Header
Valor
Content-Type
application/json
authenticationToken
Token de Messaging1
userName
Nombre de usuario de Messaging1
En el exito, si hay sesiones abiertas para el cliente especificado y subAccountId, la solicitud devuelve un JSON con el atributo:
Atributo
Valor
file_url
Link para descargar un archivo de tipo csv que contiene los campos “source” y “session_created_at” de todos los destinos encontrados
Si no hay datos asociados con customerId y subAccountId, el archivo devuelto estará vacío, sólo con el encabezado.
Ejemplo de respuesta:
