Manual Service

When developers choose Webhook as the manual service access method, they first need to build a Webhook service in their server environment. Developers need to provide the following three interfaces according to the specifications to receive manual service requests, user messages, and manual customer service reply messages. GPTBots also provides two interfaces for receiving customer service reply messages and conversation closure instructions.

Important Notes:

1. Developers must ensure their Webhook service is functioning properly, as it directly affects the human support service operation.

• If "Busy" is displayed after initiating human support, it indicates that the developer's Webhook service is malfunctioning.
• If "Connecting" is displayed after initiating human support, it indicates that the developer's Webhook service is functioning normally.

2. After successfully initiating a human support service request:

• Developers need to call the Reply to User Message interface(https://api.gptbots.ai/v1/human/message/receive) to reply to the user with at least one message in order to establish the conversation connection.
• If developers fail to reply to the user's message within the configured waiting timeout period (default 60 seconds), the human support conversation will automatically terminate.

Receive Human Service Conversation Request Notification

When an end user initiates a human service request, GPTBots forwards this request to the developer's Webhook service. A response status code of 200 from the developer's interface service indicates successful creation of the human service conversation.

Request Method

POST

Endpoint

https://your_domain/conversation/establish

Request Example

                      
                      curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \
-H 'Content-Type: application/json' \
-d '{
  "body": [
    {
      "text": "human service",
      "message_type": "QUESTION"
    },
    {
      "text": "content",
      "message_type": "ANSWER"
    },
    {
      "text": "content",
      "files": {
        "content_type":"Image",
        "url":"http://gptbots.ai/example.jpg"
      },
      "message_type": "QUESTION"
    }
  ],
  "timestamp": 1742265090895,
  "email": "bob@gmail.com",
  "conversation_id": "67d8db020fa31d1ef64f53dg",
  "bot_id": "665d88b03ce2b13cf2d573454",
  "user_info": {
    "phone": null,
    "email": "bob@gmail.com",
    "user_id": "KDslas",
    "anonymous_id": "652face5184b30540a6ea7fe"
  }
}'

                    

Note: The conversation_id in this request body is only used to identify the unique ID for human service conversation scenarios, which is different from the unique ID generated by Create Conversation ID for Agent conversation scenarios.

Request Parameters

Notes on the email field:

• When initiating manual service via iframe/Share/Bubble Widget, the user must fill in their email. Developers are also allowed to customize the user email to avoid requiring the user to fill in an email.
• When requesting manual service via third-party platforms such as WhatsApp/Telegram/livechat, the default email used is support@gptbots.ai. For livechat, developers can customize the user email.
• When requesting manual service via API, the email field can be empty. If empty, the default email used is support@gptbots.ai.

Response

Chat Interface

Using the created conversation_id, send the user's message to the manual customer service.

Request Method

POST

Endpoint

https://your_domain/chat

Request Example

                      
                      {
  "conversation_id": "conv_xxx",
  "message_id": "msg_abc124",
  "create_time": 1750000005000,
  "agent_id": "bot_xxx",
  "body": "This is my order screenshot",
  "timestamp": 1750000005200,
  "files": [
    {
      "content_type": "Image",
      "url": "https://files.gptbots.ai/xxx/order.png",
      "name": "order.png",
      "format": "png"
    }
  ]
}

                    

Request Parameters

Response

Close Conversation Interface

When a user conversation times out or the Agent user actively closes the conversation, this interface is called to close the conversation.

Request Method

POST

Endpoint

https://your_domain/conversation/close

Request Header

Request Parameters

Response

Reply to User Messages

When developers choose webhook as the human service integration method, GPTBots provides an interface for replying to user messages. This interface allows human customer service agents to send message content back to users.

Request Method

POST

Endpoint

https://api-${endpoint}.gptbots.ai/v1/human/message/receive

Request Header

Request Example

                      
                      {
  "conversation_id": "conv_xxx",
  "timestamp": 1750000000000,
  "body": "Here is the invoice you requested",
  "files": [
    { "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
    { "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
  ]
}

                    

Request Parameters

Response

Manual Customer Service Closes Conversation

When developers choose webhook as the manual service access method, the manual customer service provided by GPTBots can actively close the conversation when needed. After closure, the user will no longer receive messages from the customer service unless the user initiates a manual customer service conversation again.

Request Method

POST

Endpoint

https://api-${endpoint}.gptbots.ai/v1/human/close

Request Header

Request Parameters

Response

GPTBots Service Status Detection

GPTBots provides a health monitoring endpoint for detecting its own human service. Developers can call this endpoint to probe whether the GPTBots human service is available and working properly. If the endpoint returns HTTP status code 200 and the response body is an English identifier indicating the service is normal (such as service is normal), it means the GPTBots human service is available and working properly. This endpoint requires no authentication and returns plain text.

Request Method

GET

Endpoint

https://api.gptbots.ai/v1/human/health

Request Example

                      
                      curl -X GET 'https://api.gptbots.ai/v1/human/health'

                    

Response

When the GPTBots service is available and working properly, it returns HTTP status code 200, and the response body returns an English identifier indicating the service is normal.

                      
                      service is normal

                    

Availability Determination Recommendations

The caller only needs to use the HTTP status code as the criterion:

It is recommended to set a reasonable request timeout (such as 3 to 5 seconds) and poll at a fixed frequency (QPM: 3). This endpoint requires no authentication, so there is no need to carry an API Key when calling it.