Building an Integration Against the Chat API
A reference guide to Chat's developer surface: API tokens with scopes, the agent and customer API endpoints, and a docs page that can't drift out of sync with the API.
Most of what's been written about Chat so far describes the product from inside the inbox — what an agent sees, what a visitor experiences. This one is for the case where you want to build against Chat programmatically: automate part of your support workflow, sync conversation data into another system, or build a custom integration the built-in features don't cover.
Two API surfaces, two audiences
Chat exposes two distinct API surfaces, and the split maps to who's calling them. /api/v1/agent is the surface for actions an agent or your own backend would take on a conversation — the agent-side operations. /api/v1/customer is the surface for the visitor/customer side of a conversation — the actions your own website or app might trigger on behalf of an end user. Treat them as separate contracts: building against the wrong one for your use case will mean fighting the permission model rather than working with it.
Authentication: scoped API tokens
Integrations authenticate with API tokens that carry scopes — a token is issued for a specific set of permitted operations, not blanket account access. When you're setting up a new integration, the practical step is deciding up front what that integration actually needs to do (read conversations, post replies, look up visitor history) and issuing a token scoped to exactly that, rather than a broad token you then have to trust every piece of code that holds it to use responsibly.
The developer page can't lie to you
One detail worth knowing if you're evaluating this API before committing to build against it: the in-product developers page (/developers) doesn't hand-maintain its own list of available methods. It fetches the method list live from /api/v1/agent itself. That means the documentation you're reading in the product is generated from the same source the API actually runs on — it structurally cannot describe a method the API doesn't have, because the two aren't maintained separately. If you've been burned before by API docs that drifted out of sync with the real endpoint, this is a specific, verifiable reason that particular failure mode doesn't apply here.
Where to start
Begin on the developers page inside your workspace, review the live method list for the agent API (or the customer API, depending on which side of a conversation your integration needs to act on), and issue a token scoped narrowly to what your first integration actually does. Expand the token's scope later if you build more on top of it — starting narrow costs you nothing and limits the blast radius if a credential ever leaks.
What this is for
This surface is aimed at technical buyers evaluating Chat specifically because they need to connect it to something else — a custom CRM, an internal dashboard, a data warehouse — not at replacing the built-in inbox experience. If your team is happy working inside Chat's own UI, you likely don't need this at all; it's for the case where Chat needs to talk to software you've already built.