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.

ScopeAllows
tickets:readRead tickets and messages
tickets:writeCreate and update tickets, reply and add notes
customers:readRead customers and organisations
customers:writeCreate and update customers and organisations
articles:readRead articles
articles:writeCreate and update articles
reports:readRead 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-Limit and RateLimit-Remaining; a 429 has Retry-After.
  • Send Idempotency-Key on POSTs that create something: the same key and body within 24 hours replays the first answer.
  • Lists take limit and return nextCursor; pass it as cursor.
  • 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

MethodPathDoes
GET/api/v1/workspaceThe key’s workspace
GET/api/v1/ticketsList tickets (status, assignee, requester, tag, q, limit, cursor)
POST/api/v1/ticketsCreate 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}/messagesMessages of a ticket
POST/api/v1/tickets/{id}/messagesReply or add a note
POST/api/v1/tickets/{id}/mergeMerge tickets into this one
GET/api/v1/customersList or find customers
POST/api/v1/customersCreate a customer
GET/api/v1/customers/{id}Get a customer
PATCH/api/v1/customers/{id}Update a customer
GET/api/v1/customers/{id}/ticketsA customer’s tickets
GET/api/v1/organizationsList organisations
POST/api/v1/organizationsCreate an organisation
GET/api/v1/articlesSearch or list articles
POST/api/v1/articlesCreate 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/summaryReport 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.