Botmaker API para WhatsApp

Botmaker te provee acceso oficial para enviar y recibir mensajes de WhatsApp a más de 1500 millones de usuarios en el mundo.

Puedes enviar mensajes sin programar y activando tu bot respondiendo tus mensajes manualmente utilizando la plataforma Botmaker y también acceder a Botmaker API para WhatsApp para conectar tus aplicaciones ahora mismo.

¡Solo te llevará 15 minutos!

Puedes probarlo ahora mismo aquí ó aquí

Consideraciones iniciales

  • El proceso de aprobación de tu cuenta se hace solo por única vez. Mientras eso sucede, puedas empezar ahora mismo a utilizar nuestro sandbox para experimentar la experiencia y diseñar tu proceso de atención manual o automática.

  • Una vez que te integres, hay dos formas de iniciar una conversación con tus usuarios:

    1. Los usuarios pueden iniciar la conversación con tu marca. Para ello puedes publicar tu número de WhatsApp en anuncions, sitios web e inclusive utilizar el url de auto activación: whatsapp://send?phone=tu_numero&text=Hola! o https://wa.me/tu_numero/?text=Hola!

    2. También puedes contactar a los usuarios desde tu lado (sin que antes hayan chateado con tu empresa). En este caso es importante que previamente hayas solicitado un opt-in por parte de ellos en tu website o mobile app. Por ejemplo un formulario de registración, email etc.

  • WhatsApp proteje a sus usuarios contra prácticas de spam: tus usuarios pueden iniciar una conversación por cualquier motivo. En el caso de que tu los contactes deben ser por alguna de las siguientes razones aprobadas: Actualizaciones o alertas de cuenta, información de turnos/citas, novedades de alguna actividad generada previamente, novedeades en procesos de pagos, finanzas personaes, novedades en reservas, en estado de envíos, cambios en tickets, novedades de transporte, etc. No está permitido enviar mensajes de publicidad o venta.

  • Para aprobar tu cuenta envia un email a [email protected] indicando:

    1. Tu Business Manager Id que puedes obtener en Facebook Business Manager

    2. (si aun no tienes una cuenta, la puedes crear siguiendo estos pasos

    3. El o los números telefónicos que quieras utilizar para tu cuenta de WhatsApp. En general un solo número es suficiente pero puedes querer tener más para diferenciar idiomas (ej: línea Español, línea Portugués), ambientes (ej: Producción, QA) o países.

Podemos proveerte números en Argentina y Brasil

En caso de que quieras usar tus números, ten en cuenta que puedas utilizar números de teléfonos fijos. Si nos indicas un número de celular, este no debe haber tenido WhatsApp instalado en los últimos 6 meses

  • Información para el perfil de la cuenta WhatsApp

    • Foto de perfil. Debe ser una imagen cuadrada de al menos 192×192 píxeles. Ten en cuenta que solo la parte circular central va a verse en la lista de contactos:

Profile picture

  • Texto descriptivo del perfil para los campos About, Dirección, Descripción del comercio, Categoría, email de contacto y sitio web

Enviando mensajes a los usuarios

Es posible enviar mensajes a los usuarios utilizando la consola del operador, generando notificaciones masivas y programando envíos por diferentes estímulos. Y también se puede utilizar el API de Botmaker para disparar mensajes programáticamente desde un sistema.

Para ellos debes:

  • Obtener un token para acceder el API

  1. Selecciona Botmaker API - Credenciales

  2. Genera un token o utiliza el que ya está generado. En particular es importante que guardes el Access Token

accesstoken

  • Con el access token, se puede efectuar el llamado via HTTP Post al API rest 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 va a ser un http code 200 con un JSON indicando el id del mensaje generado:

{
"id": "id_del_mensaje"
}

cada vez que un mensaje es enviado al usuario, se efectua un chequeo de control de saldo de tu cuenta Botmaker. Si la cuenta está cerca de quedar sin saldo, el servicio va a devolver un http code 403 - Forbidden indicando que no hay saldo para enviar mensajes en el JSON de respuesta

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

cada vez que un mensaje es enviado al usuario, se efectua un chequeo para determinar si el mensaje va a ser rechazado por WhatsApp ya que el usuario no habló con la plataforma desde hace 24hs. Ver la sección Templates messages para más información.

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

Mensajes multimedia

Botmaker permite enviar todos los tipos de mensajes multimedia soportados por WhatsApp y otros canales. Para ello deber crear un mensaje desde Reglas siguiendo la información de Como crear respuestas en nueva nueva Regla.

Luego puedes llamar al servicio de activación de reglas (/api/v1.0/intent/v2) 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 se puede usar el servicio normal de mensajería (/api/v1.0/message/v3) y especificar la URL del archivo de media que se quiere envíar

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": "file_caption",
"audioURL": "audio_to_send",
"imageURL": "image_to_send",
"fileURL", "file_to_send"
}'
'https://go.botmaker.com/api/v1.0/message/v3'
# 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

Puedes elegir uno o varios de los tipos de media para enviar en un mensaje. Aquí hay una lista de formato de archivo válidos. Por el momento WhatsApp no tiene soporte de video.

Chequear validez de números de contactos de WhatsApp

Es posible verificar si un número de teléfono es válido para WhatsApp, y alternativamente obtener el formato adecuado de ese número.

El endpoint para verificar es /api/v1.0/customer/checkWhatsAppContact y se compone así:

curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'access-token: your_token'
-d '{
"chatChannelNumber": "your_phone_number",
"contacts": ["user_phone"]}'
'https://go.botmaker.com/api/v1.0/customer/checkWhatsAppContact'
# your_token: your access token
# your_phone_number: whatsapp number of yours
# contacts: an array of users phones

Aplicar formato a mensajes desde API

Se puede aplicar formato simples a textos de mensajes que se envían a los usuarios. "Hola Juan". Para más información revisar la documentación de formato de WhatsApp.