API

This is the API channel

This page covers using the API as a channel — connecting your AI Agent to your own app or backend through the conversational Chat endpoint. Looking for the full API? Head to the REST API reference to manage your Knowledge Base, conversations, AI Actions, widget configuration, and more.

Chat

The realtime Chat endpoint sends a visitor message to your AI Agent and returns the AI reply in a single round-trip. This is the endpoint you want when building a custom chat UI on top of Quickchat AI.

It differs from the other endpoints in two ways: it sits at app.quickchat.ai/chat, outside the /v1/api/ and /v1/api_core/ base paths, and it reads scenario_id from the request body rather than from the token. It uses the same Bearer token authentication as the rest of this API.

Note

Send every request to https://app.quickchat.ai/chat. The scenario_id in the body must match the AI Agent your Bearer token is bound to.

Send Message

POST https://app.quickchat.ai/chat

Request Body

Parameter	Description
scenario_id string, required	ID of your AI Agent. Must match the scenario_id bound to the Bearer token
text string, required	User input message
conv_id string	Conversation ID. Omit on the first request to start a new conversation, then pass the returned conv_id back on subsequent requests to continue it
client_metadata object	Custom key-value pairs (max 5 keys) attached to every message. Displayed as data columns in the conversation export in the Inbox

A request without conv_id starts a new conversation, and the generated conv_id is returned in the response. Store that conv_id and send it back on later requests to maintain conversation context across multiple user interactions.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Response 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Field	Description
conv_id string	Conversation identifier. Always returned. Pass it back in the conv_id body field to continue the conversation
reply string	The AI Agent’s response. May contain HTML such as <br> line breaks
ord_number integer	Sequential message number within the conversation
src integer	Internal source indicator. API clients can ignore this field

To continue an existing conversation, pass back the conv_id you received:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Client Metadata

The Chat endpoint accepts an optional client_metadata parameter: custom attributes that are assigned to every new message and displayed as data columns in the conversation export in the Inbox. You can attach the same attributes through the widget. A maximum of 5 keys can be sent at a time, for example {"userId": 12, "website": "mywebsite.com"}.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Knowledge Base Tag Filtering

You can add tags to Knowledge Base articles and use them to restrict which articles the AI draws on, so it answers based only on a subset of the Knowledge Base. This filtering is currently supported only via the API.

To filter by tag, add a kb_topic key to client_metadata. The kb_topic key must be present on every request in the conversation, including the request that starts it. Its value can change between requests, but the key itself has to be present throughout the conversation for the filter to apply.

In the example below, any article tagged your-topic, or with no tag at all, is included in the candidate pool of knowledge for the response.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Errors

The Chat endpoint returns a plain-text error message with an appropriate HTTP status code.

Status	Description	Action
400	Missing scenario_id, or the request is not authenticated	Include scenario_id in the body and a valid Authorization: Bearer <API_TOKEN> header
400	Invalid conv_id (Conversation conv_id <id> is not valid.)	Omit conv_id to start a new conversation, or pass a conv_id returned by a previous response
404	Unknown scenario_id (No implementation found for scenario_id <id>)	Verify the scenario_id and that your Bearer token is bound to it
500	Internal server error	An issue on our side. Please get in touch with support
503	Service unavailable	Servers are temporarily overloaded or under maintenance. If the problem persists, please get in touch with support