Chat

The chat endpoint sends a message to an agent and returns (or delivers via webhook) the generated response. The response can be synchronous — you wait in the same call — or asynchronous — SquadOS fires a POST to your URL as soon as the agent finishes processing.

Tip

To simply enable the API channel on an agent (activate the trigger), see the API (Webhook) guide. This page is the technical reference for the endpoint.

POST /chat/{agentId}

Path parameters

Parameter	Type	Description
agentId	string (UUID)	ID of the agent that will receive the message.

Request body

Field	Type	Required	Description
message	string	Yes	Message content.
role	string (user | assistant)	No	Message role. Default: user. Use assistant to sync history (see example below).
sync	boolean	No	If true, waits for the agent’s response in the same call (10 s timeout). Default: false.
conversation_id	string (UUID)	No	ID of an existing conversation. Omit to create a new one.
external_user_id	string	No	External user ID (e.g. your CRM ID). SquadOS automatically resumes that user’s last conversation with the agent.
user_name	string	No	Display name of the lead/end user for this conversation. Makes the conversation appear named in the Conversations list (instead of “External Contact”) and searchable by name. Persisted on the conversation and refreshed on every call that provides it. Map your integration’s name field here.
webhook_url	string (URI)	No	URL that will receive the response via POST when processing finishes. Incompatible with sync: true.
attachments	array of Attachment	No	Files or images attached to the message. See field table below.
metadata	object	No	Free-form data for correlation. Echoed back in the webhook payload without modification.

Attachment fields

Field	Type	Required	Description
name	string	Yes	File name (e.g. contract-2024.pdf).
url	string (URI)	Yes	Public URL of the file or a base64 string.
type	string (image | audio | file)	Yes	Attachment type.
mimeType	string	No	MIME type (e.g. image/jpeg, application/pdf).

Response modes

Synchronous (sync: true) Pass "sync": true in the body. SquadOS waits for the agent to reply and returns 200 with the complete response. The timeout is 10 seconds — if the agent takes longer, the API returns 408 (see Errors).

Asynchronous (webhook_url) Pass a valid webhook_url. The API returns 202 immediately with the conversation_id and message_id. When the agent finishes, SquadOS sends a POST to your URL with the full payload. See Webhooks for the payload format and signature validation.

---

a) Simple synchronous request

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your store opening hours?",
    "sync": true
  }'

Response 200

{
  "success": true,
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "response": "Our store is open Monday through Friday from 9 AM to 6 PM, and Saturdays from 9 AM to 1 PM.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.003,
  "attachments_processed": 0
}

---

b) Asynchronous request with webhook and metadata

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze this Q4 sales report",
    "webhook_url": "https://hooks.n8n.cloud/webhook/abc123",
    "metadata": {
      "crm_ticket_id": "TKT-12345",
      "customer_email": "customer@company.com"
    }
  }'

Response 202

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

When the agent finishes, SquadOS will send a POST to https://hooks.n8n.cloud/webhook/abc123 with the full response and the echoed metadata object. See Webhooks.

---

c) Image attachment (synchronous)

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What do you see in this image?",
    "sync": true,
    "attachments": [
      {
        "name": "product-photo.jpg",
        "url": "https://example.com/images/product-photo.jpg",
        "type": "image",
        "mimeType": "image/jpeg"
      }
    ]
  }'

Response 200

{
  "success": true,
  "conversation_id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
  "message_id": "f6a7b8c9-d0e1-2345-f012-456789012345",
  "response": "The image shows a product packaged in a white box with a blue logo. It appears to be a small electronic device.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.008,
  "attachments_processed": 1
}

---

d) PDF file attachment (synchronous)

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the contents of this contract",
    "sync": true,
    "attachments": [
      {
        "name": "contract-2024.pdf",
        "url": "https://example.com/docs/contract-2024.pdf",
        "type": "file",
        "mimeType": "application/pdf"
      }
    ]
  }'

Response 200

{
  "success": true,
  "conversation_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
  "message_id": "b8c9d0e1-f2a3-4567-1234-678901234567",
  "response": "The contract is a service agreement between parties X and Y, valid for 12 months starting January 2024. Key clauses cover scope of service, pricing, confidentiality, and termination.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.015,
  "attachments_processed": 1
}

---

e) Outbound assistant message (sync history)

Use "role": "assistant" to record a message sent by the assistant outside the normal flow — for example, a proactive notification you generated in your own system. This keeps the conversation history consistent in SquadOS. A conversation_id is required.

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Thank you for reaching out! Your order has been processed.",
    "role": "assistant",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response 202

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

---

f) Automatic continuation by external_user_id

Use external_user_id to automatically resume a user’s last conversation with the agent. You don’t need to store conversation_id in your system — SquadOS looks up the conversation by the external ID.

Combine it with user_name so the conversation shows up named (and searchable) in the Conversations list, instead of “External Contact”.

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I'\''m back! What was the status of my order?",
    "sync": true,
    "external_user_id": "crm-customer-123",
    "user_name": "Maria Silva"
  }'

Response 200

{
  "success": true,
  "conversation_id": "d0e1f2a3-b4c5-6789-3456-890123456789",
  "message_id": "e1f2a3b4-c5d6-7890-4567-901234567890",
  "response": "Welcome back! Your order #98765 has been approved and is being packed. Expected shipping date is tomorrow.",
  "model": "openai/gpt-4o-mini",
  "credits_used": 0.004,
  "attachments_processed": 0
}

---

Errors

Code	Situation
404	Agent not found or no active API channel.
408	Timeout in synchronous mode — the agent did not respond within 10 s. The conversation_id and message_id are returned so you can retrieve the response later via Conversations.

Example 408 response

{
  "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"
}

See Errors for the complete list of codes and the standard error response format.