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:
- 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.
- 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": "",
"message_type": "ANSWER"
}
],
"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
Parameter | Type | Description |
---|---|---|
conversation_id | string | Conversation ID for human customer service scenarios (distinct from Agent conversation IDs), must be passed through to GPTBots in the customer service reply interface |
timestamp | long | Timestamp |
string | User email, some manual service systems require an email to provide services properly | |
bot_id | string | Agent (formerly bot) ID |
body | list<Object> | Message body |
body.message_type | string | Message type, QUESTION/ANSWER |
body.text | string | The question initiated by the customer for manual customer service and its context |
user_info | object | User information |
user_info.phone | string | User's phone number, currently only available when switching to manual customer service via WhatsApp |
user_info.email | string | User's email, available when the user enters their email |
user_info.user_id | string | User ID. A unique identifier for user identity defined by enterprise developers, set by developers for a specific anonymous ID |
user_info.anonymous_id | string | Anonymous ID. When a user initiates a conversation with the Agent on non-API channel platforms, the system generates an anonymous ID containing the channel platform information based on the user's channel platform |
Notes on the
- 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
Response
Parameter | Type | Description |
---|---|---|
code | int | Response code |
message | string | Details |
Chat Interface
Using the created conversation_id
, send the user's message to the manual customer service.
Request Method
POST
Endpoint
Request Parameters
Parameter | Type | Description |
---|---|---|
conversation_id | string | Conversation ID, needs to be passed to GPTBots in the customer service reply interface |
timestamp | long | Timestamp |
body | string | User's message |
Response
Parameter | Type | Description |
---|---|---|
code | int | Response code |
message | string | Details |
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
Field | Type | Description |
---|---|---|
Authorization | Bearer ${token} | Use Authorization: Bearer ${token} for authentication. Obtain the token from the API key page. |
Content-Type | application/json | Data type, set to application/json. |
Request Parameters
Parameter | Type | Description |
---|---|---|
conversation_id | string | Conversation ID, needs to be passed to GPTBots in the customer service reply interface |
timestamp | long | Timestamp |
type | string | Type of closure, TIMEOUT (timeout closure) / USER_CLOSED (user actively closed) |
Response
Parameter | Type | Description |
---|---|---|
code | int | Response code |
message | string | Details |
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
Field | Type | Description |
---|---|---|
Authorization | Bearer ${token} | Use Authorization: Bearer ${token} for authentication. Obtain the token from the API key page. |
Content-Type | application/json | Data type, set to application/json. |
Request Parameters
Parameter | Type | Description | Required |
---|---|---|---|
conversation_id | string | Conversation ID, passed in the conversation creation interface and chat interface, just pass it through | true |
timestamp | long | Timestamp | true |
body | string | Reply content from the manual customer service | true |
Response
Parameter | Type | Description |
---|---|---|
code | int | Response code |
message | string | Details |
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
Field | Type | Description |
---|---|---|
Authorization | Bearer ${API Key} | Use Authorization: Bearer ${API Key} for authentication. Get API key from API Key page. |
Content-Type | application/json | Data type, set to application/json. |
Request Parameters
Parameter | Type | Description |
---|---|---|
conversation_id | string | Conversation ID, needs to be passed to GPTBots in the customer service reply interface |
timestamp | long | Timestamp |
Response
Parameter | Type | Description | Required |
---|---|---|---|
conversation_id | string | Conversation ID, passed in the conversation creation interface and chat interface, just pass it through | true |
timestamp | long | Timestamp | true |