Integrador SQUAD — API da IA de atendimento

Onde fica: Integrador SQUAD › Integrações · API na raiz do servidor do SQUAD

O SQUAD é o "cérebro" de IA que atende pelo OMNI. O OMNI entrega a conversa; o SQUAD pensa, usa ferramentas (consultar fatura, enviar boleto, ver o roteador…) e devolve a resposta pronta para o OMNI entregar ao cliente. O contrato entre os dois é pequeno e estável: um pareamento de uma vez e três rotas de uso.

Antes de começar

• O SQUAD atende por empresa. Cada empresa tem uma integração própria, identificada pelo empresa_id.
• O OMNI e o SQUAD precisam estar pareados (veja abaixo). Sem isso, qualquer chamada responde 401.
• Para o SQUAD agir no OMNI (enviar boleto, transferir para um setor), o servidor do SQUAD também precisa da credencial de serviço do OMNI. Sem ela, a IA atende "às cegas" e a tela de Integrações avisa.

Autenticação e pareamento

O pareamento usa dois tokens:

Token	Gerado por	Usado por	Para quê
T1	SQUAD (por empresa)	OMNI → SQUAD	Authorization: Bearer <T1> em todas as chamadas do OMNI ao SQUAD.
Credencial de serviço (nxa_…)	OMNI	SQUAD → OMNI	Configurada no servidor do SQUAD. É com ela que o SQUAD executa ferramentas e consulta conversas no OMNI.

No pareamento, o OMNI também envia ao SQUAD o próprio endereço e um token, que o SQUAD guarda cifrado.

Passo a passo do pareamento

1. No SQUAD, em Integrações, clique para gerar o token T1. Ele pode ser visto e copiado de novo depois por quem gerou.
2. No OMNI, cole o T1 na integração do SQUAD.
3. O OMNI chama POST /v1/handshake com o T1, enviando o próprio endereço e o seu token. O SQUAD guarda o token cifrado e marca a integração como pareada.

Atenção

Gerar um novo T1 desfaz o pareamento: o OMNI precisa colar o novo token e refazer o handshake.

Recursos

Método e rota	Autenticação	Para quê
POST /v1/handshake	Bearer T1	Pareamento. Corpo: omni_url, omni_token. Devolve ok, squad_url e uma mensagem.
POST /v1/decide	Bearer T1	Decide um atendimento. O OMNI manda a conversa; o SQUAD devolve a resposta.
POST /v1/texto	Bearer T1	Gera um texto avulso (traduzir e-mail, redigir resposta, resumir), sem conversa nem ferramentas.
POST /v1/retrato	Bearer T1	Gera o retrato de um tripulante do OMNI GAME a partir de uma foto.
GET /v1/retrato/modelo	—	Qual modelo de imagem está de plantão e que quadros o SQUAD sabe desenhar.

POST /v1/decide

Campos principais da chamada:

• empresa_id (obrigatório) e conversation_ref (obrigatório) — a conversa no OMNI;
• messages: o histórico, cada item com role (user ou assistant) e content;
• ixc_cliente_id ou contact_ref — a identidade do cliente (vem do OMNI, nunca da IA);
• departamento — define para qual equipe o SQUAD roteia (financeiro, técnico, comercial, suporte ou triagem);
• channel, cliente_nome, contato, protocolo — contexto opcional;
• motivo — chamadas especiais: nudge (cutucada de acompanhamento; com nudge_final para a última), abandono_check (o cliente sumiu: encerrar ou escalar?), resolucao_check (auditoria interna), instrucao (um supervisor orienta a IA), licao e licao_aprovada (aprender com o atendimento). Sem motivo, é o atendimento normal.

Campos principais da resposta:

• reply_text — a resposta pronta para o cliente;
• confidence — de 0 a 1;
• needs_human e needs_human_reason — a IA pediu um humano;
• used_tools — as ferramentas usadas, anexos — PDFs/QR a enviar (boleto, PIX);
• entregar — se for false, o OMNI não envia nada ao cliente (turnos internos);
• proposta_encerramento — o assunto foi resolvido; o OMNI arma um tempo e, se o cliente não responder, encerra e dispara a pesquisa de satisfação;
• encerrar_abandono — encerrar sem pesquisa;
• run_id, cost_usd — rastreio e custo da rodada.

