How it works Pricing API Sign in Create a Chatbot

Chatbolt API

Build awesome applications with our powerful APIs.

Getting Started

Welcome to the official Chatbolt API documentation. Below are the key details for properly using the APIs

Base URL

The base URL for all API requests is:

https://api.chatbolt.ai/v1/

Authentication

To use the API, authentication is required. Make sure to include the Authorization header with your api key in all requests. You can find it on the account page.

Authorization: YOUR_API_KEY

Response Schema

All API responses are in JSON format. Successful requests return a 200 response with result: "success" and the data object. 

{
    "result": "success",
    "data": {
        "id": "64737cd6fb1b988bbd3d23f8",
        "name": "Chatbot"
    }
}

Error Handling

When an error occurs in the API, a 400 response is returned with result: "error" and the error object.

{
    "result": "error",
    "data": {},
    "error": {
        "code": "PARAM_ERROR",
        "message": "The URL provided is not valid",
        "path": "url",
        "kind": "format"
    }
}
Name Description
codeThe error code
messageA useful message
pathThe param that has errors. Only when code is PARAM_ERROR
kindThe kind of PARAM_ERROR. Can be either format or required
Error codes

The following are some common error codes that you may encounter:

Name Description
PARAM_ERRORThe error code
BAD_REQUESTA useful message
UNAUTHORIZEDThe kind of PARAM_ERROR. Can be either format or required
NOT_FOUNDThe kind of PARAM_ERROR. Can be either format or required

Basic usage

These are the main step to get started with the Chatbolt API:

  1. Create a chatbot - Create a Chatbot
  2. Add sources to the chatbot and wait for them to be trained - Add Sources
  3. Start a chat with the chatbot - Create a Chat
  4. Send messages to the chat - Message with a Chat

Libraries & SDKs

To make it as easy as possible to integrate the Chatbolt API, official libraries and SDKs exist in:

PHPComing soon
NodeJSComing soon
RubyComing soon

Test this API on Postman

Explore and test our APIs immediately using Postman:

Create a Chatbot

Create a new chatbot.
POST/chatbots

Request

{
    "name": "My new chatbot"
}
Name Description
name The chatbot's name
public If the chatbot is public (required to use the widget)
Values: true, false (default)
ai_tone The chatbot's AI tone
Values: casual, neutral (default), formal
ai_knowledge The chatbot's AI knwoledge
Values: source (default), source_then_internet, internet
ai_prompt The chatbot's AI custom prompt

Response

{
    "result": "success",
    "data": {
        "id": "647557df9c5ec4dc99b5b352",
        "name": "Chatbot",
        "public": false,
        "ai_tone": "casual",
        "ai_knowledge": "source",
        "ai_prompt": "",
        "files": 0,
        "links": 0,
        "texts": 0,
        "chars": 0,
        "chars_used": 0,
        "status": null,
        "created_at": "2023-05-30T01:56:47.847Z",
        "modified_at": "2023-05-30T01:56:47.847Z"
    }
}

Errors

Code Message
CHATBOTS_LIMIT_ERROR You have reached the chatbot limit for your current plan.

List Chatbots

Retrieve a list of chatbots.
GET/chatbots

Request

No parameters

Response

{
    "result": "success",
    "data": [
        {
            "id": "647557df9c5ec4dc99b5b352",
            "name": "Chatbot 1",
            "public": false,
            "ai_tone": "casual",
            "ai_knowledge": "source",
            "ai_prompt": "",
            "files": 8,
            "links": 32,
            "texts": 1,
            "chars": 42331,
            "chars_used": 42331,
            "status": "trained",
            "created_at": "2023-05-30T01:56:47.847Z",
            "modified_at": "2023-05-30T01:56:47.847Z"
        },
        {
            "id": "64737cd6fb1b988bbd3d23f8",
            "name": "Chatbot",
            "public": false,
            "ai_tone": "casual",
            "ai_knowledge": "source",
            "ai_prompt": "",
            "files": 3,
            "links": 22,
            "texts": 2,
            "chars": 8673,
            "chars_used": 8673,
            "status": "training",
            "created_at": "2023-05-28T16:09:58.085Z",
            "modified_at": "2023-05-30T01:57:20.604Z"
        }
    ]
}
Name Description
id The chatbot's ID
name The chatbot's name
public If the chatbot is public (required to use the widget)
Values: true, false
ai_tone The chatbot's AI tone
Values: casual, neutral, formal
ai_knowledge The chatbot's AI knwoledge
Values: source, source_then_internet, internet
ai_prompt The chatbot's AI custom prompt
files The chatbot's number of sources of type file
links The chatbot's number of sources of type link
texts The chatbot's number of sources of type text
chars The chatbot's total number of chars that were successfully trained
chars_used The chatbot's total number of chars of all the sources
status The chatbot's sources status
Values: training, trained, error, pending, null

