API docs by Redocly

Chat Data API Schema Guide (2.0.0)

Download OpenAPI specification:Download

Introduction

Welcome to Chat Data Guide and API Reference, Version 2.0.0!

Chat Data is a platform that allows you to create AI chatbots using your chosen data or data provided by the service. It offers the following features:

Integration: You can integrate a chat widget or iframe on your website by either providing any customized documents(.pdf, docs, html, txt), website links, plaintext or Q&As.

Language Compatibility: Chat Data is designed to work with multiple languages. You can use it with sources in any language and pose questions in any language as well.

User Analysis: The owner of the chatbot has the ability to monitor user activities on the chatbot. They can analyze user geographic distribution, track user activities.

Customer Information Gathering: When customers express interest in the owner's products or services, the chatbot can collect customer information. This allows the owner to gather valuable data for marketing and customer relationship management purposes.

Daily Notifications: Chatbot owners can receive daily email notifications containing all chatbot conversations and collected leads

This reference serves as a comprehensive guide to the Chat Data system and its Version 2.0.0 API. Here, you'll find detailed information on the objects and endpoints used in the API. We greatly value your feedback. If you notice any missing or inaccurate information, please don't hesitate to email us at: admin@chat-data.com.

To leverage Chat Data's API capabilities, you'll need an API key. API keys can be created by subscribing to an appropriate membership plan on chat-data.com.

Conventions

All API requests should be directed to the domain api.chat-data.com. and secure HTTPS is mandatory for all interactions.

Our ChatDOC API adheres to RESTful conventions where applicable, utilizing standard HTTP methods such as GET, POST, PUT, and DELETE. Request and response payloads are encoded in JSON format.

HTTP status codes are used in accordance with industry standards. Successful requests return a 200 OK response, while failed requests produce 4xx or 5xx error codes.

If you have any questions or need further assistance, please don't hesitate to reach out to our support team.

JSON conventions

  • Response body of success requests is generally as follows:

    {
  "status": "success",
  "id": 160,
  "name": "Bo",
  ...
}
    • status is a common property.
    • Depending on the function of the api call, there might be other properties as well.

  • And failed response may be:

    {
    "status": "error",
    "message": ""Error message""
}
    • status and message are common properties.

  • Property names are in camelCase (not snake_case or kebab-case).

  • Optional properties are nullable, you can just ignore it sometimes.

Request limits

To maintain a uniform developer experience for all API users, the Chat Data API enforces rate limits at 600 requests per minute (RPM). Requests from the same user are subject to the same rate limiter pool.

Authentication

Requests use the HTTP Authorization header to both authenticate and authorize operations. The Chat Data API accepts bearer tokens in this header. Bearer keys can be managed in the your account page.

curl 'https://api.chat-data.com/api/v2/{{endpoint}}'   -H 'Authorization: Bearer $API_KEY'

Different keys of the same user are interoperable of each others' resource, they share common permission and rate limit of the user.

Please note: keep your API keys confidential, and do not put them in any client code, including browser html and mobile client, API interactions should be done on the server side.

Chat Data Website Guide

Creating Chatbot

Migrated to Creating Chatbot.

Getting Started With Your Chatbot Settings

Migrated to Basic Configurations.

Enhancing Chatbot Responses

Migrated to Debug And Optimization.

Webhooks Setup

Migrated to Webhooks Setup.

Discord Bot Integration

Migrated to Discord Bot Integration.

Slack Bot Integration

Migrated to Slack Bot Integration.

Whatsapp Integration

Migrated to WhatsApp Integration.

Train by Products From Shopify Store

Migrated to Train With Your Data#Shopify.

Add Chatbot to Your Shopify Store

Migrated to Add a Chatbot to Your Shopify Store.

Shopify Webhook Synchronization Integration

Migrated to Shopify Webhook Synchronization Integration.

Import Products From WooCommerce Store

Migrated to Train With Your Data#WooCommerce.

Add Chatbot to Your WordPress Website

Migrated to Add a Chatbot to Your WordPress Website.

WooCommerce Webhook Synchronization Integration

Migrated to WooCommerce Webhook Synchronization Integration.

Customizing Your Domain for Embedding Scripts

Migrated to White Label Your Chatbot.

Chat Data RESTful API

Chatbot Operations

Create and train a chatbot

Create a Chatbot using either our medical chat models or your own data with GPT-3.5 or GPT-4.0.

