Chat API
The Chat API works with live Beacon chats — a chat while it is still open, and the visitor is still watching.
It is an HTTPS-only API using OAuth 2 and JSON, running at:
https://api.helpscout.net/v2
Chats sit under /chats on the same base as the Inbox API, so a token that reads a conversation also reads a chat.
A live chat is not a conversation. Help Scout creates a conversation only when the chat ends, and the whole transcript then collapses into a single thread attributed to the customer. So while a chat is open there is nothing in the Inbox API to address, and this API exists to fill that gap.
What you can do
Read
| Get a chat | the chat, its participants and its timeline |
| Get chat events | the messages, notes and line items, paginated |
Interact
| Accept a chat | claim an unassigned chat |
| Add a message | send something the visitor sees, live |
| Add a note | leave context for a colleague; the visitor never sees it |
| Assign a chat | hand it to a person |
| Unassign a chat | release it back to the queue |
| Update tags | classify it, in time for the tags to reach reporting |
| End a chat | close it, and create the conversation |
Reacting to a chat
Chats are best driven by webhooks rather than polling:
| Event | Fires when |
|---|---|
beacon.chat.created |
a visitor starts a chat |
beacon.chat.customer.replied |
the visitor sends another message |
beacon.chat.agent.replied |
an agent replies |
beacon.chat.assigned |
the chat is assigned to a user |
beacon.chat.ended |
the chat ends |
Each carries the chat, and beacon.chat.created embeds the visitor’s first message — so an integration can usually decide what to do without a follow-up read.
Before you start
An agent must be available for a chat to exist at all. Beacon offers chat to a visitor only when someone is present in the inbox; otherwise it offers email. An integration therefore answers chats that already exist — it cannot make chat available.
Two callouts that are invisible from the API. Ending a chat while the visitor’s last message is unanswered tells them they have been put in an email queue — see End chat. And handing a chat to a person who is not available succeeds silently — see Assign chat.
The user your app acts as matters. An app authenticates using tokens, and Help Scout resolves it to the user who created the token. That user’s name is what the visitor sees, so create the app while signed in as the user you want on the outside of the conversation.