API (Webhook)

The API trigger exposes a REST endpoint that external systems can use to send messages to your agent — n8n, Make, Zapier, CRM, your own backend, anything that can perform an HTTP POST. The reply can be synchronous (the agent answers in the same call) or asynchronous (the reply arrives at a webhook you provide).

Enabling the channel

1. Open the agent in the admin panel.
2. Go to Triggers.
3. In the API card, click Connect.

When active, the card shows:

• the agent Endpoint (with a copy button);
• View full API documentation (opens the Swagger reference);
• Webhook History (logs of recent calls).

To turn it off, click Disconnect — the URL stops accepting calls immediately.

Endpoint

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

The {agentId} is already filled in the card after you connect. Full interactive documentation (schemas, examples, in-page testing) lives on the API Documentation page reachable from the card.

Authentication

Authorization header with a Bearer token:

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

Tokens are issued per organization. Generate and manage them in the admin panel under Settings -> API.

Payload

Main fields:

• message (string, required) — the message text.
• sync (boolean, optional) — true for synchronous reply (10s timeout). Default: async.
• webhook_url (string, optional) — URL that receives the reply in async mode. You receive a POST with the result.
• attachments (array, optional) — attachments as { name, url, type, mimeType }. type: image, audio, or file. Accepts a public URL or base64.
• metadata (object, optional) — arbitrary data echoed back in the webhook. Use it to correlate the reply with a CRM ticket, lead, order, etc.
• conversation_id (string, optional) — to continue an existing conversation. Without it, a new conversation is created.

Example: synchronous call with curl

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

Response (summary):

{
  "conversation_id": "uuid",
  "message": "We are open Monday to Friday, 9am to 6pm.",
  "credits_used": 12
}

Example: async call with webhook

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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": "client@company.com"
    }
  }'

The API returns 202 Accepted right away. When the agent finishes, you receive a POST at webhook_url with the result and the original metadata — use it to match the reply against your source record.

Attachments

Accepted formats:

• Images: JPEG, PNG, WebP, GIF.
• Documents: PDF, TXT, MD, CSV, DOC, DOCX, XLS, XLSX.

Not accepted: video in any format. Audio only through dedicated chat channels (use Telegram or WhatsApp for audio).

Call history

The Webhook History button opens a log of recent incoming calls: status, payload, timestamp. Useful for debugging integrations.

When to use it

• You already have a CRM/backend/n8n and want to call the agent as just another API.
• You need to correlate replies with external IDs (ticket, lead, order) using metadata.
• You want to integrate the agent into an automated flow with no end user in chat.

For anything else (human support, public link, messaging app), prefer Public URL and Widget, WhatsApp Official, or Telegram.