Cómo Crear Integraciones entre Sistemas con Automatizaciones y Webhook

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.

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.