Start Conversation

First, you need to create a conversation ID using the "Create Conversation" API. Then send messages to that conversation using the "Send Message" API to complete the conversation process.

Create Conversation

Used to request and get a conversation ID. The conversation ID is the basic carrier for users to chat with the Bot. Capabilities like chat history, long-term memory, and short-term memory are all based on the conversation ID.

Request Method

POST

Request URL

https://api.gptbots.ai/v1/conversation

Request Authentication

See Overview for authentication details.

Request

Request Example

curl -X POST https://api.gptbots.ai/v1/conversation \
  -H 'Authorization: Bearer your_apikey' \
  -H 'Content-Type: application/json' \
  -d '{
        "user_id": "123456789"
}'

Request Headers

Field	Type	Description
Authorization	Bearer ${token}	Use Authorization: Bearer ${token} for authentication. Get the key from the API Keys page as token.
Content-Type	application/json	Data type, set to application/json.

Request Body

Field	Type	Required	Description
user_id	string	Yes	User ID defined by developer to uniquely identify a user in the Bot.

Response

Response Example

{
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2" 
}

Success Response

Field	Type	Description
conversation_id	string	Conversation identifier.

Failure Response

Field	Type	Description
code	int	Error code.
message	string	Error details.

Error Codes

Code	Message
40000	Parameter error
40127	Developer authentication failed

Send Message

Send a message to the specified conversation ID and get the bot response message.

Request Method

POST

Request URL

https://api.gptbots.ai/v1/conversation/message

Request Authentication

See Overview for authentication details.

Request

Example Request

curl -X POST https://api.gptbots.ai/v1/conversation/message \
  -H 'Authorization: Bearer your_apikey' \
  -H 'Content-Type: application/json' \
  -d '{
        "user_id": "123456", 
        "text": "Hello!",
        "conversation_id": "xxxxxx",
        "response_mode": "streaming"
}'

Request Headers

Field	Type	Description
Authorization	Bearer ${token}	Use Authorization: Bearer ${token} for authentication. Get the key from the API Keys page as token.
Content-Type	application/json	Data type, set to application/json.

Request Body

Field	Type	Required	Description
user_id	string	Yes	User ID, defined by developer to uniquely identify a user in the bot.
text	string	Yes	User's question text, cannot exceed max length limit configured in bot.
conversation_id	string	Yes	Conversation ID, pass in to continue previous conversation.
response_mode	string	Yes	blocking: Blocking, wait for completion before returning result. (Long requests may be interrupted) streaming: Streaming response, based on SSE (Server-Sent Events).

Response

Example Response

{
  "message_id": "059f87d9-15c0-473a-870c-fde95cdcc1e4",
  "message_type": "ANSWER",
  "text": "Hi, is there anything I can help you?",
  "correlate_dataset": [
    {
      "data_id": "64ba14b0e62000708d1ee6ae",
      "data_name": "Document Name" 
    }
  ],
  "next_question": [
    "Need any help?",
    "Any questions?",
    "Anything else I can do for you?"
  ],
  "flow_output": [
    {
      "content": "Hello",
      "branch": "1", 
      "from_component_name": "User Input"
    }
  ],
  "create_time": 1679587005,
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2"
}

Success Response (Blocking)

Field	Type	Description
message_id	string	Unique message ID.
message_type	string	Message type, value: ANSWER, QUESTION.
text	string	Reply text.
next_question	array	System suggested next questions for user. Empty if disabled, no result, or error.
correlate_dataset	JSON Array	Knowledge documents referenced in reply.
- data_id	string	Knowledge document ID.
- data_name	string	Knowledge document name.
flow_output	JSON Array	flow bot reply content.
- content	string	flow bot component reply text.
- branch	string	flow bot branch.
- from_component_name	string	flow bot upstream component name.
create_time	int	Timestamp when reply message was created.
conversation_id	string	Conversation ID.

Success Response (Streaming)

Field	Type	Description
code	int	Message type code, 1-Knowledge, 3-Text, 7-NextQuestion, 10-FlowOutput, 0-End.
message	string	Message type, value: CorrelateDataset, Text, NextQuestion, FlowOutput, End.
data	object	Reply content.

Streaming data is returned in multiple chunks:

{"code":1,"message":"CorrelateDataset","data":[{"dataId":"64ba14b0e62000708d1ee6ae","dataName":"Document Name"}]}
{"code":3,"message":"Text","data":"I"}
{"code":3,"message":"Text","data":"can"}  
{"code":3,"message":"Text","data":"help"}
{"code":3,"message":"Text","data":"you"}
{"code":3,"message":"Text","data":"?"}
{"code":7,"message":"NextQuestion","data":["Need any help?","Any questions?","Anything else I can do for you?"]}
{"code":10,"message":"FlowOutput","data":[{"content":"Hello","branch":null,"from_component_name":"User Input"}]}
{"code":0,"message":"End","data":null}

Failure Response

Field	Type	Description
code	int	Error code.
message	string	Error details.

Error Codes

Code	Message
40000	Invalid parameter
40127	Developer authentication failed
40356	Conversation does not exist
50000	Internal server error