Esta área reúne tudo o que você precisa para conectar o AtendeSEG a outros sistemas: enviar e receber dados em tempo real, disparar mensagens a partir de eventos externos, consultar informações dentro do chatbot e manter contatos, etiquetas e oportunidades sincronizados via API. É a ponte entre a sua operação de atendimento e o resto do seu ecossistema.

Novidades nas integrações

As integrações evoluem constantemente. Veja as principais entregas recentes:

20/10/2025

Lançamento da API da Pipeline.

21/05/2025

Forçar atendimento para departamento / aba de pendentes e encerrar atendimento via API. Criar, buscar e deletar etiquetas nas configurações via API.

25/03/2025

Disparo de mensagem avulsa (API oficial do WhatsApp) através da API de envio de mensagem.

18/02/2025

Novo Webhook para oportunidades.

15/01/2025

Novas funcionalidades no Novo Push. Adicionar ou remover etiquetas e campos customizados via API de contatos. Busca de clientes pelo número do WhatsApp.

O que é um JSON?

JSON (JavaScript Object Notation) é um formato simples de troca de dados. É uma forma de organizar informações de maneira clara, usando pares de "nome" e "valor" — o que permite que sistemas diferentes entendam e compartilhem dados entre si.

Imagine uma lista de compras com "Maçã" e a quantidade "10". Em JSON, isso ficaria assim:

{
  "Nome": "Maçã",
  "Quantidade": 10
}

É, basicamente, uma lista de informações que pode ser facilmente lida e usada por programas de computador. Praticamente todas as integrações desta página trocam dados nesse formato.

Onde tudo começa: Configurações → API/Webhook

O ponto de partida das integrações é o menu Configurações → API/Webhook. A partir dele você acessa:

API (Push)

Gera um endpoint autenticado para disparar mensagens ao WhatsApp do cliente a partir de sistemas externos.

Webhook

Envia dados em JSON do AtendeSEG para um sistema externo quando determinados eventos acontecem.

Documentação

Aba com os modelos prontos e as URLs autenticadas do seu ambiente para as APIs REST (templates, usuários, etiquetas, pipeline e contatos).

Integração via Chatbot

As integrações via ChatBot são feitas por meio de requisições a APIs externas. Dentro das etapas do bot, em Condições → Rotear para → API, você consegue buscar ou enviar dados para plataformas externas.

Um fluxo típico funciona assim: você pergunta um dado ao cliente (por exemplo, o CPF ou CNPJ), salva a resposta em uma variável temporária e usa essa variável na requisição.

Montando a requisição

Ao configurar a requisição, você escolhe o método (GET, POST etc.) e informa a URL/endpoint externo. Na URL é possível inserir variáveis quando a API exige — entre chaves duplas:

https://endpointteste.com/api/{{cpf_cnpj}}

A tela de requisição é dividida em quatro áreas:

Cabeçalhos da requisição

Onde vão as autorizações e os headers exigidos pela API (por exemplo, um token de autenticação).

Parâmetros da requisição

Campos de query params. Veja o aviso abaixo sobre a forma recomendada de usá-los.

Body da requisição

O corpo em JSON enviado para a API (em métodos como POST), além de autorizações que precisem ir no corpo.

Mapeamento da Resposta

Onde você captura os dados retornados pela API e os guarda em variáveis temporárias para apresentar ao cliente na etapa seguinte.

Mapeando a resposta da API

No Mapeamento da Resposta, você associa um campo retornado pela API a uma variável temporária. Na etapa seguinte do chatbot, basta imprimir essa variável entre chaves duplas para mostrar o valor ao cliente.

Suponha que a API retorne um campo msg e um array contratos:

{
  "msg": "Contrato(s) localizado(s)",
  "contratos": [
    { "contratoId": "159632", "status": "Cancelado" },
    { "contratoId": "204871", "status": "Ativo" }
  ]
}

Para um valor único como o msg, mapeie-o para uma variável (por exemplo, mensagem_retorno) e imprima na próxima etapa:

{{mensagem_retorno}}

