Change Log

2024-11-19

New endpoints
- POST /api/external/chatbot/vision: Conversation with chatbot by image

2024-08-22

Update endpoints
- POST /api/external/user/chatbot: Setup the chatbot with FormData on create
Fix
- PUT /api/external/user/chatbot/{chatbot_id}: Fix the url for HTTP Request

2024-07-30

New endpoints
- DELETE /api/external/chatbot/webhook
- DELETE /api/external/chatbot/training_data/{training_data_id}
- GET /api/external/chatbot/training_data
- GET /api/external/chatbot/event/{event_id}
Update endpoints
- POST /api/external/chatbot/training_data: response id and event_id
- POST /api/external/chatbot/model: response event_id
Update webhook messages

2024-07-05

New endpoints
- GET /api/external/chatbot/model/{model_id}
- GET /api/external/user/token/refresh
- GET /api/external/user/chatbot/{chatbot_id}
- PUT /api/external/user/chatbot/{chatbot_id}
- DELETE /api/external/user/chatbot/{chatbot_id}
- GET /api/external/user/plan
Update endpoints
- POST /api/external/chatbot/training_data: response id (for text) or event_id (crawler, upload file)
- PUT /api/external/chatbot/opentalk: remove parameter email
Remove endpoints
- PUT /api/external/chatbot: Use PUT /api/external/user/chatbot/{chatbot_id} instead

2024-06-28

New endpoints
- GET /api/external/user/chatbot
- POST /api/external/user/chatbot

2024-05-09

Authentication
- add caigunn-access-token for management
Move endpoints
- POST /api/external/chatbot/train --> /api/external/chatbot/models
- PATCH /api/external/chatbot/model_id --> /api/external/chatbot
- POST /api/external/chatbot/conversation --> /api/external/chatbot/talk
- GET /api/external/chatbot/conversation_uids --> /api/external/chatbot/uids
New endpoints
- PUT /api/external/chatbot/opentalk
- DELETE /api/external/chatbot/opentalk
- POST /api/external/chatbot/training_data
- PUT /api/external/chatbot/webhook

2024-01-31

New endpoint
- GET /api/external/chatbot/conversation_uids
Update endpoints
- POST /api/external/chatbot/conversation: add parameter nickname
- GET /api/external/chatbot/messages: add parameter nickname

2023-11-10

New endpoints
- POST /api/external/chatbot/train
- GET /api/external/chatbot/models
- PATCH /api/external/chatbot/model_id
- POST /api/external/chatbot/conversation
- GET /api/external/chatbot/messages

Introduction

Welcome to the CaiGunn API! You can use our API to setup and interact with chatbot.

We have language bindings in Shell and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

CaiGunn uses API keys to allow access to the API. You can register and create chatbot at CaiGunn.

CaiGunn API expects for the API key to be included in all API requests to the server in a header that looks like the following:

api-key: CHATBOT_API_KEY

For chatbot manangement APIs, CaiGunn Access Token is needed. Include it in header that looks like following:

caigunn-access-token: CAIGUNN_ACCESS_TOKEN

You must replace CHATBOT_API_KEY with your personal chatbot api key and CAIGUNN_ACCESS_TOKEN with your caigunn access token.

User

Refresh Caigunn Access Token

curl --location 'https://caigunn-api.ap-mic.com/api/external/user/token/refresh?expired_date=EXPIRED_DATE' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/user/token/refresh?expired_date=EXPIRED_DATE"

headers = {"caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "token": "string"
}

Refresh caigunn-access-token.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/user/token/refresh

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Query Parameters

Name	Type	Mandatory	Default	Description
expired_date	date	false

Get Plans

curl --location 'https://caigunn-api.ap-mic.com/api/external/user/plan?offset=OFFSET&limit=LIMIT' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/user/plan?offset=OFFSET&limit=LIMIT"

headers = {
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "plans": [
    {
      "title": "string",
      "id": "string",
      "crawler_limit": 0,
      "character_limit": 0,
      "training_limit": 0,
      "price": 0
    }
  ]
}

This endpoint retrieves all plans.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/user/plan

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Query Parameters

Name	Type	Mandatory	Default	Description
offset	integer	false	0
limit	integer	false	30

Create Chatbot

curl --location 'https://caigunn-api.ap-mic.com/api/external/user/chatbot' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --form 'title=TITLE' \
    --form 'plan_id=PLAN_ID'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/user/chatbot?title=TITLE&plan_id=PLAN_ID"

