Como acessar o menu de Integrações

A funcionalidade de Integrações permite que sistemas externos enviem dados para o UnderChat através de webhooks, criando automaticamente contatos e iniciando conversas.
Ela é ideal para conectar o UnderChat com CRM, e-commerce, formulários e outros sistemas que precisam iniciar atendimentos de forma automatizada.

Importante: cada integração é vinculada a um canal específico e utiliza uma chave de API única para autenticação.

---

Como criar uma Integração

Para começar a utilizar as integrações, você precisa criar uma nova e vinculá-la a um canal.
Cada integração pode ter apenas um canal associado.

Passo a passo

1. No menu lateral, clique em Integrações.
2. Clique no botão Adicionar.
3. Preencha o Nome e selecione o Canal.
4. Clique em Salvar para concluir.

---

Como gerar a Chave de API

Após criar a integração, você precisa gerar uma Chave de API.
Essa chave é usada para autenticar as requisições enviadas por webhook.

Passo a passo

1. Na lista de integrações, localize a integração desejada.
2. Clique no botão Gerar Chave.
3. Copie e guarde a chave gerada em um local seguro.

Importante: por segurança, a chave deve ser mantida em segredo.
Caso você precise trocar a chave, basta gerar uma nova — a chave anterior será desativada automaticamente.

---

Como configurar o Mapeamento do Webhook

O mapeamento define como os dados enviados pelo webhook serão interpretados e utilizados no UnderChat.
Você pode mapear campos do contato como nome, telefone, e-mail, etiquetas e mensagem.

Passo a passo

1. Na lista de integrações, localize a integração desejada.
2. Clique em Configurar.
3. A tela de mapeamento será aberta com os campos disponíveis para configuração.

---

Campos disponíveis para mapeamento

Na configuração da integração, você pode mapear os seguintes campos:

• Nome (obrigatório)
• Sobrenome (opcional)
• Apelido (opcional)
• Data de Nascimento (opcional)
• E-mail (opcional)
• DDI do Telefone (obrigatório)
• Telefone (obrigatório)
• Notas (opcional)
• Etiquetas (opcional)
• Mensagem (obrigatório quando o tipo estiver configurado)

---

Como mapear os campos

Em cada campo, você pode escolher entre usar um mapeamento do JSON (pegando valores do webhook enviado)
ou usar um texto fixo.

Mapear usando campos do JSON

Ao mapear usando o JSON, você seleciona o campo correspondente com base no último webhook recebido.

Usar texto fixo

Se você quiser definir um valor fixo (ex: DDI 55), use o botão Usar Textarea e preencha manualmente.

---

Visualizar dados do webhook recebido

Para facilitar o mapeamento, você pode visualizar a estrutura do último webhook recebido.
Isso ajuda a identificar exatamente quais campos devem ser utilizados.

1. Na tela de configuração, clique em Visualizar Dados do Webhook.
2. Uma janela será aberta mostrando o JSON completo recebido.
3. Use a estrutura exibida para encontrar os campos corretos para mapear.

---

Como configurar o Tipo de Mensagem

O tipo de mensagem define como o webhook será processado no UnderChat: se o sistema criará uma conversa comum na fila ou se iniciará um chatbot automaticamente.

---

Tipo: Mensagem

Quando o tipo é Mensagem, o webhook cria uma conversa normal que ficará na fila aguardando atendimento.

• Mensagem se torna obrigatória
• Você pode configurar Transferir para (Setor ou Usuário), se desejar direcionar automaticamente

---

Tipo: Chatbot

Quando o tipo é Chatbot, o webhook inicia automaticamente um chatbot de entrada, permitindo que o contato interaja com o robô antes de ir para atendimento humano.

• Chatbot de entrada é obrigatório
• Mensagem é obrigatória

Importante: se o tipo for Chatbot e você não selecionar um chatbot de entrada ou não configurar a mensagem, o sistema não permitirá salvar.

---

Transferir para Setor ou Usuário

Quando o tipo estiver como Mensagem, você pode configurar para transferir automaticamente o atendimento para um setor ou usuário específico.

• Transferir para Setor: o setor é obrigatório
• Transferir para Usuário: o usuário é obrigatório

---

Como enviar um Webhook para o UnderChat

Após configurar a integração e o mapeamento, seu sistema já pode enviar webhooks para o UnderChat.

Endpoint do webhook

O endpoint padrão é:

Exemplo de URL completa:

---

Estrutura da requisição

O webhook deve ser enviado via POST com corpo em formato JSON.
A estrutura do JSON pode ser livre, pois você irá mapear os campos conforme a necessidade.

{
  "leads": [
    {
      "first_conversion": {
        "source": "teste",
        "content": {
          "lead_info_attributes": {
            "mobile_phone": "61999999999",
            "first_name": "João",
            "last_name": "Silva",
            "email": "joao@example.com"
          }
        }
      }
    }
  ]
}

---

Como o sistema processa o webhook

Quando o webhook é recebido, o UnderChat executa os seguintes passos:

1. Validação: verifica se a chave de API é válida e está ativa.
2. Mapeamento: extrai os dados conforme o mapeamento configurado.
3. Criação/atualização do contato: salva nome, telefone, e-mail e demais campos.
4. Aplicação de etiquetas: adiciona etiquetas configuradas (se existirem).
5. Criação do atendimento: gera conversa normal ou inicia chatbot, conforme o tipo configurado.

Observação: o telefone é obrigatório. Se o telefone não for encontrado ou estiver inválido, o webhook será ignorado.

---

Como gerenciar Integrações

Na página de Integrações você consegue gerenciar tudo em uma tabela, com os principais dados e ações disponíveis.

• Nome da integração
• Status (ativa ou inativa)
• Canal vinculado
• Ações para gerenciar a integração

---

Ativar ou inativar Integração

Quando a integração estiver inativa, qualquer webhook enviado para ela será ignorado e nenhuma conversa será criada.

---

Editar Integração

Você pode editar a integração para alterar o Nome e o Canal vinculado.

---

Apagar Integração

Ao apagar uma integração, a chave de API é invalidada e os webhooks enviados com ela não serão mais processados.
Essa ação não pode ser desfeita.

---

Regras e comportamentos importantes

Campos obrigatórios

Os seguintes campos são obrigatórios para o funcionamento correto:

• Nome
• DDI do Telefone
• Telefone
• Mensagem (quando o tipo estiver configurado)
• Chatbot de entrada (quando o tipo for Chatbot)

Validações do sistema

• Se o telefone estiver inválido ou não for encontrado no mapeamento, o webhook é ignorado.
• Se o tipo for Chatbot e não houver chatbot selecionado, não é possível salvar.
• Se o tipo for Chatbot e não houver mensagem configurada, não é possível salvar.
• Se Transferir para Setor estiver selecionado, o setor é obrigatório.
• Se Transferir para Usuário estiver selecionado, o usuário é obrigatório.

---

Permissão necessária

Para criar, editar, configurar ou apagar integrações, seu usuário precisa ter as permissões adequadas no grupo de permissões.