Chat

O endpoint de Chat recebe uma mensagem pela caixa API, registra a conversa no SquadOS e, normalmente, executa o agente associado. A resposta pode voltar na mesma requisição ou ser enviada depois para um webhook.

Dica

Antes de chamar este endpoint, crie e ative a caixa API (webhook). O passo a passo está em API (Webhook); a autenticação está em Autenticação.

POST /chat/{id}

Use preferencialmente o ID da caixa API em {id}. Por compatibilidade, o endpoint também aceita o ID do agente que possui uma caixa API ativa.

curl -X POST https://api.squados.io/v1/chat/API_INBOX_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual é o horário de funcionamento?",
    "sync": true
  }'

O token e a caixa precisam pertencer à mesma organização. Uma caixa inativa, de outro canal ou de outra organização é rejeitada.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
message	string	Condicional	Texto da mensagem. Envie texto, pelo menos um attachment, ou ambos.
role	user | assistant	Não	Padrão: user. Com assistant, a mensagem é apenas registrada no histórico; o agente não é executado.
conversation_id	string (UUID)	Não	Continua uma conversa específica da organização. Tem precedência sobre external_user_id.
external_user_id	string	Não	Identificador estável do contato no seu sistema. Sem conversation_id, reutiliza a conversa mais recente desse identificador na organização.
user_name	string	Não	Nome do contato. Atualiza o nome da conversa e, quando há contato vinculado, o nome exibido em Conversas.
sync	boolean	Não	Com true, devolve a resposta do agente na mesma chamada. Com false e webhook_url, enfileira a execução assíncrona.
webhook_url	string (URL HTTP/HTTPS)	Não	Destino do callback assíncrono. Sem essa URL, a resposta é direta. Com sync: true, a resposta continua direta e nenhum callback é enviado.
attachments	array de Attachment	Condicional	Imagens, áudios ou arquivos. Pode substituir message em uma requisição somente com anexo.
metadata	object	Não	Dados livres de correlação. Também são devolvidos no callback assíncrono.
onlyStorage	boolean	Não	Com true, registra a mensagem sem executar o agente. É útil para sincronizar histórico externo.

Campos de Attachment

Campo	Tipo	Obrigatório	Descrição
name	string	Recomendado	Nome do arquivo. Quando omitido, o SquadOS usa attachment.
url	string	Sim	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	image | audio | file	Recomendado	Categoria do anexo. Se omitida ou inválida, o SquadOS tenta inferir pelo mimeType; video é tratado como file.
mimeType	string	Recomendado	Tipo MIME, como image/jpeg, audio/mpeg ou application/pdf.

O processamento efetivo depende das capacidades e configurações do agente. Por exemplo, áudio pode ser transcrito e um arquivo pode ter o texto extraído antes de chegar ao modelo.

Continuidade da conversa

O SquadOS resolve a conversa nesta ordem:

1. Se conversation_id foi enviado, continua essa conversa, desde que ela pertença à organização do token.
2. Sem conversation_id, se external_user_id foi enviado, procura a conversa mais recente desse identificador na organização.
3. Sem nenhum dos dois, cria uma nova conversa.

Se a conversa encontrada estiver arquivada, uma nova conversa é criada. Guarde sempre o conversation_id devolvido: ele é a forma mais precisa de continuar o atendimento. O external_user_id é útil quando seu sistema prefere manter apenas o identificador próprio do contato.

curl -X POST https://api.squados.io/v1/chat/API_INBOX_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Voltei. Qual é o status do meu pedido?",
    "sync": true,
    "external_user_id": "crm-cliente-123",
    "user_name": "Maria Silva"
  }'

Resposta direta

A resposta é direta quando não há webhook_url ou quando sync: true. Não existe um timeout fixo de 10 segundos no contrato do endpoint; configure no seu cliente um limite compatível com o tempo de execução do agente.

Resposta 200

{
  "success": true,
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "response": "Nossa loja funciona de segunda a sexta, das 9h às 18h.",
  "model": "provedor/modelo",
  "credits_used": 1,
  "attachments_processed": 0
}

model e credits_used refletem a execução real e variam conforme o agente, o provedor e o uso.

Cuidado

Uma repetição idêntica da mesma mensagem de usuário na mesma conversa, dentro da janela de deduplicação, pode retornar 200 com status: "duplicate_ignored", conversation_id, original_message_id e original_at, sem executar o agente outra vez. Não trate toda resposta 200 como se tivesse o campo response.

Resposta assíncrona por webhook

Envie webhook_url e não use sync: true. A API confirma o recebimento com 202; a confirmação inicial ainda não contém a resposta nem o message_id do assistente.

curl -X POST https://api.squados.io/v1/chat/API_INBOX_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analise o relatório anexado",
    "sync": false,
    "webhook_url": "https://integracao.exemplo.com/squados/callback",
    "metadata": { "ticket_id": "TKT-12345" }
  }'

Com sync: false, a execução passa pela fila assíncrona e a confirmação inclui o grupo:

{
  "status": "debounced",
  "group_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "conversation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Se sync for omitido, a confirmação assíncrona pode usar "status": "processing" e trazer apenas status e conversation_id.

Quando o processamento termina, o SquadOS faz POST na URL informada. O callback de sucesso usa event: "message.completed" e inclui success, agent_id, conversation_id, message_id, response, model, credits_used, attachments_processed, responding_agent_name, metadata e timestamp. Em uma transferência entre agentes, pode haver um callback anterior com pre_transfer: true. Consulte Webhooks para os payloads e cuidados de entrega.

Registrar uma mensagem sem executar o agente

Use role: "assistant" para registrar uma mensagem produzida fora do SquadOS, ou onlyStorage: true para persistir qualquer role sem executar o pipeline. Informe conversation_id quando quiser garantir que a mensagem entre em uma conversa existente; sem ele, valem as regras normais de resolução e uma conversa pode ser criada.

curl -X POST https://api.squados.io/v1/chat/API_INBOX_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Seu pedido foi processado.",
    "role": "assistant",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Resposta 200

{
  "success": true,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": null
}

Enviar somente um anexo

message pode ser omitido quando attachments contém ao menos um item:

{
  "sync": true,
  "attachments": [
    {
      "name": "contrato.pdf",
      "url": "https://arquivos.exemplo.com/contrato.pdf",
      "type": "file",
      "mimeType": "application/pdf"
    }
  ]
}

Erros mais comuns

HTTP	code	Quando acontece
400	invalid_request	JSON inválido, role inválida, tipo incorreto ou ausência simultânea de texto e anexos.
401	unauthorized	Token ausente, inválido, revogado ou fora da validade.
403	forbidden	A caixa não pertence à organização do token ou não é do canal API.
403	trigger_inactive	A caixa API está inativa ou o agente legado não possui uma caixa API ativa.
404	not_found	Rota ou conversation_id não encontrado na organização.

As respostas de erro seguem o formato { "error": "mensagem", "code": "codigo" }. Veja Erros para o contrato comum da API.