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.
Create Conversation ID
Used to create a conversation_id to transmit the message requesting manual service from the user.
Request Method
POST
Endpoint
https://your_domain/conversation/establish
Request Example
curl -v -X POST https://YOUR_DOMAIN/human/service/conversation/establish
--header "Content-Type: application/json"
--data '{
"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"}
}'
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 |
| 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 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 |
Receive Customer Service Messages
When developers choose webhook as the manual service access method, GPTBots provides an interface for receiving manual customer service reply messages from the Webhook endpoint and sends the message content to the user.
Request Method
POST
Endpoint
https://api.gptbots.ai/v1/human/message/receive
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.gptbots.ai/v1/human/close
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 |