headers = {
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN
}

payload = {
    "title": TITLE,
    "plan_id": PLAN_ID,
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.json())

{
  "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "webchat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "api_key": "string",
  "expired_at": "2024-07-05T09:49:32.451Z"
}

Create Chatbot.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/user/chatbot

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Request Body FormData

Name	Type	Mandatory	Description
title	string	true
plan_id	uuid	true
avatar	file	false
main_color	string	false
is_default_visible	boolean	false
button_style	string	false	basic, image
button_image	file	false
initial_messages	array	false	[{"type":"text","value":"string"}]
is_fixed	bool	false
show_history	boolean	false
allowed_domains	array	false	["http://localhost", "https://caigunn.ap-mic.com"]
model_id	uuid	false
prompt	string	false
is_shared	boolean	false

Get All Chatbots

curl --location 'https://caigunn-api.ap-mic.com/api/external/user/chatbot' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/user/chatbot"

headers = {"caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "chatbots": [
    {
      "id": "string",
      "title": "string",
      "api_key": "string"
    }
  ]
}

This endpoint retrieves all chatbots.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/user/chatbot

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Query Parameters

Name	Type	Mandatory	Default	Description
offset	integer	false	0
limit	integer	false	30

Get Chatbot Info

curl --location 'https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID"

headers = {
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "updated_at": "2024-07-05T04:08:48.392Z",
  "created_at": "2024-07-05T04:08:48.392Z",
  "id": "string",
  "title": "string",
  "user_id": "string",
  "is_deleted": true,
  "deleted_at": "2024-07-05T04:08:48.392Z",
  "prompt": "string",
  "temperature": 0,
  "is_ready_for_train": true,
  "is_shared": true,
  "share_link": "string",
  "is_free": true,
  "training_data_type": "file",
  "file_model_id": "string",
  "crawler_model_id": "string",
  "text_model_id": "string",
  "usage_notification": 0,
  "message_limit": 0,
  "character_limit": 0,
  "crawler_limit": 0,
  "training_limit": 0,
  "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "period_start_at": "2024-07-05T04:08:48.392Z",
  "period_end_at": "2024-07-05T04:08:48.392Z",
  "api_key": "string",
  "total_file_size_limit": 0,
  "is_api_accessible": true,
  "model": {
    "id": "string",
    "model_name": "string",
    "embedding_name": "string"
  },
  "opentalk_device_id": "string",
  "opentalk_device_name": "string",
  "opentalk_device_type": "string",
  "bound_at": "2024-07-05T04:08:48.392Z",
  "opentalk_api_token": "string",
  "use_opentalk_conversation": false,
  "opentalk_account": "string",
  "opentalk_user_id": "string",
  "next_plan_id": "string",
  "limits_reset_day": 0,
  "coupon": {},
  "store_source_data": true,
  "is_prompt_template_accessible": true,
  "qa_generate_limit": 0,
  "qa_generate_count": 0,
  "preview_chunks": true,
  "is_chunks_editable": true,
  "opentalk_host": "string",
  "webhook_url": "string"
}

This endpoint retrieves detail information of the chatbot.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID

Path Parameters

Name	Type	Mandatory	Default	Description
chatbot-id	string	true		The ID of chatbot.

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Update Chatbot

curl --location --request PUT 'https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --form 'title=TITLE'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID"

payload = json.dumps({"title": TITLE})
headers = {
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.json())

{
  "detail": "update successfully"
}

Update chatbot settings

HTTP Request

PUT https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Request Body FormData

Name	Type	Mandatory	Description
title	string	false
avatar	file	false
main_color	string	false
is_default_visible	boolean	false
button_style	string	false	basic, image
button_image	file	false
initial_messages	array	false	[{"type":"text","value":"string"}]
is_fixed	bool	false
show_history	boolean	false
allowed_domains	array	false	["http://localhost", "https://caigunn.ap-mic.com"]
model_id	uuid	false
prompt	string	false
is_shared	boolean	false

Delete Chatbot

shell curl --location --request DELETE 'https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID"

headers = {
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
}

response = requests.request("DELETE", url, headers=headers)

print(response.json())

{
  "detail": "Delete chatbot successfully"
}

Delete Chatbot.

HTTP Request

DELETE https://caigunn-api.ap-mic.com/api/external/user/chatbot/CHATBOT_ID

