¿Cómo acceder a Botmaker API para WhatsApp?

Aquí aprenderás como acceder a Botmaker API para WhatsApp.

Los mensajes enviados por los usuarios se pueden ver instantáneamente en la Consola de operador de Botmaker, donde es posible responder manualmente o mediante bots. También, es posible notificar a un sistema de estos mensajes. Si deseas recibir cada mensaje, puedes configurar un webhook en tus sistemas de la siguiente manera:

  • Una vez activado, comenzarás a recibir mensajes de acuerdo con las políticas de Google PubSub; mensajes firmados, preservación de mensajes durante 7 días, etc.

El siguiente ejemplo muestra un mensaje típico de un usuario:

{
"CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp
"MESSAGE": "Hola!", // the user message text
"CREATION_TIME": "a_date", // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
"FROM_NAME": "user_name", // name of user if possible
"CUSTOMER_ID": "user_id", // unique id of user
"_id_": "message_id", // unique id of message
"FROM": "phone_number", // user phone number
"SESSION_CREATION_TIME": "session_id", // chat session id
// other less important fields are also inclused in the message
...
}`

También admitimos archivos multimedia (mensajes de voz, audios, documentos, imágenes, etc.) ,como por ejemplo:

{
"FROM_NAME": "user_name", // name of user if possible
"IMAGES_URLS": [
"https://botmaker.com/hostedImageByUser.png"
],
...
}`

Enviando mensajes a usuarios

Es posible enviar mensajes a los usuarios utilizando la consola del operador, generando notificaciones masivas y programando el envío por diferentes estímulos. La API de Botmaker también se puede utilizar para activar mensajes de programa desde un sistema.

Para hacer esto, debes obtener un token de acceso API siguiendo los pasos a continuación:

  • Accede a la configuración del canal.

  • Selecciona la API de Botmaker - Credenciales.

  • Genera un token o utiliza el que ya se generó. En particular, es importante que guarde el token de acceso.

  • Con acceso al token, será posible hacer que la publicación HTTP llamada API descanse con un JSON:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_access_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone", "platformContactId": "user_phone","messageText": "message_to_send"}' 'https://go.botmaker.com/api/v1.0/message/v3'
# your_access_token: ey...
# your_phone: +55135433...
# user_phone: +5512324314..
# message_to_send: Hi!

La respuesta será un código http 200 con un JSON que indica la ID del mensaje generado:

{
"id": "id_del_mensaje"
}`

Cada vez que se envía un mensaje al usuario, se realizará una verificación de saldo en tu cuenta de Botmaker. Si la cuenta está a punto de quedarse sin saldo, el servicio devolverá un código http 403 - Prohibido, que indica que no hay saldo para enviar mensajes en la respuesta JSON:

{
"error": {
"code": 101,
"message": "Insufficient credit"
}
}`

Cada vez que se envíe un mensaje al usuario, se realizará una verificación para determinar si WhatsApp rechazará el mensaje, ya que el usuario no ha hablado contigo en la plataforma en las últimas 24 horas. Consulta la sección Plantillas de mensajes para obtener más información:

{
"error": {
"code": 201,
"message": "User window is over 24 hours"
}
}`

Plantillas de mensajes

WhatsApp permite a los usuarios enviar mensajes dentro de las 24 horas posteriores al último mensaje enviado por ellos. Fuera de este período, los mensajes deben enviarse utilizando la intención del punto final y realizando los siguientes pasos:

  • Accede al área de plantillas y envíalas.

  • Una vez aprobadas, se creará una intención con su nombre.

Simplemente haz la llamada al endpoint:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone_number", "platformContactId": "user_phone_number", "ruleNameOrId": "rule_name", "params": {"my_template_var":"var_value"}}' 'https://go.botmaker.com/api/v1.0/intent/v2'
# your_token: your access token
# your_phone_number: whatsapp number of yours
# user_phone_number: whatsapp number of user
# rule_name: botmaker rule name`

Mensajes multimedia

Botmaker te permite enviar todo tipo de mensajes multimedia compatibles con WhatsApp y otros canales. Para hacer esto, debes crear un mensaje en reglas siguiendo la página “Cómo crear respuestas en una página de intención”.

También puedes llamar al servicio de activación de reglas desde tu sistema. Por ejemplo:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone_number", "platformContactId": "user_phone_number", "ruleNameOrId": "rule_name", "params": {"param_key_1":"param_value_1"}}' 'https://go.botmaker.com/api/v1.0/intent/v2'`
# your_token: your access token
# your_phone_number: whatsapp number of yours
# user_phone_number: whatsapp number of user
# rule_name: botmaker rule name

Alternativamente, puedes usar el servicio de mensajería común y especificar la URL del archivo multimedia que deseas enviar.

# your_access_token: ey...
# your_phone: +55135433...
# user_phone: +5512324314..
# file_caption: a text description next to the file
# audio_to_send: https://....my_audio.mp3
# image_to_send: https://....my_photo.jpeg
# file_to_send: https://....my_file.pdf`

Elije uno o varios formatos de medios para enviar un mensaje. Aquí hay una lista de todos los formatos de archivo compatibles. WhatsApp actualmente no admite vídeos y GIF.

Cambios en el estado de los mensajes enviados

Después de enviar un mensaje al usuario, tu punto final recibirá notificaciones de entrega o lectura de ese mensaje.

  • Delivered indica que el mensaje fue enviado - verifica dos veces desde el WhatsApp.

  • Read indica que el mensaje fue leído por el usuario objetivo - doble verificación azul desde el WhatsApp.

{
"CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp
"CREATION_TIME": "a_date", // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
"CUSTOMER_ID": "user_id", // unique id of user
"_id_": "message_id", // unique id of message
"FROM": "phone_number", // user phone number
"STATUS": "el_cambio_status" // message read or delivered
}`

Si el usuario deshabilita la opción “confirmación de lectura” en la configuración de privacidad, estos mensajes no se recibirán.

Aplicar formatos a los mensajes a través de la API Es posible aplicar formatos simples al texto de los mensajes que se enviarán a los usuarios, por ejemplo, “Hola, John”. Para más información, consulta en Documentación de Formatos de WhatsApp.