Start Conversation
Last updated:2023-11-02

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

        
This code block in the floating window

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. Max length 32 chars.

Response

Response Example

{ "conversation_id": "657303a8a764d47094874bbe" }
          {
  "conversation_id": "657303a8a764d47094874bbe" 
}

        
This code block in the floating window

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
20059 Bot deleted

Send Message

Send a message to the specified conversation ID and get the bot response message. Supports submitting text and/or images as message content.

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 '{ "text": "Hello!", "conversation_id": "xxxxxx", "response_mode": "streaming", "image_configs":[ { "url": "https://res.gptbots.cc/ailab/botchat/file/38f13465ad5246190b759b3289ecba51.jpg", "width": 200, "height": 200 } ] }'
          curl -X POST https://api.gptbots.ai/v1/conversation/message \ 
  -H 'Authorization: Bearer your_apikey' \ 
  -H 'Content-Type: application/json' \ 
  -d '{
        "text": "Hello!",
        "conversation_id": "xxxxxx",
        "response_mode": "streaming",
        "image_configs":[
          {
            "url": "https://res.gptbots.cc/ailab/botchat/file/38f13465ad5246190b759b3289ecba51.jpg",
            "width": 200,
            "height": 200
          }
        ]
}'

        
This code block in the floating window
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
text string Yes Either text or image_configs must be entered.
The user's text message, the length of the text content cannot exceed the token length limit set by the Bot configuration.
image_configs JSON Array Yes Either text or image_configs must be entered.
The user's picture message supports the submission of the network path of the picture, up to 9 pictures, and the length cannot exceed the token length limit set by the Bot.
Picture type: jpeg\png\jpg\webp
Picture configuration:
  • url, string, link of the picture
  • width, int, picture width
  • height, int, picture height
    [{"url":"https://res.gptbots.cc/ailab/botchat/file/38f13465ad5246190b759b3289ecba51.jpg","width":200,"height":200}]
  • 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": "65a4ccfC7ce58e728d5897e0", "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": "657303a8a764d47094874bbe" }
              {
      "message_id": "65a4ccfC7ce58e728d5897e0",
      "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": "657303a8a764d47094874bbe"
    }
    
            
    This code block in the floating window

    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 long 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}
              {"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}
    
            
    This code block in the floating window

    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
    40364 This Bot does not use an LLM that supports image mode
    20059 Bot deleted
    20040 Exceeded question limit
    40358 conversation_id does not match bot or user
    20022 Credit not enough