API (Webhook)

O gatilho API expoe um endpoint REST para sistemas externos enviarem mensagens ao seu agente — n8n, Make, Zapier, CRM, backend próprio, qualquer coisa que faca HTTP POST. A resposta pode ser sincrona (o agente responde na mesma chamada) ou assincrona (a resposta volta em um webhook que você informa).

Ativando o canal

1. Abra o agente no painel admin.
2. Vá para Gatilhos.
3. No card API, clique em Conectar.

Quando ativo, o card mostra:

• o Endpoint do agente (botão de copiar);
• Ver documentação completa da API (abre a referência Swagger);
• Histórico de webhooks (logs das últimas chamadas).

Para desativar, clique em Desconectar — a URL fica fora do ar imediatamente.

Endpoint

POST https://api.squados.io/v1/chat/{agentId}

O {agentId} já vem preenchido no card quando você conecta. A documentação interativa completa (com schemas, exemplos e teste in-loco) está na página Documentação da API acessível pelo próprio card.

Autenticação

Header Authorization com Bearer token:

Authorization: Bearer <SEU_TOKEN>
Content-Type: application/json

O token e gerado por organização. Gere e gerencie tokens no painel admin, em Configurações -> API.

Payload

Campos principais:

• message (string, obrigatorio) — texto da mensagem.
• sync (boolean, opcional) — true para resposta sincrona (timeout 10s). Padrão: assincrono.
• webhook_url (string, opcional) — URL que recebe a resposta quando o modo for assincrono. Você recebe um POST com o resultado.
• attachments (array, opcional) — anexos como { name, url, type, mimeType }. type: image, audio ou file. Aceita URL pública ou base64.
• metadata (object, opcional) — dados arbitrarios que voltam no webhook. Útil para correlacionar com ticket de CRM, lead, pedido, etc.
• conversation_id (string, opcional) — para continuar uma conversa existente. Sem ele, uma nova conversa e criada.

Exemplo: chamada sincrona com curl

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual e o horario de funcionamento?",
    "sync": true
  }'

Resposta (resumo):

{
  "conversation_id": "uuid",
  "message": "Funcionamos de segunda a sexta, das 9h as 18h.",
  "credits_used": 12
}

Exemplo: chamada assincrona com webhook

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analise este relatorio de vendas do Q4",
    "webhook_url": "https://hooks.n8n.cloud/webhook/abc123",
    "metadata": {
      "crm_ticket_id": "TKT-12345",
      "customer_email": "cliente@empresa.com"
    }
  }'

A API retorna 202 Accepted imediatamente. Quando o agente termina, você recebe um POST em webhook_url com o resultado e o metadata original — use para casar a resposta com seu registro de origem.

Anexos

Formatos aceitos:

• Imagens: JPEG, PNG, WebP, GIF.
• Documentos: PDF, TXT, MD, CSV, DOC, DOCX, XLS, XLSX.

Não aceitos: video em qualquer formato. Audio so via canais de chat dedicados (use Telegram ou WhatsApp para audio).

Histórico de chamadas

O botão Histórico de webhooks abre um log com as últimas chamadas recebidas: status, payload, timestamp. Útil para depurar integrações.

Quando usar

• Você já tem um CRM/backend/n8n e quer chamar o agente como mais uma API.
• Precisa correlacionar respostas com IDs externos (ticket, lead, pedido) usando metadata.
• Quer integrar o agente em um fluxo automatizado que não envolve usuário final em chat.

Para tudo mais (atendimento humano, link público, app de mensagem), prefira URL Pública e Widget, WhatsApp Oficial ou Telegram.