Chat

O endpoint de chat envia uma mensagem a um agente e retorna (ou entrega via webhook) a resposta gerada. A resposta pode ser síncrona — você aguarda na mesma chamada — ou assíncrona — o SquadOS dispara um POST na sua URL assim que o agente terminar de processar.

`POST /chat/{agentId}`

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`agentId`	string (UUID)	ID do agente que receberá a mensagem.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`message`	string	Sim	Conteúdo da mensagem.
`role`	string (`user` \| `assistant`)	Não	Role da mensagem. Padrão: `user`. Use `assistant` para sincronizar histórico (ver exemplo abaixo).
`sync`	boolean	Não	Se `true`, aguarda a resposta do agente na mesma chamada (timeout de 10 s). Padrão: `false`.
`conversation_id`	string (UUID)	Não	ID de uma conversa existente. Omita para criar uma nova.
`external_user_id`	string	Não	ID de usuário externo (ex.: ID no seu CRM). O SquadOS retoma a última conversa desse usuário com o agente automaticamente.
`user_name`	string	Não	Nome de exibição do lead/usuário final desta conversa. Faz a conversa aparecer nomeada na lista de Conversas (em vez de “Contato Externo”) e a torna pesquisável pelo nome. É persistido na conversa e atualizado a cada chamada que o informe. Mapeie aqui o campo de nome da sua integração.
`webhook_url`	string (URI)	Não	URL que receberá a resposta via `POST` quando o processamento terminar. Incompatível com `sync: true`.
`attachments`	array de `Attachment`	Não	Arquivos ou imagens anexados à mensagem. Ver tabela de campos abaixo.
`metadata`	object	Não	Dados livres para correlação. São ecoados de volta no payload do webhook sem modificação.

Campos de Attachment

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do arquivo (ex.: `contrato-2024.pdf`).
`url`	string (URI)	Sim	URL pública do arquivo ou string base64.
`type`	string (`image` \| `audio` \| `file`)	Sim	Tipo do anexo.
`mimeType`	string	Não	MIME type (ex.: `image/jpeg`, `application/pdf`).

Modos de resposta

Síncrono (sync: true) Passe "sync": true no corpo. O SquadOS aguarda o agente responder e retorna 200 com a resposta completa. O timeout é de 10 segundos — se o agente demorar mais, a API retorna 408 (ver Erros).

Assíncrono (webhook_url) Passe uma webhook_url válida. A API retorna 202 imediatamente com o conversation_id e message_id. Quando o agente terminar, o SquadOS faz POST na sua URL com o payload completo. Veja Webhooks para o formato do payload e como validar a assinatura.

a) Requisição síncrona simples

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

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, e aos sábados das 9h às 13h.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.003,
  "attachments_processed": 0
}

b) Requisição assíncrona com webhook e metadata

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

Resposta 202

{
  "success": true,
  "conversation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "message_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "status": "processing"
}

Quando o agente terminar, o SquadOS enviará POST para https://hooks.n8n.cloud/webhook/abc123 com a resposta completa e o objeto metadata ecoado. Veja Webhooks.

c) Anexo de imagem (síncrono)

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "O que você vê nesta imagem?",
    "sync": true,
    "attachments": [
      {
        "name": "produto-foto.jpg",
        "url": "https://example.com/images/produto-foto.jpg",
        "type": "image",
        "mimeType": "image/jpeg"
      }
    ]
  }'

Resposta 200

{
  "success": true,
  "conversation_id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
  "message_id": "f6a7b8c9-d0e1-2345-f012-456789012345",
  "response": "A imagem mostra um produto embalado em caixa branca com logotipo azul. O produto parece ser um eletrônico de pequeno porte.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.008,
  "attachments_processed": 1
}

d) Anexo de arquivo PDF (síncrono)

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Resuma o conteúdo deste contrato",
    "sync": true,
    "attachments": [
      {
        "name": "contrato-2024.pdf",
        "url": "https://example.com/docs/contrato-2024.pdf",
        "type": "file",
        "mimeType": "application/pdf"
      }
    ]
  }'

Resposta 200

{
  "success": true,
  "conversation_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
  "message_id": "b8c9d0e1-f2a3-4567-1234-678901234567",
  "response": "O contrato é um acordo de prestação de serviços entre as partes X e Y, com vigência de 12 meses a partir de janeiro de 2024. As principais cláusulas cobrem escopo de serviço, valores, confidencialidade e rescisão.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.015,
  "attachments_processed": 1
}

e) Mensagem outbound do assistente (sincronizar histórico)

Use "role": "assistant" para registrar uma mensagem enviada pelo assistente fora do fluxo normal — por exemplo, uma notificação proativa que você gerou no seu sistema. Isso mantém o histórico da conversa consistente no SquadOS. É necessário informar conversation_id.

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

Resposta 202

{
  "success": true,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "c9d0e1f2-a3b4-5678-2345-789012345678",
  "status": "processing"
}

f) Continuação automática por external_user_id

Use external_user_id para retomar automaticamente a última conversa de um usuário com o agente. Você não precisa armazenar conversation_id no seu sistema — o SquadOS localiza a conversa pelo ID externo.

Combine com user_name para que a conversa apareça nomeada (e pesquisável) na lista de Conversas, em vez de “Contato Externo”.

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

Resposta 200

{
  "success": true,
  "conversation_id": "d0e1f2a3-b4c5-6789-3456-890123456789",
  "message_id": "e1f2a3b4-c5d6-7890-4567-901234567890",
  "response": "Bem-vindo de volta! Seu pedido #98765 foi aprovado e está em separação. A previsão de envio é amanhã.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.004,
  "attachments_processed": 0
}

Erros

Código	Situação
`404`	Agente não encontrado ou sem canal API ativo.
`408`	Timeout no modo síncrono — o agente não respondeu em 10 s. O `conversation_id` e `message_id` são retornados para que você consulte a resposta depois via Conversas.

Exemplo de resposta 408

{
  "success": false,
  "error": "Agent response timed out. The conversation is still processing.",
  "conversation_id": "f2a3b4c5-d6e7-8901-5678-012345678901",
  "message_id": "a3b4c5d6-e7f8-9012-6789-123456789012"
}

Veja Erros para a lista completa de códigos e o formato padrão de resposta de erro.