Developer overview
Build on Bookbag: embed the chat widget, call the REST API, react to webhooks, and listen for widget events. The map of every developer surface and where to start.
View as MarkdownBookbag is built to be extended. Whether you want a chat bubble on your storefront, a programmatic chat endpoint in your backend, or real-time notifications when a lead comes in, there is a developer surface for it. This section is the narrative companion to the API Reference.
The surfaces
| Surface | What it does | Auth |
|---|---|---|
| JavaScript embed | Drops a chat bubble on any website with one script tag. | None — keyed by agent id. |
| REST API | Chat, conversations, contacts, and leads from your backend. | Authorization: Bearer oc_... |
| Webhooks | Bookbag POSTs to your URL when events happen (leads, escalations, replies). | HMAC signature you verify. |
| Event listeners | React to widget lifecycle in the browser. | None — runs client-side. |
Choosing an approach
- Just want chat on your site? Use the JavaScript embed. No code beyond a script tag.
- Building a custom UI or backend integration? Use the REST API — prefer API v2 for new work.
- Need to sync to a CRM or get notified of events? Set up a webhook.
- Personalizing replies for signed-in users? See Identity verification.
Before you start
For anything beyond the embed you will need an API key. Create one in the dashboard (you need the admin role) and store the oc_... value securely — it is shown only once. See Authentication.
You will also need your agent id — the numeric id of the agent you want to build against. It appears in the agent's dashboard URL and is the agentId / chatbotId in every API path.