{{#contratos}}
{{contratoId}}
{{/contratos}}

O bloco entre {{#contratos}} e {{/contratos}} é repetido para cada item do array, imprimindo o contratoId de cada contrato do cliente.

API (Push): disparar mensagens

Com a API (Push) você conecta o AtendeSEG a Webhooks ou requisições de sistemas externos para disparar uma mensagem ao WhatsApp do cliente — tanto via WhatsApp Business (QR Code) quanto via API Oficial.

Para criar, vá em Configurações → API/Webhook → ADICIONAR e preencha três campos:

Nome da API

Uma descrição para identificar o sistema externo.

Enviar por

O canal de WhatsApp por onde as mensagens serão enviadas aos clientes.

Ação no atendimento após o envio

O que acontece com o ticket depois do disparo (veja as opções abaixo).

As opções de ação no atendimento são:

• Fechar: mantém o ticket na aba de fechados após o envio.
• Manter aberto: deixa na aba de pendentes, sem departamento vinculado.
• Redirecionar para fila: deixa na aba de pendentes com um departamento vinculado.
• Redirecionar para usuário: envia para a aba de ativos de um atendente.

Ao salvar, você obtém o endpoint autenticado, que recebe as requisições.

JSON — WhatsApp Business

Corpo (body) da requisição para um canal WhatsApp Business:

{
  "number": "5598991199469",     // número do WhatsApp do cliente (obrigatório)
  "body": "seu texto aqui",        // texto enviado ao cliente (obrigatório)
  "externalKey": "Qualquer valor", // valor livre, fica apenas nos logs (obrigatório)
  "mediaUrl": "https://",          // link de mídia; convertido em arquivo nativo
  "userId": 183,                   // id do atendente
  "onlyNote": true,                // enviar somente a nota interna, sem mensagem
  "forceTicketToUser": true,       // forçar ticket para um usuário
  "forceTicketToDepartment": true, // usar junto de queueId; move para pendentes
  "queueId": "435",                // id do departamento
  "forceTicketToClosed": true,     // força o ticket para a aba de fechados
  "closingReasonId": 123,          // id do motivo de fechamento
  "chatbotId": 56,                 // ativa um chatbot (não usar com forceTicketToClosed)
  "note": {                        // dispara nota interna (visível só ao atendente)
    "body": "seu texto aqui",
    "mediaUrl": "https://"
  }
}

Os campos number, body e externalKey são obrigatórios. Veja o que cada campo faz:

JSON — API Oficial (WABA)

Para a API Oficial, no campo Enviar por selecione um canal com API oficial. O corpo usa um template aprovado (pelo seu templateId/hsmId):

{
  "number": "556400000000",        // número do cliente
  "templateId": "uuid-template",   // hsmId do template aprovado
  "params": ["variavel1", "variavel2"], // se o template tiver variáveis
  "externalKey": "qualquer valor",
  "userId": 183,
  "onlyNote": true,
  "forceTicketToUser": true,
  "forceTicketToDepartment": true,
  "queueId": "435",
  "forceTicketToClosed": true,
  "closingReasonId": 123,
  "chatbotId": 56,
  "note": {
    "body": "seu texto aqui",
    "mediaUrl": "https://"
  }
}

O templateId (hsmId) é obtido pela API de Templates.

Regras e precedência

forceTicketToClosed

Tem precedência sobre todos os outros parâmetros e força o ticket para fechado, mesmo que ele não tenha origem via API.

forceTicketToUser + forceTicketToDepartment

Se usados juntos, garanta que o usuário informado tenha acesso ao departamento informado.

queueId

O id do departamento é encontrado em Configurações → Departamentos.

closingReasonId

O id do motivo de fechamento é encontrado em Configurações → Motivos de fechamento.

Webhook: enviar eventos para fora

Com a funcionalidade de Webhook, o AtendeSEG envia dados em JSON para um sistema externo através de eventos. Você informa a URL do sistema externo no campo URL Webhook.

URL Webhook

Endereço do sistema externo. Em geral já vem autenticada — nesse caso, o campo de token pode ficar vazio.

Token de autenticação

Opcional. Use quando a URL externa exigir um token à parte.

Eventos

Selecione quais eventos disparam o envio. A cada ocorrência, é enviado um JSON com dados do contato, do atendimento ou do atendente.

Novo Push

Com o Novo Push você faz o mapeamento do JSON que chega de outra plataforma e dispara uma mensagem personalizada ao cliente. Ao criar, informe o nome do Push, escolha a plataforma e o canal de envio (WhatsApp Business ou API Oficial).

Você pode integrar tanto com plataformas já homologadas (como o RD Station) quanto com o modo Personalizado — útil porque permite visualizar o JSON real que está sendo enviado pelo evento na plataforma externa.

Como descobrir o JSON que o sistema externo envia

1. Adicione qualquer JSON de teste, uma mensagem, um modelo de número e um nome de lead quaisquer e clique em salvar.
2. Copie a URL/endpoint (já autenticada) e adicione nas requisições/Webhooks do sistema externo.
3. Acione o evento e vá em Histórico de Envios. A mensagem de falha é esperada neste momento — você está apenas capturando o modelo do JSON. Clique em Detalhes e copie o JSON.
4. Volte ao Push, clique em editar e cole o JSON no modelo de dados.
5. Personalize a mensagem com as variáveis mapeadas. Adicione a variável referente ao número do cliente (se vier sem o DDI 55, coloque-o antes da variável).
6. Em Arquivo, informe um link de mídia presente no JSON — ele será convertido em arquivo nativo e enviado junto. Em Nome do lead, o valor é salvo direto no nome do cliente.
7. Clique em Salvar. A partir daí, cada vez que a ação ocorrer no sistema externo, a mensagem é disparada.

As abas Envio, Condições e Funil

Envio

Onde você define a mensagem, o modelo do número, o link de arquivo e o nome do lead.

Condições

Decide se a mensagem será enviada, com base nos dados do JSON. Também permite adicionar etiquetas e status do lead.

Funil

Vincula um funil de mensagens ao cliente — basta selecionar o funil (e é possível adicioná-lo ou removê-lo).

Como funcionam as Condições

Primeiro, ative as condições. Depois, escolha se todas precisam ser verdadeiras para enviar, ou se pelo menos uma basta. Cada condição tem cinco campos:

1. A variável buscada no modelo de dados (JSON).
2. O operador de comparação.
3. O valor inserido manualmente para comparar com a variável.
4. A ação: adicionar etiqueta ou status do lead.
5. O valor da etiqueta ou status a ser adicionado.

Os 6 operadores disponíveis são:

APIs REST

Além dos disparos, o AtendeSEG oferece APIs para manter seus dados sincronizados. Os modelos e as URLs autenticadas do seu ambiente estão em Configurações → API/Webhook → Documentação.

API de Contatos

Permite criar contatos (POST), buscar vários (GET), buscar um pelo id (GET) e editar (PATCH). Todos os endpoints exigem o cabeçalho de autenticação:

{
  "Authorization": "Bearer seu_token"
}

Payload completo do método PATCH:

{
  "name": "string",
  "email": "string",
  "number": "string",
  "customFields": "{ 'field1': 'value1', 'field2': 'value2' }",
  "tags": ["string"]
}

Campos customizados (customFields)

Para adicionar ou alterar apenas um campo mantendo os demais:

1. Busque o contato antes (pelo id ou pelo número de WhatsApp).
2. Verifique os campos atuais, inclua todos na requisição PATCH e altere apenas o valor desejado.

Você pode enviar somente o item customFields. Para zerar todos os valores:

"customFields": "{}"

Etiquetas (tags)

Diferente dos campos customizados, ao adicionar uma etiqueta as que já estavam vinculadas não são apagadas. Você pode enviar apenas o item tags:

{
  "tags": ["VIP", "Indicação"]
}

Para zerar as etiquetas, deixe o array vazio:

{
  "tags": []
}

Buscar contato pelo número de WhatsApp

Como buscar pelo id externamente é trabalhoso, há um recurso para buscar pelo número:

GET  https://<seu-ambiente>/v1/contacts/number/numero_whatsapp

API de Templates

Use esta API para encontrar os hsmId (ids dos templates da API oficial), necessários no disparo via API (Push) oficial. Na URL autenticada, adicione a palavra template entre external e o token:

https://<seu-ambiente>/v1/api/external/template/<token>

Abra o endereço no navegador ou em um cliente de API (como Postman ou Insomnia) e você receberá um JSON com um array de templates. Você também encontra essa informação em Configurações → API/Webhook → Documentação.

API de Usuários (atendentes)

Retorna todos os usuários do sistema e seus ids — importantes para forçar um ticket a abrir em um usuário específico (campo userId da API Push). Funciona como a API de Templates: no lugar de template na URL, use users.

https://<seu-ambiente>/v1/api/external/users/<token>

API de Etiquetas

Permite criar, buscar e deletar etiquetas das configurações. Em todos os métodos, o token vai no cabeçalho: "Authorization": "Bearer seu_token".

No GET, cada etiqueta retorna os parâmetros: id, tag, color, isActive, userId, tenantId, createdAt e updatedAt. Body do POST:

[
  { "tag": "Tag 1", "color": "#FF0000", "userId": null },
  { "tag": "Tag 2", "color": "#00FF00", "userId": null },
  { "tag": "Tag 3", "color": "#0000FF", "userId": null }
]

API da Pipeline

Disponível em Configurações → API/Webhook → Documentação. O processo é o mesmo da API de Etiquetas, mudando apenas os recursos no final da URL. Consulte a aba Documentação do seu ambiente para os endpoints e payloads atualizados.

Variáveis

O sistema tem quatro tipos de variáveis: nativas (implícitas e explícitas), customizadas e temporárias (de condições e de retorno de API). Toda variável é apresentada entre chaves duplas: {{variavel}}.

Nativas explícitas

Nativas implícitas

Customizadas e temporárias

As variáveis customizadas são criadas em Configurações → Campos Customizados. Se for usá-las apenas para armazenar informação, pode adicionar caracteres especiais; mas para usá-las como variável, siga o padrão: só letras minúsculas e _, sem caracteres especiais e sem espaços.

cpf_cliente

Exemplo de campo usável como variável e registro.

data_nascimento

Outro exemplo no padrão recomendado.

cep

Padrão correto: minúsculas, sem espaços.

As variáveis temporárias são criadas apenas no fluxo do chatbot (em condições e no retorno de API) e servem para apresentar um valor de forma instantânea, já que não ficam salvas no banco de dados.

Sistemas que você pode integrar

Os pontos de integração do AtendeSEG permitem vínculo com diversos sistemas. Abaixo, alguns exemplos por segmento — a lista não é exaustiva: dependendo da necessidade, uma integração personalizada pode ser construída.