API (Webhook)

O canal API expõe um endpoint REST para sistemas externos enviarem mensagens — n8n, Make, Zapier, CRM, backend próprio, qualquer coisa que faça HTTP POST. A resposta pode ser síncrona (o agente responde na mesma chamada) ou assíncrona (a resposta volta num webhook que você informa).

Conectando o canal

O canal API é uma caixa de entrada, como qualquer outro canal.

1. Abra Caixas de Entrada no menu lateral do painel.
2. Clique em Conectar caixa de entrada.
3. Em Outros canais, escolha API.
4. Escolha quem atende: um agente da organização, ou o atendimento humano.
5. Dê um nome à caixa e clique em Concluir.

Não há credencial a configurar: o canal API nasce conectado.

Para ver o endereço, abra Ações → Configurações na linha da caixa e clique em Informações:

Para tirar do ar, use Desconectar na mesma tela — as chamadas param de ser aceitas imediatamente.

Endpoint

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

O {id} é o identificador que aparece em Informações. Ele aceita tanto o id da caixa quanto o id do agente — mas, numa caixa de atendimento humano, só o id da caixa funciona (não há agente a citar). Quando em dúvida, use o valor que a tela mostra.

A documentação interativa completa (schemas, exemplos e teste in-loco) está em Ver documentação completa da API, no mesmo painel.

Autenticação

Header Authorization com Bearer token:

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

O token é gerado por organização. Gere e gerencie tokens em Configurações → API (menu do seu avatar, no topo direito).

Payload

Campos principais:

• message (string, obrigatório) — texto da mensagem.
• sync (boolean, opcional) — true para resposta síncrona (timeout de 10s). Padrão: assíncrono.
• webhook_url (string, opcional) — URL que recebe a resposta quando o modo for assíncrono. 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 arbitrários 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 conversa nova é criada.

Exemplo: chamada síncrona com curl

curl -X POST https://api.squados.io/v1/chat/ID_DA_CAIXA \
  -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 assíncrona com webhook

curl -X POST https://api.squados.io/v1/chat/ID_DA_CAIXA \
  -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": "[email protected]"
    }
  }'

A API responde 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: vídeo em qualquer formato. Áudio só pelos canais de chat dedicados (use Telegram ou WhatsApp).

Histórico de chamadas

O painel Informações do canal dá acesso ao histórico das últimas chamadas recebidas: status, payload e horário. Ú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 Página pública e Widget, WhatsApp Oficial ou Telegram.