API (Webhook)

O canal API cria uma caixa de entrada com um endpoint REST. Use-o para fazer um CRM, n8n, Make, Zapier ou backend próprio enviar mensagens ao SquadOS. A caixa pode encaminhar a entrada a um agente de IA ou ao atendimento humano.

Este guia cobre a conexão e a operação do canal. Para o contrato completo de campos, respostas e erros, consulte Chat.

Antes de começar

Você precisa de Criar e editar caixas de entrada para criar, editar, ativar ou desativar a caixa. A integração também precisa de um token Bearer da mesma organização; a geração exige Criar e rotacionar tokens de API.

Cuidado

O token dá acesso à API pública da organização e não possui escopos por endpoint. Guarde-o somente no servidor ou no cofre de segredos da integração. Nunca o coloque em frontend, aplicativo móvel, repositório, log ou prompt.

Conectar a caixa

1. No Admin, abra Caixas de entrada e selecione Conectar caixa de entrada.

2. Em Outros canais, escolha API. Esse canal não pede credencial de provedor.

3. Em Quem atende esta caixa?, selecione Atendimento humano ou um agente ativo. Um agente inativo ainda pode aparecer no seletor, mas o runtime recusará a mensagem; confirme o estado do agente antes de concluir.

4. Preencha Nome da caixa e selecione Concluir. A caixa é criada ativa.

Para uma caixa já existente, abra o menu de ações da linha e escolha Editar. O bloco Conexão mostra o estado Conectado e, dentro de Informações, o endpoint copiável.

Endpoint e identificador

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

Copie o endpoint inteiro exibido em Informações. Na tela de Caixas de entrada, {id} é o ID da caixa API, apesar de a legenda atual dizer ID do agente. Use o ID da caixa: ele também funciona quando o destino é atendimento humano e mantém a origem correta da conversa.

Por compatibilidade, o endpoint aceita o ID de um agente que possua caixa API ativa. Essa alternativa não serve para caixa sem agente e pode ficar ambígua quando a operação é organizada por caixas.

Criar e usar o token

Abra o menu do avatar e siga Configurações → Desenvolvedores → API. Na aba Tokens, gere um token e copie o segredo quando ele aparecer; o valor completo não volta a ser exibido.

Envie-o em toda chamada:

Authorization: Bearer pk_seu_token_aqui
Content-Type: application/json

Veja criação, rotação, revogação e permissões em Autenticação.

Primeira chamada

Sem webhook_url, a resposta do agente volta na própria conexão HTTP. sync: true torna essa intenção explícita:

curl -X POST https://api.squados.io/v1/chat/ID_DA_CAIXA_API \
  -H "Authorization: Bearer pk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual é o horário de funcionamento?",
    "sync": true,
    "external_user_id": "crm-cliente-123",
    "user_name": "Maria Silva"
  }'

Uma execução normal responde 200 com success, conversation_id, message_id, response, model, credits_used e attachments_processed. O campo da resposta textual se chama response, não message. O endpoint não promete timeout fixo de dez segundos; configure o cliente para acomodar o tempo real do agente.

Guarde o conversation_id retornado para continuar exatamente o mesmo atendimento. Sem ele, external_user_id procura a conversa mais recente desse identificador na organização; portanto, não reutilize o mesmo identificador para pessoas diferentes.

Resposta assíncrona por callback

Envie webhook_url e não use sync: true quando a integração não deve manter a conexão aberta:

{
  "message": "Analise o relatório anexado",
  "webhook_url": "https://integracao.exemplo.com/squados/callback",
  "metadata": { "ticket_id": "TKT-12345" }
}

A confirmação inicial é 202 Accepted, com status: "processing" ou status: "debounced" e o conversation_id; ela ainda não contém a resposta do assistente. Ao terminar, o SquadOS faz POST no callback com event: "message.completed", a resposta e o metadata original.

Valide o callback de forma idempotente e aceite campos adicionais. A entrega atual tem prazo de dez segundos, uma única tentativa e nenhum header de assinatura próprio. Consulte payloads, transferências e cuidados em Webhooks.

Texto, anexos e armazenamento

Envie message, ao menos um item em attachments, ou ambos. Cada anexo usa url HTTP/HTTPS acessível pelo SquadOS ou uma URL de dados completa, como data:image/png;base64,...; base64 sem o prefixo data: não é aceito. type pode ser image, audio ou file, e o processamento efetivo depende do agente e do modelo.

Campos úteis adicionais:

• role: "assistant" registra uma mensagem externa sem executar o agente;
• onlyStorage: true armazena a entrada sem executar o pipeline;
• metadata preserva dados livres de correlação e volta no callback;
• conversation_id, external_user_id e user_name controlam continuidade e identidade do contato.

Veja schemas e exemplos de anexo em Chat.

Desativar e diagnosticar

Em Caixas de entrada → Ações → Editar → Conexão, use Desconectar para desativar a caixa. Chamadas por seu ID passam a retornar 403 trigger_inactive. Para voltar a aceitar chamadas, abra o mesmo bloco e selecione Ativar.

O badge Canal próprio da lista não confirma que a API está ativa; confira o estado dentro de Conexão. O botão Histórico de Webhooks também não está disponível no fluxo atual de Caixas de entrada. Registre status, corpo e identificadores no seu próprio sistema e consulte Erros ao investigar uma falha.

Excluir é diferente de desativar: a exclusão remove a caixa e sua configuração. Prefira desativar quando a interrupção for temporária.