WhatsApp API
Documentación técnica: WhatsApp API.
Last updated
Documentación técnica: WhatsApp API.
Last updated
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.
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.
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