Resumo

O CloudChat possui uma funcionalidade de "Enviar Evento Webhook". Através dela nós conseguimos construir integrações com qualquer sistema que consiga gerar um Webhook.

Quando o sistema não tem uma estrutura para criação de Webhook, somente API, é possível utilizar um intermediador (exemplos: n8n, Zapier, Make, Plugga...) para criar um Webhook e construir um fluxo de integração com o sistema alvo como por exemplo Hubspot, Jira e outros.

obs: as vezes é necessário construir um fluxo de "enriquecimento" dos dados que vieram do webhook utilizando uma API (por exemplo
IMPORTANTE: Esse tipo de integração costuma ser criado para integrações "de via única", ou seja, sem atualização de um campo específico. A complexidade de uma integração "de duas vias" é maior e geralmente vai exigir uma necessidade alta de uso de Webhook + API cloudchat + API/integração nativa do sistema alvo

Existem outras duas maneiras de construir essas integrações, porém possuem um nível de complexidade mais alto e tem objetivos diferentes:

Utilizar nossa API para puxar todos os dados de conversas, todos os dias e alimentar um datalake ou banco de dados: Objetivo costuma ser analítico ou de registro / consolidação de informações
- Lado negativo: Dado não vai ser criado real-time. Portanto pode ser ruim para Operação utilizar (exemplo: triagem em N2 / tech)
Utilizar o Eddie ao invés do intermediador como n8n, zapier ou make: Vai funcionar de maneira muito semelhante
- Lado negativo: Só vai funcionar para atendimentos que passarem pela ClaudIA

Detalhamento

Payload enviado pelo Webhook do CloudChat

Quando uma automação dispara um webhook, ela faz um POST HTTP para a URL configurada, enviando um JSON com as seguintes informações principais:

Estrutura do payload (JSON)

event - O tipo de evento que disparou o webhook (ex: message_created, conversation_created, etc.)
content - O conteúdo da mensagem
message_type - Tipo da mensagem (incoming, outgoing, etc.)
conversation - Objeto com dados da conversa, incluindo id, status, etc.
sender - Objeto com dados do remetente (contato), incluindo id, name, email, phone_number, etc.
account - Objeto com dados da conta, incluindo:
- idinbox - Objeto com dados da inbox/canal
- contact - Dados do contato associado

Exemplo prático (baseado no código)

Como visto no exemplo de integração com Rasa:

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

Resumo do JSON típico que chega no seu 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"
  }
}

O que fazer caso o Webhook não contenha o dado que você precisa

Nessa situação você vai precisar utilizar os "id"s gerados (ex.: inbox.id, conversation.id, sender.id) para fazer uma chamada de API no cloudchat e coletar essa informação para poder enviar para o outro sistema.

Em resumo:

O webhook envia um POST com JSON contendo os dados do evento, da conversa, do contato/remetente, da conta e da inbox, junto com o conteúdo da mensagem e o tipo de mensagem. Isso permite que o sistema externo (que recebe o webhook) saiba exatamente o que aconteceu e tome a ação adequada.

Como montar integrações entre sistemas (Automações + Webhook)