Path Parameters

Name	Type	Mandatory	Default	Description
chatbot-id	string	true		The ID of chatbot.

Header Parameters

Name	Type	Mandatory	Default	Description
caigunn-access-token	string	true		Caigunn Access Token.

Bind Opentalk

Bind Opentalk Device

curl --location --request PUT 'https://caigunn-api.ap-mic.com/api/external/chatbot/opentalk' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{"device_id": OPENTALK_DEVICE_ID}'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/opentalk"

payload = json.dumps({"device_id": OPENTALK_DEVICE_ID})
headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "Content-Type": "application/json",
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.json())

{
  "detail": "Bind Opentalk successfully"
}

Bind with Opentalk to access device's conversation script, live chat support, and analytics features.

HTTP Request

PUT https://caigunn-api.ap-mic.com/api/external/chatbot/opentalk

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Request Body Schema

Name	Type	Mandatory	Default	Description
device_id	string	true		ID of the Opentalk device.

Unbind Opentalk Device

curl --location --request DELETE 'https://caigunn-api.ap-mic.com/api/external/chatbot/opentalk' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --header 'Content-Type: application/json'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/opentalk"

headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "Content-Type": "application/json"
}

response = requests.request("DELETE", url, headers=headers)

print(response.json())

{
  "detail": "Unbind Opentalk successfully"
}

Unbind Opentalk device.

HTTP Request

DELETE https://caigunn-api.ap-mic.com/api/external/chatbot/opentalk

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Model

Create Training Data

# Create by files
curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/training_data?type=file' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --form 'files=@FILE'

# Create by crawler
curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/training_data?type=crawler' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --form 'website="WEBSITE"' \
    --form 'is_single_page="IS_SINGLE_PAGE"'

# Create by text
curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/training_data?type=text' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --form 'text=TEXT'

# Create by files
import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/training_data?type=file"

payload = {"website": WEBSITE, "is_single_page": IS_SINGLE_PAGE}
files = []
headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.json())


# Create by crawler
import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/training_data?type=crawler"

payload = {"website": WEBSITE, "is_single_page": IS_SINGLE_PAGE}

headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

# Create by text

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/training_data?type=file"

payload = {'text': 'TEXT'}

headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

# Create by files
{
    "id": null,
    "event_id": "123e4567-e89b-12d3-a456-426655440000"
}

# Create by crawler
{
    "id": null,
    "event_id": "123e4567-e89b-12d3-a456-426655440000"
}

# Create by text
{
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "event_id": null
}

Create training data for model training. Create training data by crawler or uploading files will be processed in background and the result will be sent to the webhook.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/chatbot/training_data

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Query Parameters

Name	Type	Mandatory	Default	Description
type	string	true		file, crawler, text

Request Body Form data

Name	Type	Mandatory	Description
website	string	false	The website for crawling.
is_single_page	bool	false	Crawl one webpage or the whole website
text	string	false
files	array	false

Get Training Data

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/training_data' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/training_data"

headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "training_data": [
    {
      "title": "Plain Text",
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "type": "text"
    },
    {
      "title": "File Name",
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "type": "file"
    },
    {
      "title": "Website URL",
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "type": "crawler"
    }
  ]
}

List all training data which will be used in next training.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/training_data

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Delete Training Data

curl --location --request DELETE 'https://caigunn-api.ap-mic.com/api/external/chatbot/training_data/{TRAINING_DATA_ID}' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/training_data/{TRAINING_DATA_ID}"

headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("DELETE", url, headers=headers)

print(response.json())

{
  "detail": "Delete training data successfully"
}

Delete training data by id.

HTTP Request

DELETE https://caigunn-api.ap-mic.com/api/external/chatbot/training_data/TRAINING_DATA_ID

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Path Parameters

Name	Type	Mandatory	Default	Description
training_data_id	uuid	true		The ID of training data.

Train a Model

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/model' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{"title": TITLE, "model_name": MODEL_NAME}'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/model"

payload = json.dumps({"title": TITLE, "model_name": MODEL_NAME})
headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "Content-Type": "application/json",
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.json())

{
  "event_id": "123e4567-e89b-12d3-a456-426655440000"
}

Train a model. Result will be sent to the webhook.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/chatbot/model

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Request Body Schema

