¿Cómo enviar y recibir mensajes vía API?
Con este artículo podrás enviar y recibir mensajes a través de una API y escuchar mensajes provenientes de un Webhook estándar en la plataforma.
Con este artículo podrás enviar y recibir mensajes a través de una API y escuchar mensajes provenientes de un Webhook estándar en la plataforma.
Lectura estimada: 08 minutos
La plataforma Botmaker ofrece una amplia documentación de API que se pueden utilizar para diversos fines. Este artículo se centra en enviar y recibir exclusivamente a través de API. Para hacer esto, necesitarás usar la API de mensajería y activar un Webhook para que el servidor paralelo reciba mensajes del cliente final.
A continuación se muestra un diagrama de flujo del modelo de comunicación:
¿Cómo obtener credenciales para acceder a la API?
Para acceder a la API, necesita obtener un token de acceso. Para hacer esto, siga estos pasos:
- Una vez iniciado sesión en la plataforma Botmaker, acceda API de fabricante de robots dentro del menú
- ajustes, seleccione la opción Integraciones y finalmente seleccione API de fabricante de robots.
- Genera un token usando el botón Generar credenciales o utilizar uno ya generado.
- Este token se utilizará en el encabezado de sus llamadas a nuestra API.
¿Cómo enviar un mensaje?
Los mensajes se envían a través del punto final messages, específicamente send messages. Puede probar la API a través de la pestaña Documentación. Para hacer esto, seleccione el punto final en Chat Actions y luego la API send messages.
Para probar, siga estos pasos:
- Ingrese su token en el campo access-token en el tema de autenticación.
- En Cuerpo, reemplace el Canal ID por el ID del canal que deseas. La identificación se puede encontrar en el punto final List Channels en Channels.
- Reemplace la ContactID por el ID del contacto, si la conversación se realiza vía Whatsapp este ID será el número del cliente, en Webchat es un ID que se genera.
- Define qué mensaje deseas enviar con los ejemplos de la documentación como: Mensaje de texto, menú con botones, medios, ubicación y contacto.
- El campo webhookPayload puede definir variables adicionales que se enviarán mediante notificación de Webhook al servidor.
Aplicar formato a los mensajes
Es posible aplicar formatos simples a los textos de los mensajes que se enviarán a los usuarios.
- Itálico
Para escribir su mensaje en cursiva, inserte un guión bajo antes y después del texto.
- Negrita
Para escribir su mensaje en negrita, inserte un asterisco antes y después del texto.
- Tachado
Para tachar su mensaje, inserte una tilde antes y después del texto.
- monoespaciado
Para escribir su mensaje en monoespacio, inserte tres carteles graves antes y después del texto ("```").
Respuestas API
Hay 3 tipos de respuestas API estándar, a saber: 200 (Enviado correctamente), 400 (Error en algún parámetro del cuerpo o ID del chat), 429 (Límite de solicitudes por segundo excedido).
Puede seguir los ejemplos JSON generados directamente en la pestaña Documentación de API.
¿Cómo recibir mensajes?
Tan pronto como un usuario envía un mensaje a su WhatsApp, reenviemos ese mensaje a su webhook. De esta manera, recibirá todos los mensajes de todos sus usuarios en su sistema.
Para obtener información detallada sobre cómo administrar sus webhooks, consulte el artículo: ¿Cómo integrar webhooks?
Formato de notificaciones de webhook
Hay 3 tipos de webhooks disponibles en la plataforma:
- Mensaje y estado
- Gestión de WhatsApp
- Resultados de API asincrónica
Notificaciones de mensajes
Para recibir mensajes usaremos el tipo Mensagem e Status.La información que recibirá depende de qué datos son necesarios para su operación.
En la pantalla de configuración debería poder configurar la siguiente información:
- Ingrese la URL donde el webhook enviará mensajes: esta URL es el punto final público para comunicarse con su webhook. Aquí será donde enviaremos los eventos.
- Token de seguridad: puedes agregar uno, usar el sugerido o dejar el espacio en blanco: Si es necesario, podemos agregar un token para enviarlo como autenticación a su Endpoint. Se agregará al encabezado con la clave "auth-bm-token"
- Agregue o elimine canales conectados a este webhook (se requiere al menos 1): Aquí configuramos el canal de entrada del usuario que monitorearemos y enviaremos eventos a su servidor. Se requiere al menos un canal y se pueden configurar varios canales (por ejemplo, Whatsapp, Webchat, Instagram)
- Incluye los tipos de mensajes que deseas enviar a tu webhook: Aquí le informaremos qué fuente del evento/mensaje se enviará a su Webhook. Siendo ellos:
- Mensajes de robots:Todos estos son mensajes generados por el chatbot.
- Mensajes de usuario:Todos los mensajes recibidos en la plataforma que el usuario envía en el canal (Whatsapp, webchat, Instagram).
- Mensajes del agente:Mensajes generados por un asistente humano.
- Estado del mensaje:Registra los eventos de los mensajes enviados (Entregado, leído, recibido, error).
- Solo estado de HSM:Registra los eventos de estado de los mensajes relacionados con la plantilla (Entregado, leído, recibido, error).
- Mensajes de eventos:Envía eventos generales de la plataforma, como usuario desbloqueado, usuario bloqueado, cambio de bot, etc.
- ¿Quieres incluir variables de cambio en el mensaje?: Al habilitar esta opción se enviarán variables que tengan un valor declarado durante el flujo del bot. Solo enviaremos la variable en el momento de la declaración.
Ejemplos de Notificaciones de mensajes
- Ejemplo de mensaje de texto enviado por el usuario:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"identificador de contacto": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"tipo": "mensaje",
"númerowhatsapp": "551144444444",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"en": "1.1",
"IdCliente": "2S1WE8VVOZD5RCR3WI33",
"mensajes": [
{
"fecha": "2024-02-14T13:04:00.610Z",
"fromName": "Usuario de prueba",
"_id_": "NDZGKUNNRC5PSHLRFZYJ",
"Del usuario",
"carga útil del cliente": "",
"mensaje": "Oye",
"IdOperador": nulo,
"deCliente": verdadero,
"cola": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Ejemplo de mensaje de texto enviado por el Bot:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"variables": {
"clienteIniciouAConversa": "verdadero"
},
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"identificador de contacto": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"tipo": "mensaje",
"númerowhatsapp": "551144444444",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"en": "1.1",
"IdCliente": "2S1WE8VVOZD5RCR3WI33",
"mensajes": [
{
"fecha": "2024-02-14T13:04:00.667Z",
"intentName": "Mensaje inicial",
"fromName": "Bot"
"_id_": "MYQAVYSR5H6HGA1KEFGQ",
"de": "robot",
"carga útil del cliente": "",
"message": "¡Bienvenido usuario a Botmaker! 👋",
"IdOperador": nulo,
"cola": "_default_"
}
],
"_id_": "NJZX2WDAFF0IKHLF6JQ6",
"de": "robot",
"carga útil del cliente": "",
"message": "¿Cómo puedo ayudarte?",
"IdOperador": nulo,
"cola": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Ejemplo de lista de botones enviados por el Bot:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"variables": {
"clienteIniciouAConversa": "verdadero"
},
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"identificador de contacto": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"tipo": "mensaje",
"númerowhatsapp": "551144444444",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"en": "1.1",
"IdCliente": "2S1WE8VVOZD5RCR3WI33",
"mensajes": [
{
"fecha": "2024-02-14T13:04:00.671Z",
"intentName": "Mensaje inicial",
"fromName": "Bot"
"opciones": [
{
"tipo": "devolución de datos",
"value": "Tipos de respuesta📲"
},
{
"tipo": "devolución de datos",
"value": "Comercio electrónico sin chat🛍"
},
{
"tipo": "devolución de datos",
"valor": "Geolocalización 🌍📍"
},
{
"tipo": "devolución de datos",
"value": "2FA - Correo electrónico 🏷️"
},
{
"tipo": "devolución de datos",
"valor": "Integraciones🔄"
},
{
"tipo": "devolución de datos",
"value": "Habla con una persona"
},
{
"tipo": "devolución de datos",
"valor": "Sugerencias 📚"
}
],
"_id_": "NJZX2WDAFF0IKHLF6JQ6",
"de": "robot",
"carga útil del cliente": "",
"message": "¿Cómo puedo ayudarte?",
"IdOperador": nulo,
"cola": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Ejemplo de mensaje de audio:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"identificador de contacto": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"tipo": "mensaje",
"númerowhatsapp": "551144444444",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"en": "1.1",
"IdCliente": "2S1WE8VVOZD5RCR3WI33",
"mensajes": [
{
"fecha": "2024-02-14T13:08:59.687Z",
"hasAttachment": verdadero,
"fromName": "Usuario de prueba",
"_id_": "4OKNABQ06A68IJ7PHT5K",
"Del usuario",
"audio": "https://storage.googleapis.com/storage.botmaker.com/public/res/botmakerparaeventos/users/1c2e/be71/8c29/6005/59a0/d437/0d7d/1ef2/1c2ebe718c29600559a0d4370d7d1ef2.ogg",
"carga útil del cliente": "",
"IdOperador": nulo,
"deCliente": verdadero,
"cola": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Ejemplo de presentación de documentos:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"identificador de contacto": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"tipo": "mensaje",
"númerowhatsapp": "551144444444",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"en": "1.1",
"IdCliente": "2S1WE8VVOZD5RCR3WI33",
"mensajes": [
{
"fecha": "2024-02-14T13:10:06.592Z",
"hasAttachment": verdadero,
"archivo": "https://storage.googleapis.com/storage.botmaker.com/public/res/botmakerparaeventos/users/23da/b4b0/46c6/94bf/a7e0/ad49/9c25/0a90/23dab4b046c694bfa7e0ad499c250a90.pdf",
"fromName": "Usuario de prueba",
"_id_": "0EQR1JLFQLCS3TLEFP2A",
"caption": "EBOOK_FESTA-JUNINA_1306 (1).pdf",
"Del usuario",
"carga útil del cliente": "",
"IdOperador": nulo,
"deCliente": verdadero,
"cola": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Ejemplo de carga de imagen:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"identificador de contacto": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"tipo": "mensaje",
"númerowhatsapp": "551144444444",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"en": "1.1",
"IdCliente": "2S1WE8VVOZD5RCR3WI33",
"mensajes": [
{
"fecha": "2024-02-14T13:11:53.996Z",
"imagen": "https://storage.googleapis.com/storage.botmaker.com/public/res/botmakerparaeventos/users/c330/28cd/10c1/ce5f/4574/0209/07fc/8006/c33028cd10c1ce5f4574020907fc8006.jpeg",
"hasAttachment": verdadero,
"fromName": "Usuario de prueba",
"_id_": "DT5ZUX4QAVL86400KG5N",
"Del usuario",
"carga útil del cliente": "",
"IdOperador": nulo,
"deCliente": verdadero,
"cola": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Ejemplo de envío de un flujo (este modelo de envío porque los flujos aún están en Beta según el objetivo):
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2024-01-26T01:13:58.455Z",
"identificador de contacto": "558393846412",
"sessionId": "31JAOCZKUCK6HPH0NVKT_2024-02-14T13:18:45.730Z",
"tipo": "mensaje",
"númerowhatsapp": "5511123123123",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:18:45.730Z",
"en": "1.1",
"customerId": "31JAOCZKUCK6HPH0NVKT",
"mensajes": [
{
"fecha": "2024-02-14T13:22:45.401Z",
"imagen": "https://storage.googleapis.com/storage.botmaker.com/public/res/testegrupomacro/20240201-QISCSaluLphxOommBBkjNPt0bgt1-YJ00Y-.jpeg",
"hasAttachment": verdadero,
"intentName": "Flujos 2",
"fromName": "Bot"
"_id_": "JMYH3A443IGDV3VKH6LG",
"de": "robot",
"carga útil del cliente": "",
"message": "Elige las fechas de tu cita ahora 📅🌎",
"IdOperador": nulo
}
],
"chatChannelId": "prueba-canal-whatsapp-5511123123123"
}
- Ejemplo de envío de un mensaje por parte del operador:
{
"apellido": "Prueba",
"plataformachat": "whatsapp",
"whatsappNickName": "Usuario de prueba",
"customerCreationTime": "2024-01-26T01:13:58.455Z",
"identificador de contacto": "558393846412",
"sessionId": "31JAOCZKUCK6HPH0NVKT_2024-02-14T13:18:45.730Z",
"tipo": "mensaje",
"númerowhatsapp": "5511123123123",
"firstName": "Usuario",
"sessionCreationTime": "2024-02-14T13:18:45.730Z",
"en": "1.1",
"customerId": "31JAOCZKUCK6HPH0NVKT",
"mensajes": [
{
"fecha": "2024-02-14T13:26:21.287Z",
"operatorEmail": "Usuário@botmaker.io",
"fromName": "Usuario Almeida",
"_id_": "SYWT2YP7TXWOF23LVU6N",
"de": "operador",
"carga útil del cliente": "",
"mensaje": "Oi\n",
"operatorId": "QISCSaluLphxOommBBkjNPt0bgt1",
"operatorName": "Usuario Almeida",
"cola": "_default_",
"operatorRole": "ADMIN"
}
],
"chatChannelId": "prueba-canal-whatsapp-5511123123123"
}
Recuerda visitar nuestro Central de Ayuda para más informaciones.
Escrito por: Equipo Botmaker
Actualizado: 08/02/2024