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
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.
Detalhes da conexão
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
Destination
Message
Template
Header
Element
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
Estado
Erros
Outros status
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:
Respuesta de error de autenticación (401)
Si hay un problema con la autenticación, se devolverá el siguiente mensaje:
Actualización de estado de devolución de llamada
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:
Dados:
ClientInfo
Status
Status que podem ser enviados no callback:
MO (mensajes enviados por el usuario final a la cuenta 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.
Dados
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.
Mensaje:
UserProfile:
Location:
Contact:
Address:
Email:
Name:
Org:
Phone:
Url:
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
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
Notas para la primera línea::
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 “ ; ”
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}
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:
Respuesta
En caso de éxito, si hay datos asociados con customerId y subAccountId, la solicitud devolverá un JSON con 3 atributos:
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:
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
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:
Si no hay datos asociados con customerId y subAccountId, el archivo devuelto estará vacío, con solo el encabezado.
Ejemplo de respuesta:
Destino:
Mensaje:
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
Imagen:
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
Audio:
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)
Documento:
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
Contact:
Ejemplo de envio de contactos
Address:
Email:
Name:
Org:
Phone:
Url:
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
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:
Destino:
Mensaje:
HSM:
Envío de mensajes template
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:
Destino:
Mensaje:
Template:
Header:
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:
Respuesta de error de autenticación (401)
Si hay un problema en la autenticación del usuario, se espera el siguiente mensaje de error:
Callback de actualización de estado
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:
Datos:
ClientInfo
Estatus
Estatus que puedem ser enviados en el callback:
MO (Mensajes enviados por el usuario final a la cuenta 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:
Control de flujo de MO - Listas de segmentación
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.
Mensaje:
UserProfile:
Location:
Contact:
Address:
Email:
Name:
Org:
Phone:
Url:
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.
API SFTP WhatsApp
Detalle de Conexión
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
Envío de mensajes a través de SFTP
Para realizar el disparo de mensajes vía FTP es necesario generar un archivo con el formato siguiendo el ejemplo abajo: Mensaje HSM:
2018-10-16;10:00;20:00;HSM;chatclub_welcome;pt_BR;DETERMINISTIC;nome|empresa telefone;nome;empresa 551999999999;Nome1;Wavy 551999999999;Nome2;Movile
** 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 “;”
Consulta de listas vía API
Solicitud
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}
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:
Puede obtener su nombre de usuario y su token a través de la plataforma: https://messaging.wavy.global
Respuesta
En caso de éxito, si hay datos asociados al customerId y al subAccountId, la solicitud devuelve un JSON con 3 atributos:
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:
Consulta sesiones abiertas vía API
Solicitud
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:
Respuesta
En el exito, si hay sesiones abiertas para el cliente especificado y subAccountId, la solicitud devuelve un JSON con el atributo:
Si no hay datos asociados con customerId y subAccountId, el archivo devuelto estará vacío, sólo con el encabezado.
Ejemplo de respuesta:
Last updated
