Cómo Crear Integraciones entre Sistemas con Automatizaciones y Webhook
:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso
de divergencia entre este artículo y la referencia, prevalece lo que está allí.
:::
Resumen
Cloud Chat cuenta con una funcionalidad de "Enviar Evento Webhook". A través de ella podemos construir integraciones con
cualquier sistema que pueda generar un Webhook.
Cuando el sistema no tiene una estructura para la creación de Webhooks, solo API, es posible utilizar un intermediario
(ejemplos: n8n, Zapier, Make, Plugga...) para crear un Webhook y construir un flujo de integración con el sistema
destino, como por ejemplo Hubspot, Jira y otros.
- nota: a veces es necesario construir un flujo de "enriquecimiento" de los datos que llegaron del webhook utilizando
una API (por ejemplo
- IMPORTANTE: Este tipo de integración suele crearse para integraciones "de una sola vía", es decir, sin actualización
de un campo específico. La complejidad de una integración "de dos vías" es mayor y generalmente va a exigir un uso
intensivo de Webhook + API de Cloud Chat + API/integración nativa del sistema destino
Existen otras dos maneras de construir estas integraciones, pero tienen un nivel de complejidad más alto y objetivos
diferentes:
- Utilizar nuestra API para extraer todos los datos de las conversaciones, todos los días, y alimentar un datalake o
base de datos: El objetivo suele ser analítico o de registro / consolidación de información
- Lado negativo: El dato no se va a crear en tiempo real. Por lo tanto, puede ser malo para que Operaciones lo
utilice (ejemplo: triaje en N2 / tech)
- Utilizar el Flujo Controlado en lugar del intermediario como n8n, Zapier o Make: Va a funcionar de manera muy
similar
- Lado negativo: Solo va a funcionar para las atenciones que pasen por ClaudIA
Detalle
Payload enviado por el Webhook de Cloud Chat
Cuando una automatización dispara un webhook, realiza un POST HTTP a la URL configurada, enviando un JSON con la
siguiente información principal:
Estructura del payload (JSON)
- event - El tipo de evento que disparó el webhook (ej.: message_created, conversation_created, etc.)
- content - El contenido del mensaje
- message_type - Tipo de mensaje (incoming, outgoing, etc.)
- conversation - Objeto con datos de la conversación, incluyendo id, status, etc.
- sender - Objeto con datos del remitente (contacto), incluyendo id, name, email, phone_number, etc.
- account - Objeto con datos de la cuenta, incluyendo:
- idinbox - Objeto con datos de la inbox/canal
- contact - Datos del contacto asociado
Ejemplo práctico (basado en el código)
Como se ve en el ejemplo de integración con Rasa:
@app.route('/rasa', methods=['POST'])
def rasa():
data = request.get_json()
message_type = data['message_type']
message = data['content']
conversation = data['conversation']['id']
Resumen del JSON típico que llega a tu endpoint:
{
"event": "message_created",
"message_type": "incoming",
"content": "Olá, preciso de ajuda!",
"id": 12345,
"conversation": {
"id": 678,
"status": "open",
"channel": "web_widget",
"contact_inbox": { ... }
},
"sender": {
"id": 90,
"name": "João Silva",
"email": "[email protected]",
"phone_number": "+5511999999999"
},
"account": {
"id": 1
},
"inbox": {
"id": 10,
"name": "Website Widget"
}
}
Qué hacer si el Webhook no contiene el dato que necesitas
En esa situación vas a necesitar utilizar los "id"s generados (ej.: inbox.id, conversation.id, sender.id) para hacer una
llamada a la API de Cloud Chat y obtener esa información para poder enviarla al otro sistema.
:::info El conversation.id que llega en el webhook es el número del ticket que aparece en la interfaz (ej.: #678) — el
mismo número que usas en las URLs de las APIs de conversaciones.
:::
En resumen:
El webhook envía un POST con JSON que contiene los datos del evento, de la conversación, del contacto/remitente, de la
cuenta y de la inbox, junto con el contenido del mensaje y el tipo de mensaje. Esto permite que el sistema externo (que
recibe el webhook) sepa exactamente qué ocurrió y tome la acción adecuada.
