Human Handoff Service - Webhook
GPTBots currently supports three products or services for human-assisted service: Intercom, LiveChat, and Webhook. When developers choose webhook as the integration method for human-assisted service, they first need to build a Webhook service in their own server environment, providing the following three interfaces to process initialization requests from Agents for human-assisted service and to receive user messages.
When developers choose webhook as the method for accessing human handoff services, they first need to build a Webhook receiving service in their own server environment, providing the following three interfaces to receive human handoff services requests initiated by the Agent and to receive messages.
Create Conversation ID
Used to create a human handoff services conversation ID for Agent users.
Request Method
POST
Request URL
https://your_domain/conversation/establish
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| conversation_id | string | Conversation ID, must be transparently passed to GPTBots in the customer service reply interface |
| timestamp | long | Timestamp |
| string | User's email. Some manual service systems require an email to function properly | |
| bot_id | string | ID of the Agent (formerly bot) |
| body | list<Object> | Message body |
| body.message_type | string | Message type, QUESTION/ANSWER |
| body.text | string | The customer's queries for human handoff along with context |
| user_info | object | User information |
| user_info.phone | string | User's phone number, currently only passed when switching to human handoff via WhatsApp |
Notes on using the
- When initiating human handoff service via iframe/Share/Bubble Widget, the user must provide an email. Developers are also allowed to customize the user's email to avoid requiring the user to input it.
- When requesting human handoff 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's email.
- When requesting human handoff service via API, the
Response
| Parameter | Type | Description |
|---|---|---|
| code | int | Response code |
| message | string | Details |
Chat Interface
Agent users send messages to human handoff services.
Request Method
POST
Request URL
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| conversation_id | string | Conversation ID, needs to be propagated to GPTBots in the human handoff services reply interface |
| timestamp | long | Timestamp |
| body | string | Message content |
Response
| Parameter | Type | Description |
|---|---|---|
| code | int | Response code |
| message | string | Details |
Close Session Interface
Triggered when the user conversation times out or when the Agent user actively closes the conversation.
Request Method
POST
Request URL
https://your_domain/conversation/close
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| conversation_id | string | Conversation ID, needs to be propagated to GPTBots in the human handoff services reply interface |
| timestamp | long | Timestamp |
| type | string | Type of closure, TIMEOUT (timeout) / USER_CLOSED (user-initiated closure) |
Response
| Parameter | Type | Description |
|---|---|---|
| code | int | Response code |
| message | string | Details |
GPTBots human handoff Service Interface
When developers choose webhook as the method for accessing human services, GPTBots provides an API interface for receiving human handoff services reply messages and conversation control commands sent by developers.
Receive human handoff services Messages
Used to receive reply messages from the developer's end human handoff services, and the message content will be displayed in the Agent conversation window.
Request Method
POST
Request URL
https://api.gptbots.ai/v1/human/message/receive
Request Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| conversation_id | string | Conversation ID, propagated in the conversation creation interface and chat interface | true |
| timestamp | long | Timestamp | true |
| body | string | human handoff services reply content | true |
Response
| Parameter | Type | Description |
|---|---|---|
| code | int | Response code |
| message | string | Details |
| timestamp | long | Timestamp |
| body | string | Content of the human handoff services reply |
Response
| Parameter | Type | Description |
|---|---|---|
| code | int | Response code |
| message | string | Details |
human handoff services Closes Session
human handoff services can choose to actively close the conversation when needed. Once closed, the user will no longer receive messages from human handoff services unless the user initiates a new human handoff services conversation.
Request Method
POST
Request URL
https://api.gptbots.ai/v1/human/close
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| conversation_id | string | Conversation ID, needs to be passed through to GPTBots in the human handoff services reply interface |
| timestamp | long | Timestamp |
Response
| Parameter | Type | Description | Required |
|---|---|---|---|
| conversation_id | string | Conversation ID, passed in the session creation interface and chat interface, passthrough is sufficient | true |
| timestamp | long | Timestamp | true |