How to create API integrations

An API integration connects Chatonio to one of your backend services so the AI can call it as a tool during a conversation — look up an order, check a balance, create a ticket, anything your API can do. Each integration owns a base URL and an auth config; one integration can expose many tools (one per endpoint you want the AI to be able to call).

When to add an API integration

• The customer’s answer depends on data that lives in your system (order id, subscription status, account balance).
• You want the AI to do something on the customer’s behalf — issue a refund, cancel a booking, mark a ticket resolved.
• For pure FAQ knowledge, prefer KB articles instead — integrations are for live, per-customer data.

Step 1 — Open the Integrations page

From the operator dashboard, go to Admin → Projects → [your project] → Integrations. You need ADMIN or MANAGER role on the project. The page lists every integration in the project, each with its tools nested underneath.

Step 2 — Create the integration

Click Add integration and fill in:

• Name — internal label (e.g. Stripe, OrderService).
• Base URL — the root of every endpoint, no trailing slash (e.g. https://api.example.com).
• Auth type — pick one of none, api_key, bearer, or basic.
• Channel scope — by default the integration is available on every channel in the project. Untick All channels to scope it to specific Telegram bots, web widgets, or email addresses.

Step 3 — Configure auth

Auth credentials are encrypted at rest with the platform’s Fernet key — you only ever see them once at entry. Pick the right shape:

API key (custom header)

{
  "type": "api_key",
  "header": "X-API-Key",
  "value": "sk_live_…"
}

Sent as X-API-Key: sk_live_… on every call. Pick any header name your API expects.

Bearer token

{
  "type": "bearer",
  "token": "eyJhbGciOi…"
}

Sent as Authorization: Bearer eyJhbGciOi….

Basic auth

{
  "type": "basic",
  "username": "service-user",
  "password": "…"
}

Step 4 — Add tools (the actual endpoints)

An integration is dormant until you add at least one tool. A tool is one HTTP endpoint the AI can call. Click Add tool on the integration row and fill in:

• Name — short, action-oriented, snake_case (get_order_status, cancel_subscription). The AI sees this name.
• Description — one sentence explaining when to use it. The AI reads this to decide. Be precise: “Returns the current shipping status for an order id. Use when the customer asks where their order is.”
• HTTP method — GET, POST, PUT, or PATCH.
• Endpoint path — appended to the integration’s base URL. Supports {placeholder} tokens that get filled from the parameters schema (e.g. /orders/{order_id}/status).
• Parameters schema — JSON Schema describing what the AI must extract from the conversation before calling the tool. Example:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The customer-facing order number, e.g. ORD-12345"
    }
  },
  "required": ["order_id"]
}

• Requires confirmation — turn on for any write or destructive operation (cancel, refund, delete). The AI will quote the parameters back to the customer and wait for an explicit “yes” before firing.
• Confirmation message template — optional, supports the same {placeholder} tokens as the path.

Step 5 — Test the connection

Hit the Test button on the integration row. Chatonio sends a probe request to your base URL with the configured auth and reports back:

{
  "success": true,
  "status_code": 200,
  "detail": "Connection OK"
}

Anything other than 2xx means your auth or URL is wrong; fix it before enabling.

Step 6 — Watch it work

Open a real conversation. When the customer asks a question whose answer needs the integration, the AI will:

1. Decide which tool fits.
2. Extract the parameters from the conversation (and ask the customer if anything is missing).
3. Either call immediately, or — if requires confirmation is on — quote the parameters and wait for “yes”.
4. Use the response to ground its reply.

Tips

• One tool per intent. Don’t try to make one endpoint serve five workflows — the AI picks better when each tool has a narrow, clear job.
• Description quality matters more than name. The AI routes on the description.
• Always require confirmation for writes. Cheap insurance against the AI over-acting on an ambiguous message.
• Keep responses small. Return only the fields the AI needs to answer; tool output is capped at 16 KB and noisy responses dilute the model’s focus.