Get a Chatbot

Retrieve a single chatbot.
GET/chatbots/:chatbot_id

Request

Name Description
chatbot_id The chatbot's ID Required

Response

{
    "result": "success",
    "data": {
        "id": "647557df9c5ec4dc99b5b352",
        "name": "Chatbot",
        "public": false,
        "ai_tone": "casual",
        "ai_knowledge": "source",
        "ai_prompt": "",
        "files": 3,
        "links": 4,
        "texts": 2,
        "chars": 37813,
        "chars_used": 37813,
        "status": "trained",
        "created_at": "2023-05-30T01:56:47.847Z",
        "modified_at": "2023-05-30T01:56:47.847Z"
    }
}
Name Description
id The chatbot's ID
name The chatbot's name
public If the chatbot is public (required to use the widget)
Values: true, false
ai_tone The chatbot's AI tone
Values: casual, neutral, formal
ai_knowledge The chatbot's AI knwoledge
Values: source, source_then_internet, internet
ai_prompt The chatbot's AI custom prompt
files The chatbot's number of sources of type file
links The chatbot's number of sources of type link
texts The chatbot's number of sources of type text
chars The chatbot's total number of chars that were successfully trained
chars_used The chatbot's total number of chars of all the sources
status The chatbot's sources status
Values: training, trained, error, pending, null

Update a Chatbot

Update the chatbot's name.
GET/chatbots/:chatbot_id

Request

{
    "name": "Chatbot"
}
Name Description
chatbot_id The chatbot's IDRequired
name The chatbot's name
public If the chatbot is public (required to use the widget)
Values: true, false
ai_tone The chatbot's AI tone
Values: casual, neutral, formal
ai_knowledge The chatbot's AI knwoledge
Values: source, source_then_internet, internet
ai_prompt The chatbot's AI custom prompt

Response

{
    "result": "success",
    "data": {
        "id": "647557df9c5ec4dc99b5b352",
        "name": "Chatbot",
        "public": false,
        "ai_tone": "casual",
        "ai_knowledge": "source",
        "ai_prompt": "",
        "files": 3,
        "links": 4,
        "texts": 2,
        "chars": 37813,
        "chars_used": 37813,
        "status": "trained",
        "created_at": "2023-05-30T01:56:47.847Z",
        "modified_at": "2023-05-30T01:56:47.847Z"
    }
}

Delete a Chatbot

Delete a chatbot and all associated chats and sources. This action is permanent.
DELETE/chatbots/:chatbot_id

Request

Name Description
chatbot_id The chatbot's IDRequired

Response

{
    "result": "success",
    "data": "Chatbot deleted successfully."
}

Add Sources

Add new sources to a chatbot.
POST/chatbots/:chatbot_id/sources

Request

{
    "sources": [
        {
            "content": "https://example.com/sitemap.xml",
            "type": "sitemap"
        },
        {
            "content": "https://example.com",
            "type": "website"
        },
        {
            "content": "https://example.com/about",
            "type": "link"
        },
        {
            "content": "Lorem ipsum sit dolor...",
            "type": "text",
            "name": "My text"
        },
        {
            "content": "https://example.com/document.pdf",
            "type": "file"
        }
    ]
}
Name Description
chatbot_id The chatbot's ID Required
sources The array of sources to be addedRequired
source.content The source contentRequired
• For type: file it is the URL to the file
• For type: text it is text itself
• For type: sitemap it is the URL to the sitemap
• For type: website it is the URL of the website to be scraped
• For type: link it is the single URL to be scraped
Supported files: pdf,json,csv,txt,doc/docx,epub
source.type The source typeRequired
Values: file, text, sitemap, website, link
source.name The text name (only if type: text)

Response

{
    "result": "success",
    "data": "Sources are being added and trained."
}

Note

New sources are added asynchronously as soon as their content is fetched. You can list the chatbot's sources to check their status.

List Sources

Retrieve a list of sources.
GET/chatbots/:chatbot_id/sources

Request

Name Description
chatbot_id The chatbot's ID Required
type The source's type
Values: link, file, text
status The source's status
Values: trained, training, error, pending

Response

