logo
Development
Search
Manual Service

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

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

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