Log in

Channels

API

💡

The API Channel allows you to create custom integrations using your bot & allows you to integrate it into what ever you like. The possibilities are endless! We can’t wait to see what you build with this.

Creating the API channel

🚨

Before you start

The API integration is only available on Standard, Pro and Enterprise plans.

  1. From the your bot dashboard, go to the Channels tab and enable the API channel by clicking its toggle switch. Xnapper-2023-06-29-16.17.01.png

  2. In the setting window that appears, you’ll find your integrations secret key which you’ll need later. This should be kept private as it allows access to your bot via API. Xnapper-2023-06-29-16.17.20.png

API Documentation

Start a conversation

This endpoint is used to start a conversation and allows you to obtain a conversationId. Generally, you should start with this request, then you can use the conversationId in its response to continue the conversation if desired. This step is essential if you are planning on streaming responses through our API.

Request

POST /api/public/channels/{channelId}/1.0/conversation

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

There is no request body for this request.

Example request:

curl --request POST \
--url https://chatthing.ai/api/public/channels/{channelId}/1.0/conversation \
--header 'X-API-Secret-Key: {secretKey}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • conversationId (string): The conversation identifier. This is used to continue the conversation in subsequent requests.
  • response (string): The response from the bot.

Example response:

{
  "success": true,
  "conversationId": "7bb301ad-e691-4341-8afb-b4407c4ffdf2",
  "response": "Hello, how can I help you?"
}

Status codes

  • 200 OK: The request was successful
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

Send a one off message

This end point allows you to send a one off message to your bot, if you haven’t started a conversation, one will be created & the conversationId will be returned to you, just in case you wish to continue the conversation.

Request

POST /api/public/channels/{channelId}/1.0/message

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • response (string): The message to the bot.

Example request:

curl --request POST \
--url https://chatthing.ai/api/public/channels/{channelId}/1.0/message \
--header 'Content-Type: application/json' \
--header 'X-API-Secret-Key: {secretKey}' \
--data '{
  "message": "What is the distance to the moon?"
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • conversationId (string): The conversation identifier. This is used to continue the conversation in subsequent requests.
  • response (string): The response from the bot.

Example response:

{
  "success": true,
  "conversationId": "ea74ba3d-6645-4a88-92d1-7f78b1f83688",
  "response": "The average distance from the Earth to the Moon is about 238,855 miles (384,400 kilometers)."
}

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 429 Too Many Requests: You may of run out of message credits or the ChatGPT API may be overloaded
  • 500 Internal Server Error: An error occurred on the server

Continue a conversation

The same /message end point also allows you to continue an existing conversation. Providing a conversationId gives your bot access to earlier messages in a given conversation helping it to better serve your users.

Request

POST /api/public/channels/{channelId}/1.0/message

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • conversationId (string): The conversation identifier. This is used to continue the conversation in subsequent requests.
  • message (string): The message to the bot.

Example request:

curl --request POST \
--url https://chatthing.ai/api/public/channels/{channelId}/1.0/message \
--header 'Content-Type: application/json' \
--header 'X-API-Secret-Key: {secretKey}' \
--data '{
    "conversationId": "ea74ba3d-6645-4a88-92d1-7f78b1f83688",
    "message": "How close does it get to Earth?"
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • conversationId (string): The conversation identifier. This is used to continue the conversation in subsequent requests.
  • response (string): The response from the bot.
{
  "success": true,
  "conversationId": "ea74ba3d-6645-4a88-92d1-7f78b1f83688",
  "response": "The distance between the Earth and the Moon varies throughout the month and year due to the Moon's elliptical orbit. The closest the Moon gets to Earth is about 225,623 miles (363,104 kilometers) and the farthest it gets is about 251,000 miles (405,500 kilometers). This difference in distance is known as the lunar perigee and apogee, respectively."
}

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 429 Too Many Requests: You may of run out of message credits or the ChatGPT API may be overloaded
  • 500 Internal Server Error: An error occurred on the server

