API integration

My API

Register your REST API as tools the AI bot can call. Write the spec in the dashboard, test it, and connect it. No code deploy is required.

#How it works

Each operation in the spec becomes one tool the AI can call. The AI reads the operation’s description, decides when to use it during the chat, fills in the values, and calls it.

Customer: “Where is order DM-10001? The last four digits of my phone are 1234.”
AI → verify_customer(order_no, phone_last4) → customer confirmed
AI → get_order(order_no) — the customer ID is filled in from the identity-check result
AI: “It’s on the way with CJ Logistics. [Track shipment](…)”

The Cliptalk server sends the request. Keys stay on the server. Only the response data is passed to the model.

POST https://www.mydomain.com/api/shop/verify
Authorization: Bearer ••••••
Content-Type: application/json

{ "order_no": "DM-10001", "phone_last4": "1234" }

→ 200
{ "ok": true, "customer": { "id": "cus_1001", "name": "Alex Kim" } }

GET https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10001
Authorization: Bearer ••••••

→ 200
{ "ok": true, "order": { "status": "shipped", "status_label": "Shipping", … } }

#Get started

1
Open the studio
Project → AI bot → connector My API (custom) → Create API spec.
2
Pick a template
A standard connector for your industry fills the spec with your project’s own domain (https://www.mydomain.com/api/…). The spec is in the API reference. Try the “Demo shop” sample first, or start from a blank spec.
3
Save
Click Save at the top. Secrets are bound to the saved base URL, so save first.
4
Add a secret
Save the key on the Secrets tab. For the demo, click Insert demo key.
5
Test
On the API test tab, call verify_customer, then get_order.
6
Connect
Use Save and connect to the AI bot. In the widget, say “Look up my order.”

#Basics

Field	Description
`Base URL`	Prefixed to every operation path. https required, public internet addresses only. Example: https://api.example.com/v1
`Auth`	None / Bearer token / API key header / Basic / query parameter. You pick a secret name, not the key value.
`Extra headers`	Fixed headers on every request. Reference a secret as {{secrets.NAME}}.
`Response timeout`	2–30 seconds. After that the call fails and the AI apologizes to the customer.
`Identity-check hint`	Shown in the greeting as “(tell us … to get started)”.
`What it can do`	Capability list shown in the greeting.
`API rules`	Extra rules for the AI (for example, explain returns for orders that already shipped).

{
  "name": "Our shop API",
  "baseUrl": "https://api.example.com/v1",
  "timeoutMs": 12000,
  "auth": { "type": "header", "secret": "API_KEY", "headerName": "x-api-key" },
  "headers": [
    { "name": "X-Store-Id", "value": "store_77" },
    { "name": "X-Store-Token", "value": "{{secrets.STORE_TOKEN}}" }
  ],
  "verifyHint": "Please share the order number and the last 4 digits of the phone number",
  "capabilities": ["Order and shipping lookup", "Cancel an order before it ships"]
}

#Writing operations

Field	Description
`Tool name`	Lowercase letters, digits, and _ (example: get_order). A verb makes it easier for the AI.
`Description`	This matters most. Say what it returns, when to use it, and any preconditions.
`Method and path`	GET/POST/PUT/PATCH/DELETE and the path after the base URL. {name} is a path parameter.
`Kind`	Read: call immediately · Verify: confirm the customer and remember the result · Action: run after the customer agrees
`Result path`	The part of the response to pass to the AI (example: data.orders). Empty means the whole body.
`Customer path`	(Verify) Where the customer object sits in a success response. Default: customer.
`Preview (dry_run)`	(Action) Call with dry_run:true first, show the result, then run with dry_run:false after the customer agrees.

Good: “Lists the verified customer’s recent orders (order number, items, amount, status), newest first. Use this first for shipping questions.”
Weak: “Order API”

About 5–15 operations is a good range. Too many similar tools confuse the AI.

#Parameters

Each parameter has a location (path · query · body · header) and a value source.

Source	Description	Example
`Filled by the AI from the chat`	The AI extracts the value from what the customer said. A description, example, and allowed values make this accurate.	order_no, date
`Verified customer`	Taken from the customer object in a successful identity check. The AI cannot change it, which is safer.	customer_id ← id
`Fixed value`	Always the same value.	limit = 10

A dot in a body parameter name builds a nested object: address.zip → {"address":{"zip":"…"}}

Values that decide whose data this is, such as a customer ID, must come from verified customer fields. If the AI fills them, it is hard to stop a request that uses someone else’s ID. Re-check ownership on your API server too.

{
  "name": "get_order",
  "title": "Order detail and shipping",
  "description": "Looks up one order: items, amount paid, shipping status, and tracking number.",
  "method": "GET",
  "path": "/customers/{customer_id}/orders/{order_no}",
  "kind": "read",
  "params": [
    { "name": "customer_id", "in": "path", "type": "string",
      "required": true, "source": "customer", "value": "id" },
    { "name": "order_no", "in": "path", "type": "string",
      "required": true, "source": "model",
      "description": "Order number", "example": "DM-10001" }
  ]
}

#Identity check

To handle customer data you need one operation of kind verify. Send what the customer provides (order number + last digits of the phone, booking number + name, and so on). If it matches, return a customer object.

The customer object in a success response (default path customer) is remembered for the conversation and used by “verified customer” parameters.
Keep it short: id and name are enough. Fields such as passwords, tokens, and cards are stripped automatically.
Operations that need the customer are not called before verification (Cliptalk blocks them).
On failure, return { "ok": false, "message": "…" } and the AI asks again using that sentence.

// success
{ "ok": true, "customer": { "id": "cus_1001", "name": "Alex Kim", "grade": "VIP" } }

// failure (ok:false is a failure even on HTTP 200)
{ "ok": false, "error": "not_found",
  "message": "No customer matches that order number and the last 4 digits of the phone." }

#Actions and customer confirmation

An action (cancel, change, submit) is not executed just because the AI calls it.

When the AI calls an action tool, Cliptalk creates a proposal. If preview is on, it calls the API with dry_run: true and keeps the result.
The customer sees the details with Yes and No buttons.
If they agree, the same values are sent with dry_run: false and the action runs. The result is stored on the conversation as an “AI action log” note.
The proposal expires after 30 minutes.

Put a summary (array of strings) on the preview response to show those lines on the confirmation card.

// POST …/orders/DM-10002/cancel  { "dry_run": true }
{
  "ok": true,
  "dry_run": true,
  "summary": [
    "Order: DM-10002",
    "Items: Wireless charging pad 15W x2",
    "Refund: 38,000 KRW (3–5 business days)"
  ]
}

// after the customer agrees { "dry_run": false }
{
  "ok": true,
  "status": "cancelled",
  "message": "Order DM-10002 has been cancelled."
}

#Secrets

API keys, tokens, and passwords are entered only on the Secrets tab.

They are encrypted with AES-256-GCM as soon as you save them, and never shown again to anyone (including admins). To change one, save a new value under the same name.
The key value never appears in the model, the browser, chat history, or test results. If your API echoes a key in a response, it is redacted.
A key is sent only to the base URL domain it was saved for. If you change the spec to another domain, the key locks and must be entered again. This stops someone with edit access from swapping the URL and exfiltrating the key.
In the spec, reference a secret by name in auth settings, or as {{secrets.NAME}} in a header value. Secrets cannot be placed in query or body parameters.

Recommended: issue a key used only by the bot, with the minimum permission to read and to run the actions you need. Restrict your API to Cliptalk server IPs if you can. If a key may have leaked, revoke it at the issuer and save a new one.

// auth — Authorization: Bearer <API_KEY value>
"auth": { "type": "bearer", "secret": "API_KEY" }

// reference from an extra header
"headers": [
  { "name": "X-Store-Token", "value": "{{secrets.STORE_TOKEN}}" }
]

// do not do this (the plaintext stays in the spec)
"headers": [{ "name": "x-api-key", "value": "sk_live_abc123" }]

#API test

The API test tab sends the request from the Cliptalk server the same way the AI does during a chat. You can test unsaved edits.

Response — status code, latency, size, JSON body
What the AI receives — the payload after the result path and size limit
Request sent — the real URL, headers, and body (keys redacted)
How to fix it — guidance for 401, 404, timeouts, and other failures

Test the verify operation first. The customer object it returns is filled into test customer, so you can then test operations that need it. Actions are called as a dry_run preview by default.

Tests are limited to 30 per minute per project.

#Import OpenAPI

If you already have an OpenAPI 3 or Swagger 2 document, paste it on the JSON · Import tab to create operations in one step. Paths, parameters, JSON request bodies, and auth are converted (up to 30 operations).

Always clean up afterward: turn off operations you do not need, rewrite descriptions around when to use them, switch customer-ID parameters to “verified customer”, and check the kind (action vs read) of anything that is not GET.

#Limits

Item	Limit
`Operations`	30 maximum (5–15 recommended)
`Parameters per operation`	25 maximum
`Secrets`	10 maximum
`Request timeout`	2–30 seconds (default 12)
`Response size`	Read up to 1MB; about 12,000 characters are passed to the AI
`Address`	https and public internet addresses only. Private networks, localhost, and cloud metadata addresses are blocked. Redirects are not followed
`Apply`	New conversations, within about 20 seconds after save