{
    "result": "success",
    "data": [
        {
            "id": "6475c498c27f69ee88869393",
            "type": "link",
            "content": "https://example.com",
            "status": "training",
            "error": null,
            "chars": 941,
            "created_at": "2023-05-30T09:40:33.298Z",
            "modified_at": "2023-05-30T09:40:34.922Z"
        },
        {
            "id": "6475c498c27f69ee88869393",
            "type": "link",
            "content": "https://example.com",
            "status": "training",
            "error": null,
            "chars": 941,
            "created_at": "2023-05-30T09:40:33.298Z",
            "modified_at": "2023-05-30T09:40:34.922Z"
        },
        {
            "id": "6475c498c27f69ee88869393",
            "type": "file",
            "content": "document.pdf",
            "status": "error",
            "error": "chars_limit_error",
            "chars": 1523,
            "created_at": "2023-05-30T09:40:33.298Z",
            "modified_at": "2023-05-30T09:40:34.922Z"
        },
        {
            "id": "6475c491c27f69ee88869392",
            "type": "file",
            "content": "notes.txt",
            "status": "trained",
            "error": null,
            "chars": 453,
            "created_at": "2023-05-30T09:40:33.298Z",
            "modified_at": "2023-05-30T09:40:34.922Z"
        },
        {
            "id": "64755d8b1446f0ddddb595b6",
            "type": "text",
            "content": "Lorem ipsum, dolor sit amet consectetur adipisicing elit. Molestias dolorem non natus dicta at repudiandae magni...",
            "status": "trained",
            "error": null,
            "chars": 115,
            "created_at": "2023-05-30T09:40:33.298Z",
            "modified_at": "2023-05-30T09:40:34.922Z"
        }
    ]
}
Name Description
id The source's ID
type The source's type
Values: link, file, text
content The source's content
status The source's status
Values: trained, training, error, pending
error The source's error (only if status: error)
Values: chars_limit_error, url_scrape_error, file_read_error, unknown_error
chars The source's content number of characters

Retrain Sources

This method allows you to update the appearance of the widget as well as the rate limits.
PUT/chatbots/:chatbot_id/sources

Request

{
    "source_ids": [
        "6475c498c27f69ee88869393",
        "6475c498c27f69ee88869394"
    ]
}
Name Description
chatbot_id The chatbot's ID Required
source_ids The list of source IDs (if not provided all sources will be retrained)

Response

{
    "result": "success",
    "data": "Training started successfully."
}

Delete Sources

This method allows you to update the appearance of the widget as well as the rate limits.
DELETE/chatbots/:chatbot_id/sources

Request

{
    "source_ids": [
        "6475c498c27f69ee88869393",
        "6475c498c27f69ee88869394"
    ]
}
Name Description
chatbot_id The chatbot's ID Required
source_ids The list of source IDsRequired

Response

{
    "result": "success",
    "data": "Sources deleted successfully."
}

Create a Chat

Start a new conversation with a chatbot.
POST/chatbots/:chatbot_id/chats

Request

No parameters

Response

{
    "result": "success",
    "data": {
        "id": "6475c498c27f69ee88869393",
        "title": "New chat",
        "client": "api",
        "created_at": "2023-05-30T09:40:40.544Z",
        "modified_at": "2023-05-30T09:40:40.544Z",
        "messages": [
            {
                "id": "6475c498c27f69ee88869394",
                "message": "Hi! How can I help?",
                "links": [],
                "type": "message",
                "speaker": "bot",
                "created_at": "2023-05-30T09:40:40.549Z"
            }
        ]
    }
}

Errors

Code Message
MESSAGES_LIMIT_ERROR You have reached the messages limit for your current plan.

List Chats

Retrieve a list of chats.
GET/chatbots/:chatbot_id/chats

Request

Name Description
chatbot_id The chatbot's ID Required
start_date The start date filter
Format: YYYY-MM-DD
end_date The end date filter
Format: YYYY-MM-DD
client The chat's client filter
Values: api, widget, internal
search The search query filter

Response

{
    "result": "success",
    "data": [
        {
            "id": "6475c498c27f69ee88869393",
            "client": "internal",
            "title": "How does the website registration process work?",
            "messages": 4,
            "created_at": "2023-05-30T09:40:40.544Z",
            "modified_at": "2023-05-30T09:40:40.544Z"
        },
        {
            "id": "6475c498c27f69ee88869394",
            "client": "widget",
            "title": "What are the pricing plans available and their features?",
            "messages": 5,
            "created_at": "2023-05-30T09:40:40.544Z",
            "modified_at": "2023-05-30T09:40:40.544Z"
        },
        {
            "id": "6475c498c27f69ee88869395",
            "client": "widget",
            "title": "Can you explain the payment process on the website?",
            "messages": 2,
            "created_at": "2023-05-30T09:40:40.544Z",
            "modified_at": "2023-05-30T09:40:40.544Z"
        },
        {
            "id": "6475c498c27f69ee88869396",
            "client": "api",
            "title": "What is the refund policy for purchases made on the website?",
            "messages": 7,
            "created_at": "2023-05-30T09:40:40.544Z",
            "modified_at": "2023-05-30T09:40:40.544Z"
        }
    ]
}
Name Description
id The chat's ID
client The chat's client filter
Values: api, widget, internal
title The chat's title (the first user's prompt)
messages The chat's number of messages

