Last updated at: 2026-07-06

Human Handoff Service

When developers choose Webhook as the human handoff service integration method, they first need to build a Webhook service in their own server environment. Developers need to provide the following 3 interfaces per spec, for receiving human service requests, receiving user messages, and human agent reply messages. AltaBots also provides 2 interfaces for receiving human agent reply messages and conversation close commands.

Notes: - Developers should ensure the Webhook service is available at all times; otherwise, it will affect the normal use of human handoff service. - If "busy" is shown after initiating human handoff service, it means the developer's Webhook service is abnormal. - If "connecting" is shown after initiating human handoff service, it means the developer's Webhook service is normal. - After successfully initiating a human handoff service request, the developer needs to promptly call the reply-to-user-message interface (https://altatech.ai/v1/human/message/receive) to reply to the user with at least 1 message, in order to successfully establish the conversation connection. - If the developer does not reply, the human conversation will automatically end once the configured wait timeout (default 60s) is exceeded.

Receive Human Handoff Service Conversation Request Notification

When an end user initiates a human handoff service request, AltaBots forwards the request to the developer's Webhook service. The developer's interface should return HTTP status code 200 to indicate the human handoff service conversation was successfully created.

Request Method

POST

Request URL

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": "content",
      "message_type": "ANSWER"
    },
    {
      "text": "content",
      "files": {
        "content_type": "Image",
        "url": "https://altatech.ai/example.jpg"
      },
      "message_type": "QUESTION"
    }
  ],
  "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 of the human handoff service conversation scenario — it is distinct from the conversation_id generated by "Create Conversation" for the Agent conversation scenario.

Request Parameters

Parameter	Type	Description
conversation_id	string	Conversation ID for the human handoff service scenario (distinct from the Agent conversation's `conversation_id`), needs to be passed through to AltaBots in the customer service reply interface
timestamp	long	Timestamp
email	string	User email, required by some human handoff service systems to provide normal service
bot_id	string	Agent (formerly bot) ID
body	list\<Object>	Message body
body.message_type	string	Message type, QUESTION/ANSWER
body.text	string	Questions and context initiated by the customer for human handoff service
body.files	list\<Object>	File attachments carried with the message
body.files.content_type	string	File type
body.files.url	string	File URL
user_info	object	User information
user_info.phone	string	User's phone number, currently only available when transferring to human handoff service via WhatsApp
user_info.email	string	User's email, available when the user inputs an email
user_info.user_id	string	User ID. A unique user identity identifier customized 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 information of the channel platform where the user is located

Notes on the email field: - When human handoff service is initiated via iframe/Share/Bubble Widget, the user must fill in an email; developers can also customize the user email to avoid requiring users to fill it in. - When human handoff service is requested via third-party platforms such as WhatsApp/Telegram/LiveChat, support@altatech.ai is used as the user email by default; LiveChat supports developers customizing the user email. - When human handoff service is requested via API, the email field may be left empty; when empty, support@altatech.ai is used as the default user email.

Response

Parameter	Type	Description
code	int	Response code
message	string	Details

Chat Interface

Sends the end user's messages to human handoff service, using the conversation_id created above.

Request Method

POST

Request URL

https://your_domain/chat

Request Example

{
  "conversation_id": "conv_xxx",
  "message_id": "msg_abc124",
  "create_time": 1750000005000,
  "agent_id": "bot_xxx",
  "body": "This is my order screenshot",
  "timestamp": 1750000005200,
  "files": [
    {
      "content_type": "Image",
      "url": "https://altatech.ai/xxx/order.png",
      "name": "order.png",
      "format": "png"
    }
  ]
}

Request Parameters

Parameter	Type	Description
conversation_id	string	Conversation ID, needs to be propagated to AltaBots in the human handoff service reply interface
timestamp	long	Timestamp
body	string	Message text content from the user
message_id	string	ID of the user's message
create_time	long	Creation time of the user's message (milliseconds)
agent_id	string	Agent (Bot) ID
files	array	Attachments uploaded with the message; omit or leave empty if there are none

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

Request URL

https://your_domain/conversation/close

Request Parameters

Parameter	Type	Description
conversation_id	string	Conversation ID, needs to be propagated to AltaBots in the human handoff service 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

When developers choose webhook as the method for accessing human handoff service, AltaBots provides an API interface for receiving human handoff service reply messages and conversation control commands sent by developers.

Receive Customer Service Messages

When developers choose webhook as the human handoff service access method, AltaBots provides an interface for receiving human agent reply messages from the developer's Webhook service and sends the message content to the user.

Request Method

POST

Request URL

https://altatech.ai/v1/human/message/receive

Request Example

{
  "conversation_id": "conv_xxx",
  "timestamp": 1750000000000,
  "body": "Here is the invoice you requested",
  "files": [
    { "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
    { "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
  ]
}

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 service reply content	false
files	array	Attachments carried with the reply; omit or leave empty if there are none	false

Response

Parameter	Type	Description
code	int	Response code
message	string	Details

Manual Customer Service Closes Conversation

When developers choose webhook as the human handoff service access method, the human agent provided by AltaBots can actively close the conversation when needed. After closure, the user will no longer receive messages from the human agent unless the user initiates a human handoff service conversation again.

Request Method

POST

Request URL

https://altatech.ai/v1/human/close

Request Parameters

Parameter	Type	Description
conversation_id	string	Conversation ID, needs to be passed through to AltaBots in the human handoff 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