Name	Type	Mandatory	Default	Description
title	string	true		Title for the trained model.
model_name	string	false	"PaLM2"	"PaLM2", "gpt-3.5-turbo", "gpt-4", "Gemini", "Claude 2", "Claude 3", "CaiGunn001", "Gemini 1.5"

Get All Models

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/model' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/model"

headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "models": [
    {
      "title": "string",
      "id": "string",
      "updated_at": "2023-11-06T09:09:41.552Z",
      "created_at": "2023-11-06T09:09:41.552Z",
      "model_name": "chat-bison"
    }
  ]
}

This endpoint retrieves all models.

HTTP Request

GET http://caigunn-api.ap-mic.com/api/external/chatbot/model

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Get Model

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/model/MODEL_ID' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/model/MODEL_ID"

headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "title": "string",
  "id": "string",
  "updated_at": "2024-07-05T04:19:04.436Z",
  "created_at": "2024-07-05T04:19:04.436Z",
  "model_name": "string",
  "training_data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "string"
    }
  ]
}

This endpoint retrieves detail information of the chatbot.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/model/MODEL_ID

Path Parameters

Name	Type	Mandatory	Default	Description
model-id	string	true		ID of the model.

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Conversation

Talk With Chatbot

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/talk&nickname=NICKNAME' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --header 'uid: CUSTUM_UID' \
    --header 'Content-Type: application/json' \
    --data '{"text": TEXT}'

import requests
import json

url = "http://caigunn-api.ap-mic.com/api/external/chatbot/talk&nickname=NICKNAME"

payload = json.dumps({"text": TEXT})
headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "uid": CUSTUM_UID,
    "Content-Type": "application/json",
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.json())

{
  "text": "string"
}

Send message to chatbot and get response.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/chatbot/talk

Header Parameters

Name	Type	Mandatory	Description
api-key	string	true	API Key.
caigunn-access-token	string	true	Caigunn Access Token.
uid	string	true	Custom UID for identify conversation.

Query Parameters

Name	Type	Mandatory	Default	Description
nickname	string	false		Nickname of the conversation participant.

Request Body Schema

Name	Type	Mandatory	Default	Description
text	string	true		Message from the conversation participant.

Talk With Chatbot by image

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/vision?nickname=NICKNAME' \
  --header 'api-key: CHATBOT_API_KEY' \
  --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
  --header 'uid: CUSTUM_UID' \
  --form 'text=""' \
  --form 'image=@"/path/to/file"'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/vision?nickname=NICKNAME"

payload = {"text": ""}
files = [("image", ("file", open("/path/to/file", "rb"), "application/octet-stream"))]
headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "uid": CUSTUM_UID,
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

{
  "text": "string"
}

Send image to chatbot and get response.

HTTP Request

POST https://caigunn-api.ap-mic.com/api/external/chatbot/vision

Header Parameters

Name	Type	Mandatory	Description
api-key	string	true	API Key.
caigunn-access-token	string	true	Caigunn Access Token.
uid	string	true	Custom UID for identify conversation.

Query Parameters

Name	Type	Mandatory	Default	Description
nickname	string	false		Nickname of the conversation participant.

Request Body Form data

Name	Type	Mandatory	Default	Description
text	string	false		Message from the conversation participant.
image	file	true		.png, .jpg, .jpeg, .gif, .tiff, .tif

Get Conversation UIDs

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/uids?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT' \
    --header 'api-key: CHATBOT_API_KEY'
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/uids?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT"

headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "uid": CUSTUM_UID,
}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "uids": [
    {
      "uid": "string",
      "nickname": "string",
      "source": "string",
      "last_sent": "string",
      "last_sent_at": "string"
    }
  ]
}

This endpoint retrieves conversation UIDs.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/uids

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Query Parameters

Name	Type	Mandatory	Default	Description
offset	integer	false	0
limit	integer	false	30
start_at	datetime	false	1970-1-1	Get UIDs where last_sent_at is greater than or equal start_at.
end_at	datetime	false	current datetime	Get UIDs where last_sent_at is less than or equal end_at.

Get Historical Messages

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/messages?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT&nickname=NICKNAME' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --header 'uid: CUSTUM_UID'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/messages?offset=OFFSET&limit=LIMIT&start_at=START_AT&end_at=END_AT&nickname=NICKNAME"

headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "uid": CUSTUM_UID,
}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "messages": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "receive": "string",
      "send": "string",
      "type": "text",
      "id": "string",
      "log_type": "string",
      "kwargs": {}
    }
  ]
}

