Entrada por API (outro sistema inicia)
Rotas de API — outro sistema iniciando o atendimento
Serve para um sistema externo (uma URA, um portal do cidadão, um app, um outro bot) iniciar e dirigir um atendimento no seu fluxo — começando no ponto exato que você quiser, já com os dados em mãos.
Exemplo: o cidadão ligou na central de atendimento, escolheu "2ª via" no menu de voz e pediu para continuar no WhatsApp. A central chama a nossa API dizendo "abre o atendimento de 2ª via para este telefone, com este CPF e este protocolo". Quando o cidadão manda a primeira mensagem no WhatsApp, o bot já começa na 2ª via, sem repetir menu.
Como funciona (visão geral)
- No fluxo, você adiciona o bloco Início por API no ponto onde a conversa deve começar e dá um endereço (slug) a ele.
- Ao publicar, esse bloco vira uma rota — uma URL que o sistema externo chama.
- Em Administração › Integrações › Entrada por API você gera uma chave e copia o contrato para entregar a quem vai integrar.
- O sistema externo chama a rota (start). O atendimento fica armado.
- O cidadão manda a primeira mensagem no canal → o bot abre no bloco da rota, com as variáveis já preenchidas.
Uma slug por tema
Sim. Cada bloco "Início por API" tem sua própria slug — então você abre quantas rotas quiser, uma para cada assunto, apontando para partes diferentes do fluxo:
Endereço | Começa em | Recebe |
|---|---|---|
POST /api/flow/segunda-via/sessions | ramo da 2ª via | cpf |
POST /api/flow/agendamento/sessions | ramo de agendamento | cpf, data |
POST /api/flow/divida/sessions | ramo de negociação | cpf, protocolo |
É assim que "acionar o fluxo em qualquer lugar" acontece: o ponto de entrada é o bloco onde você colocou o Início por API. Arraste-o para onde quiser, ligue no ramo certo, dê a slug — pronto.
Campos que você recebe
No bloco você define as variáveis obrigatórias (ex.: cpf, protocolo). A chamada precisa enviá-las; sem elas a API recusa (não abre atendimento sem os dados). Elas ficam disponíveis no fluxo como {{cpf}}, {{protocolo}}, etc. telefone e protocolo da chamada entram automaticamente no contexto.
Autenticação
Toda chamada leva:
- X-Api-Key — a chave gerada em Rotas de API (identifica o seu workspace).
- X-Signature — HMAC-SHA256 do corpo (bytes) usando o segredo da chave, em hexadecimal. Obrigatório em POST, PATCH e DELETE.
Os endereços (verbos)
Iniciar — POST /api/flow/{slug}/sessions
Corpo:
{
"telefone": "+5561999990000",
"protocolo": "PROTO-123",
"modo": "armar",
"variaveis": { "cpf": "12345678909" }
}- telefone — obrigatório, formato internacional (E.164).
- protocolo — opcional; serve de idempotência (repetir a mesma chamada não abre duas conversas, devolve a existente).
- modo — armar (padrão: o cidadão fala primeiro) ou proativo (o bot fala primeiro — requer template aprovado, em breve).
- variaveis — as obrigatórias da rota + quaisquer outras livres.
Resposta 202:
{ "session_id": "…", "estado": "armada", "protocolo": "PROTO-123", "telefone": "+5561999990000" }Consultar — GET /api/flow/sessions/{session_id}
Devolve o estado (armada → ativa → encerrada), o conversa_id quando o atendimento abre, e as variáveis. Precisa só de X-Api-Key.
Atualizar — PATCH /api/flow/sessions/{session_id}
Injeta/atualiza variáveis do atendimento (mescla com as existentes).
{ "variaveis": { "status_pagamento": "confirmado" } }Encerrar — DELETE /api/flow/sessions/{session_id}
Marca a sessão como encerrada.
Exemplo de ponta a ponta (curl)
# 1) o sistema externo inicia o atendimento de "2ª via" para o telefone
curl -X POST 'https://SEU-DOMINIO/api/flow/segunda-via/sessions' \
-H 'X-Api-Key: ak_xxx' \
-H 'X-Signature: <HMAC_SHA256_do_corpo_com_o_segredo>' \
-H 'Content-Type: application/json' \
-d '{"telefone":"+5561999990000","protocolo":"P-777","variaveis":{"cpf":"12345678909"}}'
# -> 202 { "session_id": "abc", "estado": "armada" }
# 2) (opcional) consulta depois
curl 'https://SEU-DOMINIO/api/flow/sessions/abc' -H 'X-Api-Key: ak_xxx'O cidadão manda a primeira mensagem no WhatsApp e o bot abre na 2ª via, com {{cpf}} e {{protocolo}} prontos.
Onde isto fica
Administração › Integrações, na seção Entrada por API — no fim da página, depois das conexões. Os dois assuntos moram juntos de propósito: em cima, a plataforma chamando um sistema de fora; embaixo, um sistema de fora chamando a plataforma. É a mesma pergunta ("o que está conectado?") pelos dois lados.

