# Chatbot Endpoints

# Get Chatbot

The "Get Chatbot" endpoint serves as a key resource for retrieving detailed information about a specific chatbot within your Karabo.ai portfolio. By utilizing this endpoint, you can access comprehensive data about your chatbot's configuration, usage, and integration details. This information is crucial for managing and optimizing your chatbot's performance and user interaction on your platform.

Endpoint: GET https://karabo.ai/api/v1.0/chatbot-get/<str:uniqueId>/

This endpoint requires the unique identifier (uniqueId) of your chatbot, ensuring that you receive tailored information corresponding to the specified chatbot.

# Response Structure

Upon a successful request, the API returns a structured response containing the following chatbot details:

Chatbot Name: The name you have assigned to your chatbot.
Chatbot Type: The type or category your chatbot falls under, based on its intended use or functionality.
Chatbot Title: The title of your chatbot, typically displayed in the chat window or greeting.
Chatbot Greeting: The initial message or greeting presented by the chatbot to users.
Chatbot Instructions: Specific instructions or guidance provided by the chatbot to assist users in interacting with it.
Conversation Count: The total number of conversations handled by the chatbot up to the current date.
User Allowance: The maximum number of messages each user is allowed to prevent abuse.
Available Word Count: The remaining word count available to add training material to your chatbot. This number equals the chatbot training allowance minus number of words already used in training.
Reset Date: The date when conversation counts and word limits will reset, typically aligned with your billing cycle.
Embed Code: A pre-formatted HTML snippet for embedding your chatbot into a website. This code includes links to necessary CSS and JavaScript files for the chatbot's visual and functional integration.

Succesful response:

{
  "chatbot_name": "HelpDesk Bot",
  "chatbot_type": "Customer Support",
  "chatbot_greeting": "Hi there! How can I assist you today?",
  "chatbot_instructions": "Type your question, and I'll do my best to help.",
  "conversation_count": 450,
  "user_allowance": 100,
  "available_word_count": 100000,
  "chatbot_color1": "#123456",
  "chatbot_color2": "#123456",
  "reset_date": "2024-12-01",
  "embed_code": "<script src='https://cdn.jsdelivr.net/npm/marked@3.0.7/marked.min.js' defer></script><link rel='stylesheet' href='chatbot_css_file_url'><script src='chatbot_js_file_url' defer></script>"
}

# Edit Chatbot

The "Edit Chatbot" endpoint is a critical feature designed for users who wish to update the settings and appearance of their existing chatbots on the Karabo.ai platform. This endpoint facilitates the modification of various chatbot attributes, ensuring that your chatbot remains aligned with your evolving preferences, branding guidelines, and interaction requirements.

Endpoint: POST https://karabo.ai/api/v1.0/chatbot-edit/<str:uniqueId>/

To modify a specific chatbot, the endpoint requires the unique identifier (uniqueId) of the chatbot you intend to update. This identifier ensures precise targeting and modification of the chatbot settings.

# Required Parameters

To update your chatbot, you can provide the following information in the request body:

TIP

You can provide only the variables you want to update, anything you enter will be updated to the value you provided. To leave other variables unchanged, do not include them in the request.

