Skip to main content

API

In this guide, we go through the steps necessary to integrate your custom Quickchat AI Assistant with your product via an API endpoint.

Authentication

Include your API Key and scenario_id in every request.

In order to obtain your API key, upgrade your subscription to include API Access.

Chat

Initialise new conversation / new user history

curl https://chat.quickchat.ai/chat \
-H 'Content-Type: application/json' \
-d '{
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"text": "Hello!"
}'

The above command returns JSON structured like this:

{
"ord_number": 2,
"conv_id": "abcd1234",
"reply": "Hey there! 🙂"
}

conv_id is an optional parameter. Request which does not contain conv_id starts a new conversation and newly-generated conv_id is returned.

Associate conv_id with your particular user to maintain conversation context across time and multiple user interactions.

This endpoint performs a single conversation exchange.

HTTP Request

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

Query Parameters

ParameterTypeDescription
api_keystringCreate an account and subscribe to obtain your API key
scenario_idTextID associated with your Quickchat API implementation.
textstringUser input message

Send message to the AI Assistant

curl https://chat.quickchat.ai/chat \
-H 'Content-Type: application/json' \
-d '{
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"conv_id": "abcd1234",
"text": "Hello!",
}'

The above command returns JSON structured like this:

{
"ord_number": 236,
"reply": "Hey, great to hear from you again! 😉"
}

HTTP Request

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

Query Parameters

ParameterTypeDescription
api_keystringCreate an account and subscribe to obtain your API key
scenario_idstringID associated with your Quickchat API implementation.
conv_idstring (Optional)Identify a particular conversation/user.
textstringUser input message.
message_contextstring (Optional)Additional client-provided per-message context which is passed to the AI alongside the message.
client_metadatadict (Optional)For instance {userId: 12, website: mywebsite.com}. Maximum 5 keys at a time. These parameters will be assigned to every new message and will be displayed as data columns in the conversation export in the Inbox.

Messages with custom context and metadata

As described in the Query Parameters table above, the https://chat.quickchat.ai/chat endpoint allows you to send two optional parameters: message_context and client_metadata.

Client metadata represents custom attributes which will be assigned to every new message and be displayed as data columns in the conversation export in the Inbox. You can also add custom attributes to the messages via Widget to the same effect.

Message context allows you to provide, for instance, per-user specific context to each message to give a more personalised feel to every conversation.

curl https://chat.quickchat.ai/chat \
-H 'Content-Type: application/json' \
-d '{
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"conv_id": "abcd1234",
"text": "Hello!",
"message_context": "The users name is John.",
"client_metadata": {userId: 12, website: mywebsite.com}
}'

Adding Knowledge Base Tag Filters via API

In the Quickchat AI App you have the possibility to add tags for every Article. These can be used to filter the Knowledge Base, so the AI responds only based on a subset of Articles from the Knowledge Base. Please note that so far this feature is supported only via API.

To filter by Knowledge Base topics (tags), you should add the kb_topic to your client_metadata in the API calls. Importantly, assure that the kb_topic key is present at every call to the API including initialising the conversation. Whilst the value of kb_topic can change between API calls, the parameter itself has to be constantly present during the entire conversation to be regarded by our system.

The below example shows how to add kb_topic to client_metadata. In the example, any Article with tag your-topic or no tag at all will be selected for the candidate pool of knowledge for the response.

json={
"api_key": "<API_KEY>",
"scenario_id": "<SCENARIO_ID>",
"conv_id": "abcd1234",
"text": "Hello!",
"message_context": "The users name is John.",
"client_metadata": {'kb_topic': 'your-topic'}
}

Errors

Below we have gathered the error codes which may be returned by the API, together with their description and possible solutions.

CodeDescriptionAction
400The following parameters must be provided: api_key, scenario_id, textPlease make sure all required parameters are provided.
400conv_id abcd1234 does not existPlease ensure that conv_id you are referring to is correct.
400The limit for message context is 1000 characters.Please shorten the message context to 1000 characters including whitespaces.
401UnauthorizedPlease make sure that your api_key and scenario_id are correct (see Integrations - API in the App).
500Internal Server ErrorThere is an issue on our side. Please get in touch with support.
503Service UnavailableOur servers are overloaded or temporarily unavailable due to maintenance. If problem persists, please get in touch with support.