Camille asks her repair shop whether they can also fix her gears, a question the shop's automation leaves to a person. A live chat is the workspace's members answering a contact themselves in a conversation, from the Heythere app or the API. While it lasts, the contact's messages go to the members and start no run.
How does a live chat start?
With a member's first message to the contact, sent with sendConversationMessage. It cancels the conversation's active run.
An automation asks for one with a handover step: its run ends handed_over, and the conversation awaits a member. Until one writes, Camille's messages start no run, and the conversation shows its handover.
Who is notified?
The Heythere iPhone app notifies the workspace's members of a handover, then the member who started the live chat of each message the contact sends.
What can members send?
Text, while the conversation's reply window is open: WhatsApp refuses any other message outside it. showConversationTyping shows Camille that a member is typing.
How does a member hand the contact to an automation?
With startAutomationRun, such as when Camille asks to join the waitlist for the next repair slot. The automation of the conversation's number runs as if its message.received trigger had received her latest message. getConversationAutomation says whether it can start.
When does a live chat end?
When a member ends it with endLiveChat or starts an automation, or when the reply window closes, 24 hours after the contact's latest message. The contact's next message then goes to the number's automation again, as does every message once a handover's reply window closes without a member answering.
In the API
Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.
- POST
sendConversationMessageSend conversation message
/api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/messages - POST
showConversationTypingShow conversation typing
/api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/typing - POST
endLiveChatEnd live chat
/api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/live-chats/{liveChatId}/end - POST
startAutomationRunStart automation run
/api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/automation/runs - GET
getConversationAutomationGet the conversation's automation
/api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/automation