You can poll the status of the training by GET /chatbot/status/{chatbotId} at interval of 10s. Generally it takes 1-2 minutes to finish depending on content length of the provided text or websites.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
chatbotName
required
string (Chatbot Name)

The name of the chatbot to be created.

sourceText
string (Source Text)

Text data for the chatbot, subject to character limits based on your plan. Relevant only if the model is custom-data-upload.

urlsToScrape
Array of strings (Urls To Scrape)

A list of URLs is provided for text content extraction by Chat Data. Since it is not possible to ascertain the website's textual content in advance, the web crawling process will terminate when either the list of URLs is exhausted or when the chatbot's character limit is reached. We kindly request that you ensure your URLs commence with the http:// or https:// protocol, such as in the format https://www.chat-data.com. Relevant only if the model is custom-data-upload.

customBackend
string (Custom Backend)

The URL of a customized backend for the chatbot, to be used if you prefer to use your own backend.

bearer
string (Bearer)

The authentication bearer token required to access and authenticate against your custom backend.

model
string (Chatbot Model)
Default: "custom-data-upload"
Enum: "custom-data-upload" "medical-chat-human" "medical-chat-vet" "custom-model"

The chatbot uses different models:

  • For custom data upload: custom-data-upload
  • For medical chat with humans: medical-chat-human
  • For medical chat with veterinarians: medical-chat-vet
  • For custom model: custom-model

The chatbot defaults to custom-data-upload if the model paramter is not provided. In medical models and custom model, sourceText and urlsToScrape are ignored.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrain an existing chatbot

The Chatbot Retrain API enables you to retrain the chatbot when the chatbase's model is custom-data-upload. This API will fail if the chatbot is another model.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

sourceText
string (Source Text)

Text data intended for chatbot training. Subject to character limits based on the user's plan. Applicable only for models with custom data upload capability.

urlsToScrape
Array of strings (URLs to Scrape)

A list of URLs provided for text content extraction. The web crawling process concludes once the list of URLs is fully processed or the chatbot's character limit is reached. Please ensure URLs begin with 'http://' or 'https://'. Applicable only for models with custom data upload capability. Existing website with the same url will be recrawled to get the latest content.

Array of objects (Products for Training)

A list of products for training the chatbot.

Array of objects (Q&As for Training)

A list of Q&As for the chatbot to learn specific topic answers.

Array of objects or objects or objects or objects or objects (Knowledge Chunks to Delete)

A list of knowledge sources to remove from the chatbot's knowledge base.

Responses

Request samples

Content type
application/json
{
  • "chatbotId": "string",
  • "sourceText": "Example training text.",
  • "urlsToScrape": [],
  • "products": [
    ],
  • "qAndAs": [
    ],
  • "deletes": [
    ]
}

Response samples

Content type
application/json
{}

Get Chatbot Status

Get the current training progress of the chatbot.

Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "progress": 100
}

Delete a chatbot

This API enables the deletion of a chatbot by specifying its ID. It removes the chatbot along with its associated data from the system, including training data, user monitoring data, conversations, leads information, etc. Exercise caution when using this deletion action, as all deleted sources are unrecoverable.

Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Get all chatbots

Returns a list of all chatbots under your account with related information.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "chatbots": [
    ]
}

Get a chatbot

Returns the related information about a single chatbot. The returned chatbot schema is the same as the /get-chatbotsendpoint.

Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "chatbot": {
    }
}

Update Chatbot Settings

This API endpoint allows you to edit your chatbot.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the generated chatbot. You can initiate API calls pertaining to this chatbot using this ID.

chatbotName
string (Chatbot Name)

The name of the created chatbot.

basePrompt
string (Base prompt)

Base prompt for the chatbot

initialMessages
Array of strings (Initial messages)

Array of initial messages to be used by the chatbot

suggestedMessages
Array of strings (Suggested messages)

Array of suggested messages shown in the chatbot.

visibility
string (Visibility)
Enum: "private" "public"

Visibility status of the chatbot 'private' | 'public'. It controls whether your chatbot is accessible to others.

onlyAllowOnAddedDomains
boolean (Only allow on added domains)

Enable or disable only allow the iframe and widget on specific domains

domains
Array of strings (Domains)

Array of only allowed domains

rateLimitPoints
number (RateLimit points)