This endpoint retrieves historical messages from a conversation.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/messages

Header Parameters

Name	Type	Mandatory	Description
api-key	string	true	API Key.
caigunn-access-token	string	true	Caigunn Access Token.
uid	string	true	Custom UID for identify conversation.

Query Parameters

Name	Type	Mandatory	Default	Description
offset	integer	false	0
limit	integer	false	30
start_at	datetime	false
end_at	datetime	false
nickname	string	false		Nickname of the conversation participant.

Webhook

curl --location --request PUT 'https://caigunn-api.ap-mic.com/api/external/chatbot/webhook' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{"webhook_url": WEBHOOK_URL}'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/webhook"

payload = json.dumps({"webhook_url": WEBHOOK_URL})
headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN,
    "Content-Type": "application/json",
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.json())

{
  "detail": "Webhook url update successfully"
}

Set webhook url to subscribe chatbot events.

HTTP Request

PUT https://caigunn-api.ap-mic.com/api/external/chatbot/webhook

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Request Body Schema

Name	Type	Mandatory	Default	Description
webhook_url	string	true		Webhook url for chatbot event subscripiton.

Unsubscribe Webhook

curl --location --request DELETE 'https://caigunn-api.ap-mic.com/api/external/chatbot/webhook' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests
import json

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/webhook"

headers = {
    "api-key": CHATBOT_API_KEY,
    "caigunn-access-token": CAIGUNN_ACCESS_TOKEN
}

response = requests.request("DELETE", url, headers=headers)

print(response.json())

{
  "detail": "Unsubscribe webhook successfully"
}

Unsubscribe webhook.

HTTP Request

DELETE https://caigunn-api.ap-mic.com/api/external/chatbot/webhook

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Get Events by Event ID

curl --location 'https://caigunn-api.ap-mic.com/api/external/chatbot/event/{EVENT_ID}' \
    --header 'api-key: CHATBOT_API_KEY' \
    --header 'caigunn-access-token: CAIGUNN_ACCESS_TOKEN'

import requests

url = "https://caigunn-api.ap-mic.com/api/external/chatbot/event/{EVENT_ID}"

headers = {"api-key": CHATBOT_API_KEY, "caigunn-access-token": CAIGUNN_ACCESS_TOKEN}

response = requests.request("GET", url, headers=headers)

print(response.json())

{
  "webhook_logs": [
    {
      "created_at": "2024-07-30T07:48:56.065248Z",
      "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "event": "crawling",
      "status": "initial",
      "data": {
        "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "broadcast_status": "completed"
    },
    {
      "created_at": "2024-07-30T07:50:03.500039Z",
      "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "event": "crawling",
      "status": "completed",
      "data": {
        "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "training_data_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
      },
      "broadcast_status": "completed"
    }
  ]
}

List all training data which will be used in next training.

HTTP Request

GET https://caigunn-api.ap-mic.com/api/external/chatbot/event/{EVENT_ID}

Header Parameters

Name	Type	Mandatory	Default	Description
api-key	string	true		API Key.
caigunn-access-token	string	true		Caigunn Access Token.

Path Parameters

Name	Type	Mandatory	Default	Description
event_id	uuid	true		Event ID.

Webhook Events

crawling.initial

{
  "event": "crawling",
  "status": "initial",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

crawling.completed

{
  "event": "crawling",
  "status": "completed",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "training_data_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}

uploading.initial

{
  "event": "uploading",
  "status": "initial",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

uploading.completed

{
  "event": "uploading",
  "status": "completed",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "training_data_ids": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "filename": "filename"
      },
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "filename": "filename",
        "status": "failed",
        "detail": "Unsupport file format"
      }
    ]
  }
}

uploading.failed

{
  "event": "uploading",
  "status": "failed",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

training.initial

{
  "event": "training",
  "status": "initial",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

training.completed

{
  "event": "training",
  "status": "completed",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "training_data_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}

training.failed

Detail
Training data not found
Character limit exceeded

{
  "event": "training",
  "status": "failed",
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "detail": ""
  }
}

Errors

The CaiGunn API uses the following error codes:

Error Code	Meaning
400	Bad Request.
401	Unauthorized.
403	Forbidden.
404	Not Found.
405	Method Not Allowed.
406	Not Acceptable.
500	Internal Server Error.
503	Service Unavailable.