chatbot_name: The new name for your chatbot.
chatbot_greeting: The initial message users receive when starting a conversation with the chatbot.
chatbot_instructions: Instructions or help messages guiding users on how to interact with the chatbot.
user_allowance: The maximum number of messages a single user is permitted to send to the chatbot within a day. This helps prevent abuse and ensures fair usage (Integer value).
chatbot_color1: A primary color for the chatbot, specified in hexadecimal format (e.g., #ffffff).
chatbot_color2: A secondary color for the chatbot, also in hexadecimal format and serving to complement or contrast the primary color.

Example request:

{
  "chatbot_name": "InfoDesk Bot",
  "chatbot_greeting": "Welcome to our InfoDesk.",
  "chatbot_instructions": "You can ask me any questions about our services.",
  "user_allowance": 100,
  "chatbot_color1": "#123456",
  "chatbot_color2": "#654321"
}

Successful response:

{
  "response": "Data updated successfully"
}

# Manage Documents

Enhancing your chatbot's knowledge base is essential for improving its accuracy, responsiveness, and overall utility. The "Add Documents" endpoint is specifically designed for this purpose, allowing you to upload new PDF documents that expand the information reservoir your chatbot draws from during interactions.

# Add Documents to Chatbot

Endpoint: POST https://karabo.ai/api/v1.0/chatbot-document-add/<str:uniqueId>/

This endpoint targets a specific chatbot identified by its unique identifier (uniqueId). By supplying new documents, you contribute directly to the chatbot's learning and adaptability.

This endpoint supports the simultaneous addition of multiple documents at the same time, enhancing the efficiency of updating your chatbot's knowledge base. All documents must be in PDF format.

Example Request For this we will use postman.

Authentication - Ensure you have entered your Token correctly in the Authentication Header of the request
Uploading the documents Add all your PDFs at once (4 files added in this example). Note the URL and you should receive the success response shown below if the request is successful.

Uploading Documents to Chatbots

Success response:

{
  "message": "Documents added successfully."
}

TIP

If you get a server error with uploading documents you can try:

Upload fewer documents at a time
Compress PDFs to reduce the file size

# View Chatbot Documents

This endpoint allows you to View all the available documents that a chatbot has for training. Again note this is only valid for Knowledge and Business Enquiries type chatbots.

Example Request

Endpoint: GET https://karabo.ai/api/v1.0/chatbot-document-view/<str:uniqueId>/

curl -X GET "https://karabo.ai/api/v1.0/chatbot-document-view/uniqueId123/" -H "Authorization: Token {access_token}"

Success Response If you made a successful request, you will receive document records in this format:

{
    "response": "success",
    "documents": [
        {
            "title": "Document Title 1",
            "file": "https://example.com/path/to/document1.pdf",
            "word_count": 1500,
            "text": "Preview of the document content...",
            "document_id": "doc1uniqueId"
        },
        {
            "title": "Document Title 2",
            "file": "https://example.com/path/to/document2.pdf",
            "word_count": 3000,
            "text": "Preview of the document content...",
            "document_id": "doc2uniqueId"
        }
    ]
}

If the chatbot has no documents, you will receive the following response:

{
    "response": "success",
    "documents": []
}

# Delete a Chatbot Document

This endpoint facilitates the deletion of a specific document from a chatbot's training material set. It is only accessible for chatbots categorized under "Knowledge Retrieval" or "Business Enquiries".

Endpoint: POST https://karabo.ai/api/v1.0/chatbot-document-delete/{uniqueId}/

Method : POST

Auth required : YES

Permissions required : User must have an active subscription linked to their profile.

Path Parameters

uniqueId (string): Unique identifier for the Chatbot from which a document is to be deleted.

Example Request

{
    "document_id": "string"
}

Success Response Condition : If everything is OK and the document is successfully deleted.

Code : 200 OK

{
    "response": "Document deleted successfully."
}

Error Responses Condition : If there is no active subscription associated with the user's profile.

Code : 400 BAD REQUEST

Content :

{
    "error": "You need an active subscription to access this API, please use create_subscription endpoint to get a subscription."
}

Condition : If the requested chatbot is not found or does not match the specified types.

Code : 400 BAD REQUEST

Content :

{
    "error": "Can only manage documents for Knowledge Retrieval or Business Enquiries Chatbots."
}

Condition : If the document ID provided does not exist or does not belong to the specified chatbot.

Code : 404 NOT FOUND

Content :

{
    "error": "Document with ID: {document_id} not found."
}

Condition : If the user does not have permission to delete the document.

Code : 403 FORBIDDEN

Content :

{
    "error": "Access Denied"
}

curl -X POST "https://karabo.ai/api/v1.0/chatbot-document-delete/uniqueId123/" -H "Authorization: Token {access_token}" -H "Content-Type: application/json" -d '{"document_id":"doc123uniqueId"}'

# Manage Links

In an effort to continuously refine and enhance your chatbot's knowledge and response capabilities, Karabo.ai introduces the "Add Links" endpoint. This feature allows you to integrate web-based resources directly into your chatbot's training regimen. By submitting URLs, you enable the platform to scrape data from these web pages, which is then assimilated into your chatbot's training materials, enriching its understanding and response accuracy.

# Add New Link

Use the following end-point to add a new link to an existing chatbot.

Endpoint: POST https://karabo.ai/api/v1.0/chatbot-link-add/<str:uniqueId>/

This endpoint is designed to target a specific chatbot identified by its uniqueId. It facilitates the direct addition of web links to the chatbot’s knowledge base, significantly expanding its learning resources.

To enhance your chatbot's knowledge base with information from the internet, you can submit a list of URLs. The content from these links will be extracted and used to train your chatbot, providing it with a broader range of information and improving its ability to assist users more effectively.

Links: A list of URLs (links) that you want to add to your chatbot's training material. These should be valid web addresses leading to content that is relevant and beneficial for your chatbot’s learning and interaction capabilities.

Example Request

When you wish to add new sources of information to your chatbot's training material, simply compile a list of URLs and send them through the specified endpoint. Here's how you can structure your request:

{
  "links": ["https://google.com", "https://facebook.com"]
}

Success response: Upon successful submission and processing of the URLs, the system initiates the data scraping process to extract relevant information from the provided links. This data is then systematically integrated into your chatbot's training materials.

{
  "message": "Links queued, if there is enough allowance, they will be added and your chatbot will be retrained, you can see in the dashboard if links were added."
}

TIP

Links are queued for processing rather than being processed instantly due to the time required for processing. Therefore, please revisit the dashboard after a few minutes to verify if the links have been successfully added.

# View Chatbot Links

This endpoint allows you to view all the links associated with a chatbot, specifically tailored for chatbots of the "Knowledge Retrieval" or "Business Enquiries" types. Access to this endpoint requires an active subscription.

Endpoint URL: GET https://karabo.ai/api/v1.0/chatbot-link-view/{uniqueId}/

Method : GET

Auth required : YES

Permissions required : User must have an active subscription linked to their profile.

Path Parameters

uniqueId (string): Unique identifier for the Chatbot whose links are to be retrieved. Provide the uniqueId in the URL path.

Success Response Condition : If everything is OK and the chatbot exists.

Code : 200 OK

Content example

{
    "response": "success",
    "links": [
        {
            "title": "Link Title 1",
            "link": "https://example.com/link1",
            "word_count": 1500,
            "text": "Preview of the content associated with the link...",
            "link_id": "link1uniqueId"
        },
        {
            "title": "Link Title 2",
            "link": "https://example.com/link2",
            "word_count": 3000,
            "text": "Preview of the content associated with the link...",
            "link_id": "link2uniqueId"
        }
    ]
}

Error Responses Condition : If there is no active subscription associated with the user's profile.

Code : 400 BAD REQUEST

Content :

{
    "error": "You need an active subscription to access API, please use create_subscription endpoint to get a subscription."
}

Condition : If the requested chatbot is not found.

Code : 404 NOT FOUND

Content :

{
    "error": "Chatbot not found."
}

Condition : If the chatbot type is neither 'Knowledge Retrieval' nor 'Business Enquiries'.

Code : 400 BAD REQUEST

Content :

{
    "error": "Can only add links to Knowledge Retrieval or Business Enquiries Chatbots."
}

Sample Call

curl -X GET "https://karabo.ai/api/v1.0/chatbot-link-view/uniqueId123/" -H "Authorization: Token {access_token}"

# Delete Chatbot Link

This endpoint facilitates the deletion of a specific link from a chatbot's resources. It is restricted to chatbots categorized under "Knowledge Retrieval" or "Business Enquiries" types. An active subscription is required to access this functionality.

Endpoint URL: POST https://karabo.ai/api/v1.0/chatbot-link-delete/{uniqueId}/

Method : POST

Auth required : YES

Permissions required : User must have an active subscription linked to their profile.

Path Parameters

uniqueId (string): Unique identifier for the Chatbot from which a link is to be deleted.

Data constraints

Provide the link_id in the JSON payload.

Data example All fields must be sent.

{
    "link_id": "link123uniqueId"
}

Success Response Condition : If everything is OK and the link is successfully deleted.

Code : 200 OK

Content example

{
    "response": "Link deleted successfully."
}

Error Responses Condition : If there is no active subscription associated with the user's profile.

Code : 400 BAD REQUEST

Content :

{
    "error": "You need an active subscription to access API, please use create_subscription endpoint to get a subscription."
}

Condition : If the requested chatbot is not found or is not eligible under specified types.

Code : 404 NOT FOUND

Content :

{
    "error": "Chatbot not found."
}

Condition : If the chatbot type is inappropriate for link management.

Code : 400 BAD REQUEST

Content :

{
    "error": "Can only add links to Knowledge Retrieval or Business Enquiries Chatbots."
}

Condition : If the link ID provided does not exist or does not belong to the specified chatbot.

Code : 404 NOT FOUND

Content :

{
    "error": "Link with ID: {link_id} not found."
}

Condition : If the user does not have permission to delete the link.

Code : 403 FORBIDDEN

Content :

{
    "error": "Access Denied"
}

Sample Call

curl -X POST "https://karabo.ai/api/v1.0/chatbot-link-delete/uniqueId123/" -H "Authorization: Token {access_token}" -H "Content-Type: application/json" -d '{"link_id":"link123uniqueId"}'

# Manage Calendars

This endpoint is tailored for adding new calendars to an existing Appointment/Calendar Support Chatbot. It allows users with an active subscription to dynamically expand their chatbot's scheduling capabilities by incorporating additional calendars. Each request is authenticated and validated to ensure secure and appropriate access.

TIP

This endpoint only works for Appointment/Calendar Support Chatbot types.

# Create New Calendar

POST to https://karabo.ai/api/v1.0/chatbot-calendar-add/<str:uniqueId>/

Authentication

Token Authentication: Users must provide a valid token obtained through the authentication process.
Permissions: Only users with an authenticated state are permitted to access this endpoint.

Request Parameters

uniqueId: The unique identifier of the ChatBot to which calendars are being added. This ID should be included in the URL path.
calendar_data: A list of calendar objects to be added.

{
  "calendar_data": [
    {
      "calendar_name": "Facial Treatments by Maria",
      "calendar_email": "maria@serenitybeautyspa.com",
      "daily_start": "09:00 AM",
      "daily_end": "06:00 PM",
      "local_timezone": "America/New_York",
      "description": "Book your rejuvenating facial treatment with Maria, our skincare expert.",
      "include_weekends": false,
      "min15App": false,
      "min30App": true,
      "min45App": true,
      "min60App": true
    },
    {
      "calendar_name": "Massage Therapy with Alex",
      "calendar_email": "alex@serenitybeautyspa.com",
      "daily_start": "10:00 AM",
      "daily_end": "07:00 PM",
      "local_timezone": "America/New_York",
      "description": "Experience relaxation like never before with a therapeutic massage from Alex.",
      "include_weekends": true,
      "min15App": false,
      "min30App": false,
      "min45App": false,
      "min60App": true
    },
    {
      "calendar_name": "Nail Services by Chris",
      "calendar_email": "chris@serenitybeautyspa.com",
      "daily_start": "08:00 AM",
      "daily_end": "05:00 PM",
      "local_timezone": "America/New_York",
      "description": "Get the perfect manicure and pedicure from Chris, our nail care specialist.",
      "include_weekends": true,
      "min15App": true,
      "min30App": true,
      "min45App": true,
      "min60App": true
    }
  ]
}

Responses

200 OK: Successfully added the specified calendars to the chatbot.

{
  "message": "Calendars were added to the chatbot, users can immediately see the new calendars."
}

400 Bad Request: The request is malformed or lacks necessary information.

If the user does not have an active subscription:

{
  "error": "You need an active subscription to access this API, please use the create_subscription endpoint to get a subscription."
}

If the specified chatbot is not found or does not support appointments/calendars:

{
  "error": "Can only add Calendars to Appointment/Calendar Support Chatbots"
}

If the calendar_data is missing or invalid:

{
  "error": "Must include calendar_data in the request, read the documentation for more information."
}

If the user has reached the maximum number of calendars:

{
  "error": "You have reached your maximum calendar limit."
}

404 Not Found: The specified chatbot does not exist.
```
{
  "error": "Chatbot not found."
}
```

Important Notes

Users are limited to adding a maximum of 10 calendars per chatbot. The system automatically calculates the available number of calendars that can be added based on the existing count.
It's crucial to ensure the calendar_data provided in the request matches the required data structure to prevent request rejections.
This endpoint is accessible only to users with an active subscription and authenticated state.

# View Chatbot Calendars

This endpoint provides access to view all the calendar settings associated with a chatbot that is categorized specifically for "Appointment/Calendar Support".

Endpoint URL: GET https://karabo.ai/api/v1.0/chatbot-calendar-view/{uniqueId}/

Method : GET

Auth required : YES

Permissions required : User must have an active subscription linked to their profile.

Path Parameters

uniqueId (string): Unique identifier for the Chatbot whose calendar settings are to be retrieved.

Success Response Condition : If everything is OK and the chatbot exists with the appropriate type.

Code : 200 OK

Content example

{
    "response": "success",
    "calendar_list": [
        {
            "name": "Main Office Calendar",
            "calendar_email": "office@example.com",
            "daily_start": "09:00",
            "daily_end": "17:00",
            "include_weekends": false,
            "local_timezone": "EST",
            "description": "Main office calendar for scheduling appointments.",
            "min15App": true,
            "min30App": true,
            "min45App": false,
            "min60App": true
        }
    ]
}

Error Responses Condition : If there is no active subscription associated with the user's profile or if the profile is not found.

Code : 400 BAD REQUEST

Content :

{
    "error": "You need an active subscription to access this API, please use create_subscription endpoint to get a subscription."
}

Condition : If the requested chatbot is not found or the chatbot type is not supported for this operation.

Code : 400 BAD REQUEST

Content :

{
    "error": "Can only view calendars of Appointment/Calendar Support Chatbots."
}

Condition : If the chatbot is not found.

Code : 404 NOT FOUND

Content :

{
    "error": "Chatbot not found."
}

Sample Call

curl -X GET "https://karabo.ai/api/v1.0/chatbot-calendar-view/uniqueId123/" -H "Authorization: Token {access_token}"

# Delete a Chatbot Calendar

This endpoint facilitates the deletion of a specific calendar from a chatbot's scheduling system, designated specifically for chatbots categorized under "Appointment/Calendar Support".

Full Endpoint: POST https://karabo.ai/api/v1.0/chatbot-calendar-delete/{uniqueId}/

Method : POST

Auth required : YES

Permissions required : User must have an active subscription linked to their profile.

Path Parameters

uniqueId (string): Unique identifier for the Chatbot from which a calendar is to be deleted.

Data constraints

Provide the calendar_id in the JSON payload.

Data example All fields must be sent.

{
    "calendar_id": "cal123uniqueId"
}

Success Response Condition : If everything is OK and the calendar is successfully deleted.

Code : 200 OK

Content example

{
    "response": "Calendar deleted successfully."
}

Error Responses Condition : If there is no active subscription associated with the user's profile.

Code : 400 BAD REQUEST

Content :

{
    "error": "You need an active subscription to access this API, please use create_subscription endpoint to get a subscription."
}

Condition : If the requested chatbot is not found or is not of the appropriate type.

Code : 400 BAD REQUEST

Content :

{
    "error": "Can only manage calendars for Appointment/Calendar Support Chatbots."
}

Condition : If the calendar ID provided does not exist or does not belong to the specified chatbot.

Code : 404 NOT FOUND

Content :

{
    "error": "Calendar with ID: calendar_id not found."
}

Condition : If the user does not have permission to delete the calendar.

Code : 403 FORBIDDEN

Content :

{
    "error": "Access Denied"
}

Sample Call

curl -X POST "https://karabo.ai/api/v1.0/chatbot-calendar-delete/uniqueId123/" -H "Authorization: Bearer {access_token}" -H "Content-Type: application/json" -d '{"calendar_id":"cal123uniqueId"}'

← Profile Data