The limit on the number of messages (even if each message by GPT-4.0 consume 20 message credits, it's still considered as one message here in the rate limiter) to be sent from one device every rateLimitTimeframe seconds

rateLimitTimeframe
number (RateLimit timeframe)

The timeframe (in seconds) in which the messages limit sent

rateLimitMessage
string (RateLimit message)

The error message shown to the user when the conversation is rate limited.

baseModel
string (Base Model)
Enum: "gpt-3.5" "gpt-4"

The OpenAPI model used in our RAG processing pipeline.

temperature
number (Temperature) [ 0 .. 1 ]

The temperature parameter for the AI model with range [0, 1]

storeChat
boolean (Store Chat History)
Default: true

Indicates whether the chat history will be stored on our server. This option is automatically disabled when utilizing our medical chat models to prioritize user privacy and comply with confidentiality standards.

Array of objects (Links for Frequently Asked Questions)

An array representing added frequently asked questions pages.

showCalendar
boolean (Show Calendar)
Default: false

Specifies whether the Calendly booking button should be displayed in the chatbot widget or iframe.

calendarUrl
string (Calendly url)

The URL of Calendly for users to schedule appointments.

calendarMessage
string (Calendly message)

The message to display for appointment scheduling.

enableBouncingAnimation
boolean (Enable bouncing animation)
Default: true

At the session start, determines whether the chatbot bubble should bounce to attract attention.

ignoreDataSource
boolean (Ignore Data Source)
Default: false

Whether custom data uploaded by the user should be ignored for chatbot responses. If set to true, the chatbot will act the same as a pure ChatGPT chatbot. This option is applicable when the chatbot is based on the custom-data-upload model.

object (Configuration to collect customer information)

The information to be collected from potential customers.

object (Chatbot styles)
object (Configuration for email notifications from the chatbot)

The configuration for sending daily email notifications.

customBackend
string (Custom Backend)

The URL of a customized backend for the chatbot, to be used if you prefer to use your own backend.

bearer
string (Bearer)

The authentication bearer token required to access and authenticate against your custom backend.

Responses

Request samples

Content type
application/json
{
  • "chatbotId": "string",
  • "chatbotName": "string",
  • "basePrompt": "string",
  • "initialMessages": [
    ],
  • "suggestedMessages": [
    ],
  • "visibility": "private",
  • "onlyAllowOnAddedDomains": true,
  • "domains": [
    ],
  • "rateLimitPoints": 0,
  • "rateLimitTimeframe": 0,
  • "rateLimitMessage": "string",
  • "baseModel": "gpt-3.5",
  • "temperature": 0,
  • "storeChat": true,
  • "qALinks": [],
  • "showCalendar": false,
  • "calendarUrl": "https://calendly.com/user/example",
  • "calendarMessage": "Book a demo",
  • "enableBouncingAnimation": true,
  • "ignoreDataSource": false,
  • "leadsConfig": {
    },
  • "styles": {
    },
  • "notification": {},
  • "customBackend": "https://api.chat-data.com/api/v2/chat",
  • "bearer": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Update profile picture

This API endpoint allows you to update the profile picture of your chatbot.

Example request by curl:

curl -X POST -H "Content-Type: multipart/form-data" -F "image=@/path/to/your/image.jpg" https://api.chat-data.com/api/v2/upload-chatbot-profile-picture/{chatbotId}
Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string

The unique identifier allocated to the chatbot.

Request Body schema: multipart/form-data
required
image
string <binary> (Picture file path)

The path of the profile picture.

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete chatbot profile picture

Delete a chatbot profile picture.

Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Update chatbot icon

This API endpoint allows you to update the icon picture of your chatbot.

Example request by curl:

curl -X POST -H "Content-Type: multipart/form-data" -F "image=@/path/to/your/image.jpg" https://api.chat-data.com/api/v2/upload-chatbot-icon/{chatbotId}
Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string

The unique identifier allocated to the chatbot.

Request Body schema: multipart/form-data
required
image
string <binary> (Picture file path)

The path of the profile picture.

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete chatbot icon picture

Delete a chatbot icon picture.

Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Retrieve confidence score for context chunks

This operation retrieves the confidence scores (defined as cosine similarity) of related chunks used to generate answers. You can use this function to obtain confidence scores before calling the /chat API endpoint, providing an estimate of the chatbot's ability to deliver high-quality answers based on the context. Chunks are cached based on the messages array, so subsequent calls to the /chat API with the same messages array will incur minimal latency in retrieving related vector embeddings from the database. Therefore, calling this API endpoint before /chat should not significantly impact overall chat performance.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
required
Array of objects (List of Message Objects)

List of messages

baseModel
string (Chatbot Base Model)
Enum: "gpt-3.5" "gpt-4"

The baseModel parameter in the API call overrides the Chatbot's baseModel setting when processing the Rag context during chatting.

chatbotId
required
string

The ID of the chatbot

Responses

Request samples

Content type
application/json
{
  • "messages": [
    ],
  • "baseModel": "gpt-3.5",
  • "chatbotId": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "averageScore": 0.8,
  • "scoresArray": [
    ],
  • "exampleChunks": [
    ],
  • "embeddingText": "what is marrow transfer"
}

Retrieve context chunks

This operation fetches segments pertinent to generating responses. Designed for seamless chatbot integration with the GPTs store, this API endpoint allows users to supply relevant document fragments to the GPTs. Similar to the /get-confidence-score endpoint, this API are cached for efficiency based on the query.

Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

Request Body schema: application/json
required
query
required
string (Query)

The text utilized for vector-based searching of the knowledge base based on the cosine similarity.

count
number (Context Count)
Default: 5

Specifies the maximum number of context segments to return that show a positive cosine similarity with the input query text.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "count": 5
}

Response samples

Content type
application/json
[
  • {
    }
]

Send Message to Chatbot

Send messages to a chatbot and receive a response.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
required
Array of objects (List of Message Objects)

List of messages

chatbotId
required
string

The ID of the chatbot

baseModel
string (Chatbot Base Model)
Enum: "gpt-3.5" "gpt-4"

The baseModel parameter in the API call overrides the Chatbot's baseModel setting when processing the Rag context during chatting.

stream
boolean (Stream)
Default: false

Whether to stream back partial progress or wait for the full response

conversationId
string (Conversation ID)

ID of the current conversation. The chatbot will generate one if this field is undefined.

Responses

Request samples

Content type
application/json
{
  • "messages": [
    ],
  • "chatbotId": "string",
  • "baseModel": "gpt-3.5",
  • "stream": false,
  • "conversationId": "string"
}

Response samples

Content type
text/plain
abc
chunk2
chunk3

Chatbot Analytics

Get conversations.

Get conversations from a chatbot. This operation support paginations. Example request by curl:

curl -X GET https://api.chat-data.com/api/v2/get-conversations/{chatbotId}?startTimestamp={value1}&endTimestamp={value2}&start={value3}&size={value4}
Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

query Parameters
startTimestamp
number (Start Timestamp)

The timestamp of the start date.

endTimestamp
number (End Timestamp)

The timestamp of the end date.

start
number (Start)
Default: 0

The start position of the results, used for pagination.

size
number (Size)

The maximum size of the results retrieved after the start position, used for pagination.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "conversations": [
    ]
}

