API

We're adding API as a channel, so users can use the chatbot logic built on ChatAIBot but utilize their own custom-made chat widget / launcher.

Why is this helpful?

• You have a better chat widget UI

• You want to manage chatbots on multiple domains

Following are the steps to use API as a channel:

Step 1: Build your chatbot flow

1. Goto Bot builder > Choose "API" as channel

2. Build your conversation flow

3. Hit "Deploy" to publish your version

Step 2: Configure ChatAIBot's APIs

You would need to invoke 2 APIs to facilitate the chat between the chatbot built on ChatAIBot and your system.

1. Start conversation - To initiate the conversation and create a thread.

2. Send visitor message - To send the visitor's reply to a message for ChatAIBot to process and goto the next step in the chat flow.

With this your system will be able to smoothly interact with the chatbot built on ChatAIBot.

Start conversation

POST https://app.chataibot.io/api/v1/conversations

Initiates a chat session with a visitor. Make sure you use this API for unique visitors.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Copy

{
  "channel": "API",
  "message": {
    "data": {
      "body": "Hello" // user message
    },
    "type": "text"
  },
  "variables": { // variables are optional to send
    "system": { 
      "timezone": "Asia/Calcutta",
      "referrerUrl": "https://chataibot.io",
      "browserLanguage": "en-GB"
    },
    "contact": {
      "name": "User Name",
      "email": "[e-mail]",
      "phone": "1234567890"
    },
    "conversation": {
      "variable": "value"
    }
  },
  "bot_key": "<bot_key>", // found on the trigger block
  "from": {
    "user_external_id": "<visitor_id>", // mandatory to define a unique visitor id
    "type": "VISITOR"
  }
}

Response

200

{
    "ok": true,
    "conversation": {
        "id": "<conversation_id>",
        "created_at": "2025-02-10 20:21:03.913000",
        "assignee": {
            "id": "<bot_user_id>",
            "to": "<bot_user_email>"
        }
    },
    "contact": {
        "name": "User Name",
        "email": "[e-mail]",
        "phone": "9999999999",
        "visitor_key": "<visitor_id>_<account_id>"
    }
}

400

{
    "ok": true,
    "conversation": {
        "id": "<conversation_id>",
        "created_at": "2025-02-10 20:21:03.913000",
        "assignee": {
            "id": "<bot_user_id>",
            "to": "<bot_user_email>"
        }
    },
    "contact": {
        "name": "User Name",
        "email": "[e-mail]",
        "phone": "9999999999",
        "visitor_key": "<visitor_id>_<account_id>"
    }
}

401

{
  "ok": false,
  "error": "JWT_SIGNATURE_EXCEPTION",
  "code": "JWT_SIGNATURE_EXCEPTION",
  "message": "Invalid JWT token",
  "status": 401
}

Send visitor response

POST https://app.chataibot.io/api/v1/conversation/<conversation_id>/messages

Send all visitor responses received at your systems to ChatAIBot using this API.

After receiving it, ChatAIBot will process the visitor message as per the chatbot flow and provide the chatbot response.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Text

{
  "message": {
    "data": {
      "body": "Hello" // visitor's message
    },
    "type": "text" 
  },
  "user": {
    "type": "VISITOR"
  }
}

Button

{
  "message": {
    "data": {
      "body": "Button 1",
      "callback": "",
      "next_dialog": "5",
      "key": "4"
    },
    "type": "button.response"
  },
  "user": {
    "type": "VISITOR"
  }
}

Multi-button

{
  "message": {
    "data": {
      "body": "Button 1",
      "callback": "",
      "next_dialog": "4",
      "key": "3",
      "selected_button_index": [
        "Button 1__0"
      ]
    },
    "type": "button.response"
  },
  "user": {
    "type": "VISITOR"
  }
}

Slider

{
  "message": {
    "type": "slider.response",
    "data": {
      "body": "30",
      "value": 30,
      "callback": null
    }
  },
  "user": {
    "type": "VISITOR"
  }
}

File Upload

{
  "message": {
    "type": "file_upload.response",
    "data": {
      "files": [
        {
          "filename": "7df2d331_foo.png",
          "link": "https://wotnot.io/images/7df2d331_foo.png",
          "mime_type": "image/png",
          "extension": "png"
        },
        {
          "filename": "7df2d338_bar.png",
          "link": "https://wotnot.io/images/7df2d331_bar.png",
          "mime_type": "image/png",
          "extension": "png"
        }
      ]
    }
  },
  "user": {
    "type": "VISITOR"
  }
}

Javascript

{
  "message": {
    "type": "javascript.response",
    "data": {
      "variables": {
        "contact_variables": [
          {
            "name": "name",
            "value": "John"
          }
        ],
        "non_contact_variables": [
          {
            "name": "ans",
            "value": "2"
          }
        ]
      }
    }
  },
  "user": {
    "type": "VISITOR"
  }
}

Response

200

{
  "ok": true,
  "message_id": "6HRBshHEcV8P103039226478taGDJQxC"
}

400

{
  "error": "Invalid request"
}

401