Streaming message responses

The same /message endpoint also allows you to retrieve the bot's response as a stream. If anyone has used ChatGPT or one of our bots, you’ll notice the response is returned in chunks. This improves the initial response time since we don’t need to wait for the entire response before showing something to the user. Again, providing a conversationId gives your bot access to earlier messages in a given conversation, helping it to better serve your users.

This stream flag will cause our API to return partial message deltas.

Request

POST /api/public/channels/{channelId}/1.0/message

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • conversationId (string, optional): The conversation identifier. This is used to continue an existing conversation.
  • message (string): The message to the bot.
  • stream (boolean, optional): A flag to indicate you are expecting the response to be returned via a stream.

Example request:

curl --request POST \
--url https://chatthing.ai/api/public/channels/{channelId}/1.0/message \
--header 'Content-Type: application/json' \
--header 'X-API-Secret-Key: {secretKey}' \
--data '{
    "message": "What is the distance to the moon?",
    "stream": true
}'

Response

Example response:

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"role":"assistant"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":"The"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" average"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" distance"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" from"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" the"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" Earth"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" to"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" the"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" Moon"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" is"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" about"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" "},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":"238"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":","},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":"855"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" miles"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" ("},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":"384"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":","},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":"400"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":" kilometers"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{"content":")."},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-7MZUCOltFCEIMM1zJWdb2LI5teuCl","object":"chat.completion.chunk","created":1685613980,"model":"gpt-3.5-turbo-0301","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 429 Too Many Requests: You may of run out of message credits or the ChatGPT API may be overloaded
  • 500 Internal Server Error: An error occurred on the server

Stream handling logic

The following example should hopefully get you up and running, or at least provide the basis for how you might approach processing the message stream response from our API.

fetch(`/api/public/channels/channelId/1.0/message`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Secret-Key": 'secretKey',
  },
  body: JSON.stringify({
    message,
    stream: true,
  }),
}).then(async (response) => {
  if (response.ok && response?.body) {
    const reader = response.body.getReader();
    const decoder = new TextDecoder("utf-8");

    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        break;
      }
      // massage and parse the chunk of data
      const chunk = decoder.decode(value);
      const lines = chunk.split("\n");
      const parsedLines = lines
        .map((line) => line.replace(/^data: /, "").trim()) // Remove the "data: " prefix
        .filter((line) => line !== "" && line !== "[DONE]") // Remove empty lines and "[DONE]"
        .map((line) => JSON.parse(line)); // Parse the JSON string

      for (const parsedLine of parsedLines) {
        const { choices } = parsedLine;
        const { delta } = choices[0];
        const { content } = delta;
        if (content) {
          console.log(content);
        }
      }
    }
  }
});

Retrieve a list of conversations

This endpoint allows users to retrieve a list of conversations. It supports pagination to efficiently navigate through large conversation sets.

POST /api/public/channels/{channelId}/1.0/conversations

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • limit (integer, optional, default 10): The maximum number of conversations to retrieve per page. The minimum value is 1 and the maximum value is 100.
  • cursor (string, optional): The ID of the last conversation from the previous page. This is used for pagination to retrieve the next set of conversations.

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/conversations \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "limit": 2
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • conversations (array): An array of conversation objects containing the following properties:
    • id (string): The unique identifier of the conversation.
    • createdAt (string): The timestamp when the conversation was created.
    • initialMessage (string): The initial message of the conversation.
  • pagination (object): Contains pagination information:
    • total (integer): The total number of conversations available.
    • last (string): The ID of the last conversation in the current page.

Example response:

{
  "success": true,
  "conversations": [
    {
      "id": "3eda9841-9813-49a4-a75c-3758ea31b43c",
      "createdAt": "2024-16-01T10:07:04.296Z",
      "initialMessage": "What is the distance to the moon?"
    },
    {
      "id": "9b03aeb0-d9fe-466d-9fc9-49607643ade7",
      "createdAt": "2024-16-01T10:07:24.458Z",
      "initialMessage": "How many planets are there in the solar system?"
    }
  ],
  "pagination": {
    "total": 15,
    "last": "fbd1e412-8071-476e-bb25-d76109b77f0a"
  }
}

The pagination object provides information about the total number of conversations available and the ID of the last conversation in the current page. This can be used for pagination purposes by passing the last conversation ID as the cursor parameter in subsequent requests.

That's it! You can now use the API to obtain a list of conversations and navigate through them using pagination logic.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

Retrieve a conversations messages

This endpoint allows users to retrieve messages linked to a specific conversation. It supports pagination to efficiently navigate through long conversations.

POST /api/public/channels/{channelId}/1.0/messages

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • conversationId (string): The ID of the conversation you want to retrieve messages for.
  • limit (integer, optional, default 10): The maximum number of messages to retrieve per page. The minimum value is 1 and the maximum value is 100.

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "conversationId": "{conversationId}",
  "limit": 10
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • messages (array): An array of message objects containing the following properties:
    • id (string): The unique identifier of the message.
    • message (string): The content of the message.
    • role (string): The role of the sender (e.g., "assistant" or "user").
    • createdAt (string): The timestamp when the message was created.
  • pagination (object): Contains pagination information:
    • total (integer): The total number of messages available for the conversation.
    • last (string): The ID of the last message in the current page.

Example response:

{
  "success": true,
  "messages": [
    {
      "id": "9df33cfc-1bc5-4990-8aa2-94552aa646c4",
      "message": "Hello, how can I help you?",
      "role": "assistant",
      "createdAt": "2024-16-01T10:07:20.127Z"
    },
    {
      "id": "4364a927-ca22-4bab-ac17-48903a514717",
      "message": "How many planets are there in the solar system?",
      "role": "user",
      "createdAt": "2024-16-01T10:07:24.324Z"
    },
    {
      "id": "b5ce7f56-9340-4072-8716-793f720f6fb1",
      "message": "There are eight planets in the solar system.",
      "role": "assistant",
      "createdAt": "2024-16-01T10:07:24.324Z"
    }
  ],
  "pagination": {
    "total": 3,
    "last": "b5ce7f56-9340-4072-8716-793f720f6fb1"
  }
}

The pagination object provides information about the total number of messages available for the conversation and the ID of the last message in the current page. This can be used for pagination purposes by passing the last message ID as the cursor parameter in subsequent requests.

That's it! You can now use the API to obtain messages linked to a particular conversation and navigate through them using pagination logic.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

Create manual data source

This endpoint allows users to create a manual data source.

POST /api/public/channels/{channelId}/1.0/data-sources

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

There is no request body for this request.

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • dataSource (object): An object containing the following properties:
    • id (string): The unique identifier of the data source.
    • type (string): The type of data source (only MANUAL).
    • state ('synced', 'syncing', 'sync_error', 'not_synced'): The state of the data source, this indicates whether it has been synced or not.
    • lastSync (string): The timestamp when the data source was last synced successfully.
    • createdAt (string): The timestamp when the data source was created.

Example response:

{
  "success": true,
  "dataSource": {
    "id": "41559b21-b8ff-44c3-8658-1c9e34273070",
    "type": "MANUAL",
    "state": "not_synced",
    "lastSync": null,
    "syncInterval": null,
    "createdAt": "2024-01-27T15:02:51.970Z"
  }
}

That's it! You can now use the API to create a manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

List manual data sources

This endpoint allows users to retrieve a list of manual data sources.