Get Customers.

Get collected customers from a chatbot. This operation support paginations. Example request by curl:

curl -X GET https://api.chat-data.com/api/v2/get-customers/{chatbotId}?startTimestamp={value1}&endTimestamp={value2}&start={value3}&size={value4}
Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

query Parameters
startTimestamp
number (Start Timestamp)

The timestamp of the start date.

endTimestamp
number (End Timestamp)

The timestamp of the end date.

start
number (Start)
Default: 0

The start position of the results, used for pagination.

size
number (Size)

The maximum size of the results retrieved after the start position, used for pagination.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "customers": []
}

Get the statistic distribution of the chatbot.

Get the aggregated statistics of a chatbot. Example request by curl:

curl -X GET https://api.chat-data.com/api/v2/get-analysis/{chatbotId}?startTimestamp={value1}&endTimestamp={value2}
Authorizations:
HTTPBearer
path Parameters
chatbotId
required
string (Chatbot ID)

The unique identifier allocated to the chatbot.

query Parameters
startTimestamp
number (Start Timestamp)

The timestamp of the start date.

endTimestamp
number (End Timestamp)

The timestamp of the end date.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "countryDistribution": [
    ],
  • "hourDistribution": [
    ],
  • "creditsDistribution": [
    ]
}

User Account

Get the current plan of the user

Get a summary of the user's current subscriptions and priviledges.

Response example:

{
  status: "success"
  plan: {
    subscriptions: {standard: 1},
    remainingTrainingChars: 50000000,
    refreshingTrainingChars: 110000000,
    remainingCredits: 5000,
    refreshingCredits: 10000,
    chatbots: 2,
    chatbotsLimit: 5,
    chatbotCharactersLimit: 11000000,
    gatherLeads: true,
    customDomain: true,
    api: true,
    customModel: true,
    userAnalysis: true,
    notification: true,
    gpt4: true,
    removeBrand: false,
  }
}
Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "plan": {
    }
}