Como integrar a Duotalk em outro sistema?

A Duotalk permite a integração direta com CRMs, planilhas e outros sistemas externos através do envio de Webhooks. Ao configurar esta integração, a plataforma envia um pacote de dados (Payload) em formato JSON sempre que ocorre um evento específico (como a abertura ou fecho de uma conversa).

Neste artigo, encontrará a documentação técnica necessária para configurar o seu endpoint e interpretar os dados recebidos.

Requisitos da Requisição

O seu sistema deve estar preparado para receber uma requisição HTTP com as seguintes características:

• Método HTTP: POST

• Formato do Corpo (Body): JSON

• Endpoint: URL do seu webhook (configurada na App Store da Duotalk).

Estrutura do JSON (Payload)

Abaixo encontra-se o exemplo completo do JSON enviado pela Duotalk. Note que alguns campos podem ser enviados como null dependendo do tipo de integração (abertura, transferência ou fecho).

{
  "method": "post",
  "url": "https://url-do-seu-sistema.com",
  "headers": {
    "Content-Type": "application/json",
    "token": "seu-token-de-autenticacao"
  },
  "params": {
    "api_key": "AccApp.params.api_key"
  },
  "data": {
    "id": "626c4d54a21c9d2b1c7cdf12",
    "canal": "WhatsApp 360 | Webchat AI | WhatsApp | Facebook | Instagram",
    "origem": "Inbound | Outbound | Campanha",
    "origemUrl": "https://link-de-origem.com",
    "qualificacaoLead": "Lead Qualificado",
    "intermediario": "Duotalk",
    "nomeDaEntidade": "Valor da entidade capturada no bot",
    "nomeDaIntencao": "Valor da intenção",
    "primeiraIntencao": "Valor da primeira intenção",
    "url_duotalk": "https://app.duotalk.io/apps/inbox/start-conversation?name=Rodrigo&phone=5511999999999",
    
    "nomeChatbot": "Nome do Fluxo/Bot",
    "tipoIntegracao": "abertura | 1ª resposta de campanha | Transferência | fechamento",
    
    "dataFechamento": "2023-10-01T00:00:00.000Z",
    "motivoFechamento": "Cliente comprou",
    "motivoFechamentoId": "id_do_motivo",
    "motivoPerda": "Preço alto",
    "valorVenda": "100.00",
    
    "integrationIdValue": "ID externo do operador (se configurado)",
    "operador": "Nome do Operador",
    "operadorId": "ID do operador na Duotalk",
    "operadorEmail": "operador@empresa.com",
    
    "operadorFechamento": "Nome do Operador que fechou",
    "operadorFechamentoId": "ID do operador que fechou",
    "operadorFechamentoEmail": "email@empresa.com",
    
    "nome": "Rodrigo",
    "telefone": "5511999999999",
    "email": "rodrigo@email.com",
    "mensagem": "Conteúdo da transcrição da conversa",
    "firstMessage": "Olá, gostaria de saber mais",
    "messageHistory": "Histórico completo em texto",
    
    "origemTitulo": "Campanha de Verão",
    "headline": "Título do Anúncio",
    "body": "Texto do anúncio",
    "source_type": "facebook_ads",
    "source_id": "id_do_anuncio",
    "source_url": "url_do_anuncio",
    "ctwa_clid": "identificador_clique_whatsapp"
  }
}

Requisição HTTP

A integração ocorre através de uma requisição HTTP do tipo POST para o endpoint do sistema externo.

• URL do Endpoint: https://url.webhook-do-sistema.com

• Método HTTP: POST

• Cabeçalhos:

  • Content-Type: application/json

  • token: Token de autenticação necessário para validar a requisição.

Dicionário de Dados

Entenda o significado de cada campo enviado dentro do objeto data:

Dados do Operador (Utilizador)

Estes campos são preenchidos se o atendimento tiver passado por um humano. Caso contrário, podem ser null ou system.

Dados de Fecho (Apenas para tipoIntegracao: "fechamento")

Dados de Campanha (Referral / Ads)

Campos populados geralmente quando a origem é uma campanha paga (Facebook/Instagram Ads).

Comportamento do Campo "mensagem"

O conteúdo do campo mensagem altera-se dependendo do tipoIntegracao:

• Abertura Inbound: Contém a conversa inicial do lead com o chatbot.

• Primeira resposta de campanha: Contém apenas a resposta do cliente após o envio do modelo (template).

• Transferência: Contém a transcrição completa da conversa até ao momento da transferência.

• Fechamento: Contém a transcrição completa da conversa até ao momento do encerramento.

Configurações Adicionais de Cabeçalhos

Além dos cabeçalhos básicos, a requisição pode conter as seguintes configurações:

• Access-Control-Allow-Headers: Lista de cabeçalhos permitidos na requisição.

• Access-Control-Allow-Methods: Métodos HTTP permitidos (ex: OPTIONS, GET, POST).

• Access-Control-Allow-Origin: Origem permitida para a requisição (por exemplo, pode ser definido para permitir todas as origens com *).

• Access-Control-Max-Age: Tempo máximo (em segundos) que a resposta do pré-vôo pode ser armazenada em cache (ex: 86400 para 24 horas).

Esse modelo fornece uma visão clara e estruturada sobre como a integração deve ser configurada e quais campos e valores são esperados na requisição.