API Reference / Conversation API / Human handoff service

Manual Service

Last updated：4 days ago

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 -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" } }'

                      
                      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"
  }
}'

This code block in the floating window

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
email	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 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

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

https://your_domain/chat

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

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-${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