Public API
Put TrolleyChat's assistant inside your own product. Your server calls the API, tells us which of your signed-in users is asking, and gets back the assistant's reply. You build the chat UI; TrolleyChat provides the brain: the inbox's knowledge base, its personality, escalation to a human, and the full conversation in your team's dashboard.
When to use the API instead of the widget
The live chat widget is the right choice for a storefront or a marketing site: anonymous visitors, one script tag, no code. The API is for applications that already know who their users are and want the conversation to live inside their own interface.
| Live chat widget | Public API | |
|---|---|---|
| Who the visitor is | Anonymous until they verify an email | Your app tells us, on every conversation |
| Where it runs | A script tag on your site | Your server, calling ours |
| The UI | TrolleyChat's chat window | Yours |
| The assistant | Same | Same |
| Human handoff and dashboard | Yes | Yes |
How it works
- You create an API key on an inbox, under Settings → Integrations → API access.
- When a user opens your help panel, your server calls
POST /api/v1/conversationswith your user's id. You get a conversation and its recent history. - When the user sends a message, your server calls
POST /api/v1/conversations/{id}/messages. The assistant's reply comes back in the same response. - If the assistant hands the conversation to a person, your team answers from the TrolleyChat dashboard. Your server picks up their replies with
GET /api/v1/conversations/{id}/messages.
Everything the assistant says comes from the inbox's knowledge base and configuration. It never reads data from your application, and in v1 it takes no actions other than handing off to a person.
Base URL
https://app.trolleychat.ai
All requests and responses are JSON.
In this section
- Authentication — creating and using API keys
- Identity and metadata — how you tell us who is asking
- Conversations and messages — the three endpoints
- Errors and rate limits — the codes your client should handle
- Quickstart — a working example in a few minutes