POST /api/public/channels/{channelId}/1.0/data-sources/list

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • limit (integer, optional, default 10): The maximum number of objects to retrieve per page. The minimum value is 1 and the maximum value is 100.
  • cursor (string, optional): Used to request subsequent pages, simply provide the last identifier from the pagination response structure (see below).

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "limit": 10
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • dataSources (array): An array of data source objects containing the following properties:
    • id (string): The unique identifier of the data source.
    • type (string): The type of data source (only MANUAL).
    • state ('synced', 'syncing', 'sync_error', 'not_synced'): The state of the data source, this indicates whether it has been synced or not.
    • lastSync (string): The timestamp when the data source was last synced successfully.
    • createdAt (string): The timestamp when the data source was created.
  • pagination (object): Contains pagination information:
    • total (integer): The total number of data sources.
    • last (string): The ID of the last data source in the current page.

Example response:

{
  "success": true,
  "dataSources": [
    {
      "id": "19d95fbc-8285-40bc-8cc0-3e1fe597b765",
      "type": "MANUAL",
      "state": "synced",
      "lastSync": "2024-01-27T14:39:03.038Z",
      "syncInterval": null,
      "createdAt": "2023-10-31T14:52:19.264Z"
    }
  ],
  "pagination": {
    "total": 1,
    "last": "19d95fbc-8285-40bc-8cc0-3e1fe597b765"
  }
}

The pagination object provides information about the total number of data sources and the ID of the last data source in the current page. This can be used for pagination purposes by passing the last data source ID as the cursor parameter in subsequent requests.

That's it! You can now use the API to obtain data sources linked to a particular bot and navigate through them using pagination logic.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

Get manual data source

This endpoint allows users to check the status of a manual data source.

GET /api/public/channels/{channelId}/1.0/data-sources

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

Include the following query parameters with your request:

dataSourceId={dataSourceId}

Example request:

curl --request GET \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources?dataSourceId={dataSourceId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • dataSource (object): An object containing the following properties:
    • id (string): The unique identifier of the data source.
    • type (string): The type of data source (only MANUAL).
    • state ('synced', 'syncing', 'sync_error', 'not_synced'): The state of the data source, this indicates whether it has been synced or not.
    • lastSync (string): The timestamp when the data source was last synced successfully.
    • createdAt (string): The timestamp when the data source was created.

Example response:

{
  "success": true,
  "dataSource": {
    "id": "41559b21-b8ff-44c3-8658-1c9e34273070",
    "type": "MANUAL",
    "state": "not_synced",
    "lastSync": null,
    "syncInterval": null,
    "createdAt": "2024-01-27T15:02:51.970Z"
  }
}

That's it! You can now use the API to get a manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled or the data source does not exist
  • 500 Internal Server Error: An error occurred on the server

Update manual data source

This endpoint allows users to update a manual data source.

PUT /api/public/channels/{channelId}/1.0/data-sources

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source.
  • syncInterval ('day' | 'week' | 'month' | null, optional, default null): The sync frequency.

Example request:

curl --request PUT \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070",
  "syncInterval": null
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • dataSource (object): An object containing the following properties:
    • id (string): The unique identifier of the data source.
    • type (string): The type of data source (only MANUAL).
    • state ('synced', 'syncing', 'sync_error', 'not_synced'): The state of the data source, this indicates whether it has been synced or not.
    • lastSync (string): The timestamp when the data source was last synced successfully.
    • createdAt (string): The timestamp when the data source was created.

Example response:

{
  "success": true,
  "dataSource": {
    "id": "41559b21-b8ff-44c3-8658-1c9e34273070",
    "type": "MANUAL",
    "state": "not_synced",
    "lastSync": null,
    "syncInterval": null,
    "createdAt": "2024-01-27T15:02:51.970Z"
  }
}

That's it! You can now use the API to update a manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect, the channel is not enabled or the data source does not exist
  • 500 Internal Server Error: An error occurred on the server

Delete manual data source

This endpoint allows users to delete a manual data source.

DELETE /api/public/channels/{channelId}/1.0/data-sources

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source.

Example request:

curl --request DELETE \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070"
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.

Example response:

{
  "success": true
}

That's it! You can now use the API to delete a manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect, the channel is not enabled or the data source has already been deleted
  • 500 Internal Server Error: An error occurred on the server

Create manual data source rows

This endpoint allows users to create rows linked to a manual data source.

POST /api/public/channels/{channelId}/1.0/data-sources/row

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source.
  • dataSourceRows (array): An array of data source row objects containing the following properties:
    • name (string): A unique identifier to represent the row / file, this is not provided to your bot during training.
    • content (string): A string containing markdown formatted text in utf8 forma, your bot will be trained on this information.

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/row/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070",
  "dataSourceRows": [
    {
      "name": "one.md",
      "content": "# Testing 1\n**How can I** train my pet **unicorn** to fetch the remote control?"
    },
    {
      "name": "two.md",
      "content": "# Testing 2\n**What if** clouds were actually fluffy marshmallow trampolines?"
    },
    {
      "name": "three.md",
      "content": "# Testing 3\n**Is there** a parallel universe where socks never go missing and can be used as teleportation devices?"
    }
  ]
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.

Example response:

{
  "success": true,
}

That's it! You can now use the API to create rows for your manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

List data source rows

This endpoint allows users to retrieve a list of rows related to a manual data source.

POST /api/public/channels/{channelId}/1.0/data-sources/row/list

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source.
  • limit (integer, optional, default 10): The maximum number of objects to retrieve per page. The minimum value is 1 and the maximum value is 100.
  • cursor (string, optional): Used to request subsequent pages, simply provide the last identifier from the pagination response structure (see below).

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/row/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070",
  "limit": 10
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • dataSourceRows (array): An array of data source row objects containing the following properties:
    • id (string): The unique identifier of the row.
    • name (string): The row name, we recommend you use an identifier which means something to you, perhaps a file name.
  • pagination (object): Contains pagination information:
    • total (integer): The total number of data sources.
    • last (string): The ID of the last row in the current page.

Example response:

{
  "success": true,
  "dataSourceRows": [
    {
      "id": "c4f85105-6d07-44c0-bdb7-eb0baf7c6f62",
      "name": "one.md"
    },
    {
      "id": "4f401205-5f76-46e1-a2b0-9adf66617d81",
      "name": "two.md"
    },
    {
      "id": "eb330863-4251-45c6-917d-e863c22f5bb9",
      "name": "three.md"
    }
  ],
  "pagination": {
    "total": 3,
    "last": "eb330863-4251-45c6-917d-e863c22f5bb9"
  }
}

The pagination object provides information about the total number of data source rows and the ID of the last row in the current page. This can be used for pagination purposes by passing the last row ID as the cursor parameter in subsequent requests.

That's it! You can now use the API to obtain data source rows linked to a particular data source and navigate through them using pagination logic.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled
  • 500 Internal Server Error: An error occurred on the server

Get manual data source row

This endpoint allows users to check the status of a manual data source row.

GET /api/public/channels/{channelId}/1.0/data-sources/row

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

Include the following query parameters with your request:

dataSourceId={dataSourceId}
dataSourceRowId={dataSourceRowId}

Example request:

curl --request GET \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/row?dataSourceId={dataSourceId}&dataSourceRowId={dataSourceRowId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.
  • dataSourceRow (object): An object containing the following properties:
    • id (string): The unique identifier of the data source.
    • type (string): The type of data source (only MANUAL).
    • state ('synced', 'syncing', 'sync_error', 'not_synced'): The state of the data source row, this indicates whether it has been synced or not.
    • lastSync (string): The timestamp when the data source was last synced successfully.
    • createdAt (string): The timestamp when the data source was created.
    • content (string): The content of the data source row.

Example response:

{
	"success": true,
	"dataSourceRow": {
		"id": "c4f85105-6d07-44c0-bdb7-eb0baf7c6f62",
		"type": "MANUAL",
		"state": "synced",
		"lastSync": "2024-01-27T14:39:03.014Z",
		"createdAt": "2024-01-27T14:30:01.216Z",
		"content": "# Testing 1.1\n## Blah"
	}
}

That's it! You can now use the API to get a manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect or the channel is not enabled or the data source does not exist
  • 500 Internal Server Error: An error occurred on the server

Update manual data source rows

This endpoint allows users to update manual data source rows, one at a time or in bulk.

PUT /api/public/channels/{channelId}/1.0/data-sources/row

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source.
  • dataSourceRows (array): An array of data source row objects containing the following properties:
    • id (string): The unique identifier of the data source row.
    • name (string): The row name, we recommend you use an identifier which means something to you, perhaps a file name.
    • content (string): A string containing markdown formatted text encoded as utf8, your bot will be trained on this information.

Example request:

curl --request PUT \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/row \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070",
  "dataSourceRows": [
    {
      "id": "c4f85105-6d07-44c0-bdb7-eb0baf7c6f62",
      "name": "one-updated.md",
      "content": "# Testing 1"
    },
    {
      "id": "4f401205-5f76-46e1-a2b0-9adf66617d81",
      "name": "two-updated.md",
      "content": "# Testing 2"
    },
    {
      "id": "eb330863-4251-45c6-917d-e863c22f5bb9",
      "name": "three-updated.md",
      "content": "# Testing 3"
    }
  ]
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.

Example response:

{
  "success": true,
}

That's it! You can now use the API to update manual data sources rows.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect, the channel is not enabled or the data source does not exist
  • 500 Internal Server Error: An error occurred on the server

Delete manual data source rows

This endpoint allows users to delete manual data source rows, one at a time or in bulk.

DELETE /api/public/channels/{channelId}/1.0/data-sources/rows

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source.
  • dataSourceRows (array): An array of data source row objects containing the following properties:
    • id (string): The unique identifier of the row.

Example request:

curl --request DELETE \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/rows \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070",
  "dataSourceRows": [
    {
      "id": "834976db-f946-40f1-9e86-994817d22715"
    },
    {
      "id": "057d3c71-9b00-4e53-b412-47bd135d2cdc"
    },
    {
      "id": "dcb67a0e-2a39-4ff3-a6c0-43941ec81d6a"
    }
  ]
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.

Example response:

{
  "success": true
}

That's it! You can now use the API to delete manual data source rows.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect, the channel is not enabled or the data source has already been deleted
  • 500 Internal Server Error: An error occurred on the server

Sync manual data source

This endpoint allows users to trigger a sync on a manual data source.

POST /api/public/channels/{channelId}/1.0/data-sources/sync

Include the following headers in your request:

Content-Type: application/json
X-API-Secret-Key: {secretKey}

In the request body, provide the following parameters:

  • dataSourceId (string, required): The unique identifier of the data source you wish to sync.

Example request:

curl --request POST \
  --url https://chatthing.ai/api/public/channels/{channelId}/1.0/data-sources/sync \
  --header 'Content-Type: application/json' \
  --header 'X-API-Secret-Key: {secretKey}' \
  --data '{
  "dataSourceId": "41559b21-b8ff-44c3-8658-1c9e34273070"
}'

Response

The API response will include the following information:

  • success (boolean): Indicates whether the request was successful or not.

Example response:

{
  "success": true
}

That's it! You can now use the API to trigger a sync against a manual data source.

Status codes

  • 200 OK: The request was successful
  • 400 Bad Request: The request was malformed or missing required fields
  • 403 Forbidden: The provided api secret key does not match your channel or the wrong channel id was provided in the endpoint URL
  • 404 Not Found: The channel id is incorrect, the channel is not enabled or the data source has already been deleted
  • 429 Too Many Requests: There is already a sync in progress, or you have run out of storage tokens
  • 500 Internal Server Error: An error occurred on the server
Previous
WhatsApp