How to Build Integrations Between Systems Using Automations and Webhooks
:::info The most up-to-date documentation for the Cloud Humans APIs is at docs.cloudhumans.com/api-reference. If this
article and the reference differ, the reference prevails.
:::
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.
:::info The conversation.id that arrives in the webhook is the ticket number shown in the interface (e.g., #678) — the
same number you use in the conversation API URLs.
:::
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.