Chaves de entrada
Cada chave identifica quem está chamando. No chaveiro você pode:
Ação | O que acontece |
|---|---|
Gerar chave | cria o par chave + segredo |
Copiar o segredo | o segredo aparece uma única vez, na hora da criação |
Revogar | a chave para de ser aceita na hora |
Reativar | volta a valer, sem precisar gerar outra |
Esconder as revogadas | tira do caminho o que já não vale, sem apagar o histórico |
Rotas publicadas — e o contrato
Cada bloco "Início por API" de um fluxo publicado abre uma rota. Cada rota tem o documento pronto — método, endereço, cabeçalhos, corpo esperado e um curl de exemplo — para você copiar e entregar ao integrador, sem escrever nada à mão. Ver o contrato completo abre tudo; os botões de copiar pegam o endereço, o caminho ou o exemplo inteiro.
Relatório de disparos de uma campanha
Outro sistema consulta o que cada disparo de uma campanha deu, com a mesma chave de entrada. São os mesmos campos do Exportar da aba Disparos.
GET /api/disparos/public/campaigns/{campanha_id}/dispatches
Parâmetro | O que faz |
|---|---|
page | página, a partir de 1 |
limit | linhas por página, de 1 a 5000 (padrão 500) |
status | só os disparos nessa situação: sent, delivered, read, failed… |
day | só os disparos criados nesse dia (AAAA-MM-DD, horário de Brasília) |
curl -s "https://SEU-ENDERECO/api/disparos/public/campaigns/ID-DA-CAMPANHA/dispatches?limit=5000&page=1" \
-H "X-Api-Key: SUA-CHAVE"{"items": [{"Campanha": "Aviso de corte", "Canal": "WhatsApp", "DataDisparo": "12/11/2026", "HoraDisparo": "17:42:18",
"NomeCliente": "ACME LTDA", "Telefone": "5561999990001", "Situacao": "Erro", "SituacaoEnvio": "Destinatário sem WhatsApp",
"CodigoErro": "131026", "DescricaoErro": "Message undeliverable, (#131026) Message Undeliverable. (Gupshup 131026)",
"CPC": "N/A", "RespostaUsuario": "Não", "DataResposta": "", "HoraResposta": "", "UltimaResposta": ""}],
"total": 29357, "page": 1, "limit": 5000}A chave vai em X-Api-Key ou Authorization: Bearer. A chave criada junto com uma campanha Via API lê só a campanha dela; as demais leem qualquer campanha do workspace.
Campo | Valores |
|---|---|
Situacao | Concluido (saiu da plataforma), Erro, Em processamento (ainda na fila) |
SituacaoEnvio | Envio confirmado, Aguardando envio ou o motivo da falha em uma frase |
CodigoErro | o código do fornecedor ou da plataforma; N/A quando não houve erro |
CPC | Sim, Não ou N/A (a campanha não confirma a pessoa certa) |
RespostaUsuario | Sim ou Não; data, hora e texto são da última resposta |
UltimaResposta | o texto da última resposta em uma linha, até 30 caracteres |
Respostas de erro: 401 sem chave ou chave inválida, 403 chave de outra campanha, 404 campanha inexistente, 422 limit fora de 1 a 5000, 429 acima do teto de consultas por minuto da mesma chave (60, por padrão).
Indicadores de atendimento
Outro sistema consulta os números dos painéis de fila e de agentes de um dia ou de um período, com a mesma chave de entrada.
GET /api/atendimento/public/indicators
Parâmetro | O que faz |
|---|---|
day | um dia só (AAAA-MM-DD, horário de Brasília) |
start e end | um período, os dois juntos; no máximo 366 dias |
assistant | só os atendimentos desse assistente (o id dele) |
Use day ou start e end. A chave vai em X-Api-Key ou Authorization: Bearer.
curl -s "https://SEU-ENDERECO/api/atendimento/public/indicators?day=2026-11-12" \
-H "X-Api-Key: SUA-CHAVE"{"periodo": {"inicio": "2026-11-12", "fim": "2026-11-12"}, "assistente": null,
"totais": {"atendimentos_total": 7, "somente_bot": 1, "resolvidos_pela_ia": 0, "somente_humano": 1,
"taxa_derivacao_humano": 0.5714, "atendimentos_encerrados": 7, "bot_para_atendente": 3, "desistencias": 2,
"taxa_desistencia": 0.2857, "escalados_pela_ia": 1, "espera_media_seg": 120.0, "espera_ate_desistir_seg": 900.0,
"tempo_medio_atendimento_seg": 480.0, "csat_media": null, "csat_respostas": 0, "atendentes_ativos": 1,
"tempo_disponivel_seg": 10800.0, "tempo_em_pausa_seg": 3600.0, "pausas": 1, "pausas_acima_do_previsto": 0},
"por_dia": [{"dia": "2026-11-12", "atendimentos_encerrados": 7, "bot_para_atendente": 3}],
"por_canal": [{"canal": "widget", "atendimentos_encerrados": 6, "bot_para_atendente": 3}],
"por_fila": [{"fila": "suporte", "atendimentos_encerrados": 6, "bot_para_atendente": 3}],
"por_hora": [{"hora": "14h", "atendimentos_encerrados": 7, "bot_para_atendente": 3}],
"por_atendente": [{"atendente": "[email protected]", "atendimentos_encerrados": 3, "pausas": 1}],
"por_motivo": [{"motivo": "agente", "quantidade": 4}],
"pausas_por_tipo": [{"pausa": "Almoço", "pausas": 1, "tempo_seg": 3600.0}]}Cada item de por_dia e por_canal traz os mesmos campos de totais; o exemplo mostra só alguns. por_fila não traz os campos de quem atendeu: conversa que ficou no bot não tem fila. Dia, canal ou fila sem movimento no período não aparece.
Campo | O que é |
|---|---|
atendimentos_total | todos os atendimentos encerrados no período: só bot, IA e com atendente |
somente_bot | terminaram no bot, sem ir para fila |
resolvidos_pela_ia | a IA resolveu sem passar para um atendente |
somente_humano | chegaram ao atendente sem passar por bot (e-mail) |
taxa_derivacao_humano | % Derivação para Humano: do total, a fatia que um atendente atendeu (bot_para_atendente + somente_humano), de 0 a 1 |
atendimentos_encerrados | atendimentos humanos encerrados no período, com as desistências |
bot_para_atendente | saíram da IA ou do menu para uma fila e um atendente assumiu |
desistencias, taxa_desistencia | entraram na fila e saíram antes de alguém assumir; a taxa vai de 0 a 1 |
escalados_pela_ia | atendimentos que a IA passou para um atendente |
espera_media_seg | média de espera na fila de quem foi atendido, em segundos |
espera_ate_desistir_seg | média de espera de quem desistiu, em segundos |
tempo_medio_atendimento_seg | duração média do atendimento humano, em segundos |
csat_media, csat_respostas | nota média e quantidade de avaliações |
atendentes_ativos | pessoas que ficaram disponíveis em algum momento |
tempo_disponivel_seg, tempo_em_pausa_seg | soma do tempo disponível e do tempo em pausa |
pausas, pausas_acima_do_previsto | pausas iniciadas e as que passaram do tempo cadastrado |
Média sem dado no período vem null; contagem vem 0. Com assistant, os campos de jornada do atendente (atendentes_ativos, tempos e pausas) e pausas_por_tipo não vêm: a pausa é da pessoa, não do assistente.
Respostas de erro: 401 sem chave ou chave inválida, 404 assistente inexistente, 422 período ausente, invertido, acima de 366 dias ou day junto com start/end, 429 acima do teto de consultas por minuto da mesma chave (30, por padrão).
Detalhe dos atendimentos
Atendimento a atendimento do período, com os marcos de cada um, para o outro sistema montar os próprios índices. Entram os que ficaram só no bot, os que a IA resolveu e os que foram para um atendente.
GET /api/atendimento/public/conversations
Parâmetro | O que faz |
|---|---|
day | um dia só (AAAA-MM-DD, horário de Brasília) |
start e end | um período, os dois juntos; no máximo 366 dias |
assistant | só os atendimentos desse assistente (o id dele) |
page | página, a partir de 1 |
limit | linhas por página, de 1 a 5000 (padrão 500) |
O dia é o do encerramento. A lista sai do atendimento mais antigo para o mais novo.
curl -s "https://SEU-ENDERECO/api/atendimento/public/conversations?day=2026-11-12&limit=5000&page=1" \
-H "X-Api-Key: SUA-CHAVE"{"items": [{"Id_Conversa": "0b9f6c1e-3d2a-4a57-9c0e-5f1f6f1f7a10", "Protocolo": "2026-000777",
"Inicio_Bot": "2026-11-12T09:22:28-03:00", "Final_Bot": "2026-11-12T09:24:28-03:00",
"Entrada_Fila": "2026-11-12T09:24:28-03:00", "Inicio_Hmn": "2026-11-12T09:25:28-03:00",
"Final_Hmn": "2026-11-12T09:32:28-03:00", "Canal_Atend": "gupshup", "Servico": "Central 156",
"Nome_Cliente": "Maria da Silva", "Fone_Cliente": "5561999990001", "Situacao": "Concluído",
"Tmp_Atend_Bot": 120, "Tmp_Fila_Hmn": 60, "Tmp_Atend_Hmn": 420, "Finalizacao": "Agente",
"Motivo": "agente", "Tempo_Total": 600, "Operador": "[email protected]", "Grupo_Resp": "suporte"}],
"total": 5231, "page": 1, "limit": 5000}Campo | O que é |
|---|---|
Id_Conversa, Protocolo | identificador do atendimento e o protocolo, quando houve |
Inicio_Bot, Final_Bot | primeira mensagem do atendimento e o momento em que saiu do bot (foi para a fila ou terminou) |
Entrada_Fila, Inicio_Hmn, Final_Hmn | entrou na fila, o atendente assumiu, o atendimento terminou; vazios quando não houve |
Canal_Atend, Servico | canal e nome do assistente |
Nome_Cliente, Fone_Cliente | nome do contato e o identificador dele no canal (o telefone, no WhatsApp) |
Tmp_Atend_Bot, Tmp_Fila_Hmn, Tmp_Atend_Hmn, Tempo_Total | tempo no bot, na fila, com o atendente e do início ao fim, em segundos |
Finalizacao | Bot, IA, Agente ou Sem atendente (entrou na fila e saiu antes de alguém assumir) |
Motivo | como terminou: agente, inatividade, fim_fluxo, a tabulação escolhida pelo atendente… |
Operador, Grupo_Resp | login do atendente (AutoAtendimento no bot e na IA) e a fila |
Datas em ISO 8601, no horário de Brasília. Situacao é sempre Concluído: a lista traz só atendimento encerrado.
Respostas de erro: 401 sem chave ou chave inválida, 404 assistente inexistente, 422 período ausente, invertido, acima de 366 dias, day junto com start/end ou limit fora de 1 a 5000, 429 acima do teto de consultas por minuto da mesma chave (60, por padrão).