Get a Chat

Retrieve a single chat.
GET/chatbots/:chatbot_id/chats/:chat_id

Request

Name Description
chatbot_id The chatbot's ID Required
chat_id The chat's IDRequired

Response

{
    "result": "success",
    "data": {
        "id": "6475c498c27f69ee88869393",
        "title": "What are the pricing plans available and their features?",
        "client": "internal",
        "created_at": "2023-05-30T09:40:40.544Z",
        "modified_at": "2023-05-30T09:40:40.544Z",
        "messages": [
            {
                "id": "6475c498c27f69ee88869394",
                "message": "Hi! How can I help?",
                "speaker": "bot",
                "created_at": "2023-05-30T09:40:40.549Z"
            },
            {
                "id": "6475c498c27f69ee88869396",
                "message": "What are the pricing plans available and their features?",
                "speaker": "human",
                "created_at": "2023-05-30T09:40:40.554Z"
            },
            {
                "id": "6475c498c27f69ee88869397",
                "message": "Our pricing plans include Basic ($9.99/mo), Standard ($19.99/mo), and Premium ($29.99/mo). Each plan offers different features to cater to various needs. For detailed information, please visit our website's pricing page.",
                "speaker": "bot",
                "created_at": "2023-05-30T09:40:40.564Z"
            }
        ]
    }
}
Name Description
chatbot_id The chatbot's ID Required
id The chat's ID
client The chat's client filter
Values: api, widget, internal
title The chat's title (the first user's prompt)
messages The list of messages
Array of [message]
message.id The message's ID
message.message The message's text (only if type: message)
message.speaker The message's speaker
Values: bot, human

Delete a Chat

Delete a chat. This action is permanent.
DELETE/chatbots/:chatbot_id/chats/:chat_id

Request

Name Description
chatbot_id The chatbot's ID Required
chat_id The chat's IDRequired

Response

{
    "result": "success",
    "data": "Chat deleted successfully."
}

Message with a Chat

Send a message to continue the conversation with a chat.
POST/chatbots/:chatbot_id/chats/:chat_id/messages

Request

{
    "prompt": "What are the pricing plans available?"
}
Name Description
chatbot_id The chatbot's ID Required
chat_id The chat's IDRequired
prompt The input message to generate a responseRequired

Response

{
    "result": "success",
    "data": {
        "response": "Our pricing plans include Basic ($9.99/mo), Standard ($19.99/mo), and Premium ($29.99/mo). Each plan offers different features to cater to various needs. For detailed information, please visit our website's pricing page.",
        "sources": [
            {
                "id": "64882ae15cf58c3d4f1151f4",
                "name": "pricing_info.pdf",
                "text": "Our pricing plans are designed to suit different needs and budgets. The Basic plan offers a great value at $9.99 per month, providing essential features for individuals and small businesses. The Standard plan, priced at $19.99 per month, includes additional features and is ideal for growing teams. For those seeking the ultimate experience, our Premium plan is available at $29.99 per month, offering all advanced features and priority support. Visit our website's pricing page for more information.",
                "score": 0.757822633,
                "page": 1
            },
            {
                "id": "64882ae15cf58c3d4f1151f5",
                "name": "https://example.com/pricing",
                "text": "To provide flexibility and options, we offer three pricing plans: Basic, Standard, and Premium. The Basic plan starts at $9.99 per month, providing essential features for individuals. The Standard plan, priced at $19.99 per month, offers additional features suitable for small to medium-sized businesses. Our Premium plan, available at $29.99 per month, provides access to all advanced features, priority support, and is perfect for enterprise-level organizations. Please visit our website's pricing page for more details on each plan.",
                "score": 0.740372658
            }
        ]
    }
}
Name Description
response The AI response
sources The list of sources that matched the prompt
source.id The sources's ID
source.name The source's name
source.text The text portion that matched the prompt
source.score The similarity score from 0 to 1
source.page The source's page (only for PDF files)

Errors

Code Message
MESSAGES_LIMIT_ERROR You have reached the messages limit for your current plan.
Email not received? Send again
Do you need help? Contact us
Change Plan

Update payment method