API (Webhook)

The API channel creates an inbox with a REST endpoint. Use it to let a CRM, n8n, Make, Zapier, or your own backend send messages to SquadOS. The inbox can route incoming messages to an AI agent or human support.

This guide covers channel connection and operation. For the full field, response, and error contract, see Chat.

Before you start

You need Create and edit inboxes to create, edit, activate, or deactivate the inbox. The integration also needs a Bearer token from the same organization; generation requires Create and rotate API tokens.

Caution

The token grants access to the organization’s public API and has no endpoint scopes. Keep it only on your server or in the integration’s secret vault. Never put it in a frontend, mobile app, repository, log, or prompt.

Connect the inbox

1. In Admin, open Inboxes and select Connect inbox.

2. Under Other channels, choose API. This channel does not request provider credentials.

3. Under Who answers this inbox?, select Human support or an active agent. An inactive agent can still appear in the selector, but the runtime will reject the message; verify the agent’s state before finishing.

4. Fill in Inbox name and select Done. The inbox is created active.

For an existing inbox, open the row’s actions menu and choose Edit. The Connection block shows Connected and, under Information, the copyable endpoint.

Endpoint and identifier

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

Copy the full endpoint displayed under Information. On the Inboxes screen, {id} is the API inbox ID, even though the current label says Agent ID. Use the inbox ID: it also works when the destination is human support and preserves the correct conversation source.

For compatibility, the endpoint accepts the ID of an agent that has an active API inbox. That alternative does not work for an inbox without an agent and can be ambiguous when operations are organized around inboxes.

Create and use the token

Open the avatar menu and follow Settings → Developers → API. On the Tokens tab, generate a token and copy the secret when it appears; the complete value is not shown again.

Send it with every call:

Authorization: Bearer pk_your_token_here
Content-Type: application/json

See creation, rotation, revocation, and permissions in Authentication.

First call

Without webhook_url, the agent response returns on the same HTTP connection. sync: true makes that intent explicit:

curl -X POST https://api.squados.io/v1/chat/API_INBOX_ID \
  -H "Authorization: Bearer pk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "sync": true,
    "external_user_id": "crm-customer-123",
    "user_name": "Maria Silva"
  }'

A normal execution returns 200 with success, conversation_id, message_id, response, model, credits_used, and attachments_processed. The text response field is named response, not message. The endpoint does not promise a fixed ten-second timeout; configure the client for the agent’s actual execution time.

Keep the returned conversation_id to continue the exact same service thread. Without it, external_user_id looks up the latest conversation for that identifier in the organization; therefore, do not reuse the same identifier for different people.

Asynchronous callback

Send webhook_url and do not use sync: true when the integration should not hold the connection open:

{
  "message": "Analyze the attached report",
  "webhook_url": "https://integration.example.com/squados/callback",
  "metadata": { "ticket_id": "TKT-12345" }
}

The initial acknowledgment is 202 Accepted, with status: "processing" or status: "debounced" and the conversation_id; it does not yet contain the assistant response. When processing ends, SquadOS sends a POST to the callback with event: "message.completed", the response, and the original metadata.

Validate callbacks idempotently and accept additional fields. Current delivery has a ten-second deadline, one attempt, and no dedicated signature header. See payloads, transfers, and delivery considerations in Webhooks.

Text, attachments, and storage

Send message, at least one item in attachments, or both. Each attachment uses an HTTP/HTTPS url accessible to SquadOS or a complete data URL such as data:image/png;base64,...; base64 without the data: prefix is not accepted. type can be image, audio, or file, and actual processing depends on the agent and model.

Other useful fields:

• role: "assistant" records an external message without running the agent;
• onlyStorage: true stores the input without running the pipeline;
• metadata preserves free-form correlation data and returns it in the callback;
• conversation_id, external_user_id, and user_name control continuity and contact identity.

See attachment schemas and examples in Chat.

Deactivate and troubleshoot

Under Inboxes → Actions → Edit → Connection, use Disconnect to deactivate the inbox. Calls using its ID then return 403 trigger_inactive. To accept calls again, open the same block and select Activate.

The list’s Own channel badge does not confirm that the API is active; check the state inside Connection. The Webhook History button is also unavailable in the current Inboxes flow. Record statuses, bodies, and identifiers in your own system and consult Errors when investigating a failure.

Deletion is different from deactivation: deleting removes the inbox and its configuration. Prefer deactivation for a temporary interruption.