How to Build Integrations Between Systems Using Automations and Webhooks

Summary

Cloud Chat has a "Send Webhook Event" feature. With it, we can build integrations with any system that can generate a Webhook.

When the system does not have a structure for creating a Webhook, only an API, it is possible to use an intermediary (examples: n8n, Zapier, Make, Plugga...) to create a Webhook and build an integration flow with the target system, such as Hubspot, Jira, and others.

• note: sometimes it is necessary to build a data "enrichment" flow for the data that came from the webhook using an API (for example

• IMPORTANT: This type of integration is usually created for "one-way" integrations, that is, without updating a specific field. The complexity of a "two-way" integration is higher and will generally require heavy use of Webhook + Cloud Chat API + the target system's native API/integration

There are two other ways to build these integrations, but they have a higher level of complexity and different goals:

• Using our API to pull all conversation data every day and feed a datalake or database: The goal is usually analytical or for recording / consolidating information

  • Downside: Data will not be created in real time. So it can be bad for Operations to use (example: triage in N2 / tech)

• Using the Controlled Flow instead of an intermediary like n8n, Zapier, or Make: It will work in a very similar way

  • Downside: It will only work for conversations that go through ClaudIA

Details

Payload sent by the Cloud Chat Webhook

When an automation triggers a webhook, it makes an HTTP POST to the configured URL, sending a JSON with the following main information:

Payload structure (JSON)

• event - The type of event that triggered the webhook (e.g., message_created, conversation_created, etc.)

• content - The message content

• message_type - Message type (incoming, outgoing, etc.)

• conversation - Object with conversation data, including id, status, etc.

• sender - Object with sender (contact) data, including id, name, email, phone_number, etc.

• account - Object with account data, including:

  • idinbox - Object with inbox/channel data

  • contact - Data of the associated contact

Practical example (based on the code)

As seen in the Rasa integration example:

@app.route('/rasa', methods=['POST'])
def rasa():
    data = request.get_json()
    message_type = data['message_type']
    message = data['content']
    conversation = data['conversation']['id']

Summary of the typical JSON that arrives at your 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"
  }
}

What to do if the Webhook does not contain the data you need

In this situation, you will need to use the generated "id"s (e.g., inbox.id, conversation.id, sender.id) to make an API call to Cloud Chat and collect that information so you can send it to the other system.

In summary:

The webhook sends a POST with JSON containing the data of the event, the conversation, the contact/sender, the account, and the inbox, along with the message content and the message type. This allows the external system (which receives the webhook) to know exactly what happened and take the appropriate action.