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

Shell

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

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "text": "Hello!"
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code, 
      response.content.decode('utf-8')))

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

Parameter	Type	Description
api_key	string	Create an account and subscribe to obtain your API key
scenario_id	Text	ID associated with your Quickchat API implementation.
text	string	User input message

Send message to the AI Assistant

Shell

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!",
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code, 
      response.content.decode('utf-8')))

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

Parameter	Type	Description
api_key	string	Create an account and subscribe to obtain your API key
scenario_id	string	ID associated with your Quickchat API implementation.
conv_id	string (Optional)	Identify a particular conversation/user.
text	string	User input message.
message_context	string (Optional)	Additional client-provided per-message context which is passed to the AI alongside the message.
client_metadata	dict (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.

Shell

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}
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "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'}
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code, 
      response.content.decode('utf-8')))

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.

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