API, webhooks and MCP
The API is part of Pro and above. The full reference is the OpenAPI document at /api/v1/openapi.json.
Authentication
Create a key in Settings, Developers and send it as Authorization: Bearer hb_.... A key acts as the member who created it, limited by its scopes, and stops working when that member leaves or the key is revoked.
| Scope | Allows |
|---|---|
tickets:read | Read tickets and messages |
tickets:write | Create and update tickets, reply and add notes |
customers:read | Read customers and organisations |
customers:write | Create and update customers and organisations |
articles:read | Read articles |
articles:write | Create and update articles |
reports:read | Read reports |
Limits, retries and paging
- Each key has its own rate limit: 120 requests a minute by default, up to 300, or 1200 on Enterprise. Responses carry
RateLimit-LimitandRateLimit-Remaining; a 429 hasRetry-After. - Send
Idempotency-Keyon POSTs that create something: the same key and body within 24 hours replays the first answer. - Lists take
limitand returnnextCursor; pass it ascursor. - Errors are
{ "error", "code", "issues"? }. - The workspace IP allowlist applies to the API too.
curl https://helpbat.officebats.com/api/v1/tickets \
-H 'authorization: Bearer hb_...' -H 'content-type: application/json' \
-H 'idempotency-key: order-4471' \
-d '{"subject":"Refund for order 4471","message":"...","requester":{"email":"[email protected]"}}'
Endpoints
| Method | Path | Does |
|---|---|---|
| GET | /api/v1/workspace | The key’s workspace |
| GET | /api/v1/tickets | List tickets (status, assignee, requester, tag, q, limit, cursor) |
| POST | /api/v1/tickets | Create a ticket |
| GET | /api/v1/tickets/{id} | Get a ticket (id or number) |
| PATCH | /api/v1/tickets/{id} | Update a ticket |
| DELETE | /api/v1/tickets/{id} | Delete a ticket |
| GET | /api/v1/tickets/{id}/messages | Messages of a ticket |
| POST | /api/v1/tickets/{id}/messages | Reply or add a note |
| POST | /api/v1/tickets/{id}/merge | Merge tickets into this one |
| GET | /api/v1/customers | List or find customers |
| POST | /api/v1/customers | Create a customer |
| GET | /api/v1/customers/{id} | Get a customer |
| PATCH | /api/v1/customers/{id} | Update a customer |
| GET | /api/v1/customers/{id}/tickets | A customer’s tickets |
| GET | /api/v1/organizations | List organisations |
| POST | /api/v1/organizations | Create an organisation |
| GET | /api/v1/articles | Search or list articles |
| POST | /api/v1/articles | Create an article |
| GET | /api/v1/articles/{id} | Get an article (id or slug) |
| PATCH | /api/v1/articles/{id} | Update an article |
| GET | /api/v1/reports/summary | Report summary |
Webhooks
Add webhooks in Settings, Developers. Each POST carries HelpBat-Event, HelpBat-Delivery and HelpBat-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + raw body with the webhook’s signing secret (shown once). Check the signature and that t is recent. Failed deliveries are retried for about a day; a webhook that fails 50 times in a row is turned off.
Events: ticket.created, ticket.updated, ticket.deleted, message.created, note.created, sla.breached, ticket.rated, chat.started, trigger.fired. Public replies trigger message.created when they are actually sent (after the undo window).
const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const ok = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex') === v1;
MCP server
AI assistants that speak the Model Context Protocol can use HelpBat at https://helpbat.officebats.com/mcp (streamable HTTP) with an API key as the bearer token. Tools: list_tickets, get_ticket, create_ticket, reply_to_ticket, add_note, update_ticket, find_customer, get_customer, search_articles, get_article, create_article. Tools call the REST API with your key, so scopes, roles, limits and the audit log apply. Ticket content comes back marked as untrusted data.
Extension points
Build integrations today with the API, webhooks, channel apps (Forms and channel apps) and the MCP server. A listing marketplace for these apps is planned.