Si deseas que tu sistema externo (ERP, CRM, base de datos, etc.) se comunique directamente con el chatbot de Mercately, necesitas contar con un endpoint (API) que cumpla ciertas condiciones técnicas. En este artículo te explicamos los parámetros clave, formatos de respuesta y configuraciones necesarias para lograr una integración exitosa.
1. Formato y tipo de contenido
El bot de Mercately únicamente acepta solicitudes POST y el contenido debe ser enviado en formato:
Este formato es esencial para que el bot pueda procesar y presentar correctamente la información enviada por tu sistema.
2. Estructura esperada del response
La respuesta del endpoint debe contener ciertos parámetros específicos según el comportamiento que desees que tenga el bot. A continuación te explicamos cada uno:
Parámetro | Requerido | Descripción |
| ✅ Obligatorio | Texto que el bot enviará al usuario final. Debe estar bien estructurado, claro y representativo del resultado de la solicitud. |
| ❌ Opcional | Usado si deseas que el bot genere opciones dinámicas. Representa el nombre del grupo de opciones. |
| ❌ Opcional | Estructura de tipo lista para generar respuestas seleccionables por el usuario. Solo se usa si se crean opciones dinámicas. Debe incluir: |
Ejemplo de respuesta esperada (con opciones dinámicas)
{
"message": "Selecciona tu sucursal:",
"option_name": "Sucursales disponibles",
"options": [
{
"key": "SCQ01",
"value": "Sucursal Quito - Centro"
},
{
"key": "SCG02",
"value": "Sucursal Guayaquil - Mall del Sol"
}
]
}Ejemplo de respuesta esperada (mensaje simple)
{
"message": "ID: 12345\nNombres: PEDRO PÉREZ\nEstado: ACTIVO\nDeuda: $30\nVencimiento: 25-11-2020"
}3. Códigos de respuesta HTTP
Es fundamental que el endpoint utilice correctamente los códigos de estado HTTP para que Mercately pueda interpretar si la integración fue exitosa o fallida:
200 (OK) → La solicitud fue procesada correctamente. El bot continuará con el flujo.
Cualquier otro código (ej: 400, 500, etc.) → El bot considerará que hubo un fallo y mostrará un mensaje de error, si está configurado para ello.
Consideraciones adicionales
Seguridad: Recomendamos utilizar autenticación por medio de
headerspersonalizados (como tokens), que puedes definir directamente en la configuración del paso “Enviar respuesta a endpoint”.Tiempos de respuesta: El endpoint debe responder en menos de 10 segundos para evitar que el bot se detenga por timeout.
Pruebas: Se recomienda testear el endpoint desde herramientas como Postman antes de conectarlo con el bot.