Chamadas repetidas de abandono_check para a mesma conversa em até 6 horas recebem a decisão anterior, sem nova rodada de IA. O SQUAD limita a 60 chamadas por minuto por empresa (429) e respeita um teto diário de custo (acima dele, devolve needs_human para o OMNI escalar).

POST /v1/texto

Corpo: empresa_id, system (a instrução do papel, até 4.000 caracteres), mensagem (até 20.000), max_tokens (padrão 800, teto 2.000) e tarefa (rótulo para log). Resposta: texto, modelo, provider, custo_usd, tokens_in, tokens_out. O pedido e a resposta não são gravados; só o custo.

Ferramentas do SQUAD

O SQUAD age no mundo do provedor por ferramentas. Elas são executadas pelo OMNI (que as protege com as regras de privacidade: só o cliente identificado na conversa), a pedido do SQUAD. Cada equipe tem as suas:

Equipe	Ferramentas
Financeiro	identificar e consultar cliente, faturas e vencimentos, boleto (2ª via), PIX copia e cola, nota fiscal, renegociar débito, desbloqueio de confiança, liberar velocidade, transferir para humano
Suporte técnico	identificar e consultar cliente, listar contratos, diagnóstico e status da conexão, consultar sinal, status de O.S., consultar equipamento, diagnóstico e status do roteador, histórico de uso do Wi-Fi, teste de velocidade (download e upload), reiniciar roteador, canal automático e otimização de canal, analisar espectro, separar redes Wi-Fi, consultar e trocar senha do Wi-Fi, verificar manutenção, faturas e boleto
Comercial	identificar e consultar cliente, listar contratos, consultar assinatura pendente, listar planos, enviar o cartão do plano, consultar viabilidade, registrar negociação
Em todas	transferir para setor ou humano, lembrar do cliente, pesquisar na web, buscar conhecimento, propor encerramento

Algumas dessas ferramentas chegam ao Integrador ISP (ISP) e ao ACS (ACS) por trás do OMNI. As ferramentas sensíveis (como desbloqueio e renegociação) seguem as regras e os limites configurados por empresa.

Exemplos

Pedir uma decisão de atendimento

curl -s -X POST https://squad.exemplo.com.br/v1/decide \
  -H "Authorization: Bearer t1-de-exemplo" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id": 1, "conversation_ref": "conversa-123",
       "ixc_cliente_id": "3749", "departamento": "financeiro",
       "messages": [{"role": "user", "content": "Preciso da segunda via do boleto"}]}'

{"mode": "ativo", "reply_text": "Claro! Já te envio o boleto.", "confidence": 0.9,
 "needs_human": false, "used_tools": [{"name": "boleto_segunda_via"}],
 "run_id": 5001, "cost_usd": 0.004, "entregar": true,
 "proposta_encerramento": false, "encerrar_abandono": false}

Gerar um texto avulso

curl -s -X POST https://squad.exemplo.com.br/v1/texto \
  -H "Authorization: Bearer t1-de-exemplo" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id": 1, "system": "Você traduz e-mails de suporte para português.",
       "mensagem": "Hello, my internet has been down since this morning.",
       "max_tokens": 400, "tarefa": "traduzir_email"}'

Erros comuns

Código	Quando
401	T1 ausente, inválido ou integração não configurada para a empresa.
409	(/v1/texto) empresa sem nenhum squad cadastrado.
422	Corpo inválido ou acima dos limites.
429	Mais de 60 chamadas por minuto para a empresa.
502	O provedor de IA respondeu com erro ou demorou demais.
503	Nenhum squad ativo para a empresa, ou nenhum provedor de IA utilizável.

Leia também

• Integrações — visão geral
• Integrador OMNI