Help API

With a platform key

Make a key under Developers, Keys and tick the Help module (scopes help:read and help:write). The key reaches the Help desk of the organization it was made in, the same tickets that organization's agents see. Pass workspace (a slug) to use another of the organization's Help workspaces. Tickets on restricted desks (HR, Finance, Security) are never reachable with a key. What each key called is under Developers, Logs.

curl "https://api.bolrach.com/v1/help/tickets?status=active&limit=20" \
  -H "Authorization: Bearer $BOLRACH_KEY"

curl -X POST "https://api.bolrach.com/v1/help/tickets" \
  -H "Authorization: Bearer $BOLRACH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Order 1042 has not arrived","body":"It was due on Monday.","customerName":"Ada","customerEmail":"ada@example.com","externalRef":"order-1042"}'
# 201 {"id":"…","number":57,"status":"open","workspace":"acme","idempotent":false,"consoleUrl":"…"}

curl -X PATCH "https://api.bolrach.com/v1/help/tickets/TICKET_ID" \
  -H "Authorization: Bearer $BOLRACH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'

Webhooks

Add an endpoint under Developers, Webhooks (an owner or admin of the Help desk). It must be a public https address. You get its signing secret once. Every event is a POST of JSON:

{
  "id": "evt_…",
  "type": "ticket.created",
  "created": 1790180000,
  "workspace": "WORKSPACE_UUID",
  "data": { "ticket": { "id": "…", "number": 57, "subject": "…", "status": "open", "priority": "medium",
                       "channel": "api", "externalRef": "order-1042", "requester": { "name": "Ada", "email": "ada@example.com" } } }
}

• ticket.created: a ticket was opened, from any channel.
• ticket.updated: status, priority or assignee changed.
• message.created: a reply or an internal note was added; data.message carries it.
• conversation.started: a customer started a chat; data.conversation.
• ticket.sla_at_risk and ticket.sla_breached: a response target is close, or missed.
• ping: sent by Send test, so you can check your signature code first.

Each delivery carries Bolrach-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of the timestamp, a dot and the raw body with your signing secret, the same header Bolrach Pay sends. Refuse anything older than five minutes.

const [t, v1] = req.headers['bolrach-signature'].split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Answer any 2xx within eight seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marked failed; you can send a failed delivery again from the Webhooks page. Switching an endpoint off also stops what is already queued for it.

One engine

Bolrach Help runs as one process. DGUMS omnichannel escalate creates tickets through /api/internal/bridge/tickets so staff work one ticket plane instead of a separate DGUMS-only ticket store.

# health (no auth)
curl "https://bolrach.com/help/api/health"
# → {"ok":true,"service":"help-api"}

Health

curl "https://bolrach.com/help/api/health"

Console API (agents, with an Authvio token)

Agent routes need an Authvio bearer token for audience empire:support:web and the workspace UUID in x-workspace-id.

curl "https://bolrach.com/help/api/tickets?status=open" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
  -H "x-workspace-id: WORKSPACE_UUID"

curl -X POST "https://bolrach.com/help/api/tickets" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
  -H "x-workspace-id: WORKSPACE_UUID" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Billing question","body":"Invoice looks wrong","priority":"medium","customer":{"name":"Ada","email":"ada@example.com"}}'

curl "https://bolrach.com/help/api/tickets/TICKET_UUID" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
  -H "x-workspace-id: WORKSPACE_UUID"

curl -X POST "https://bolrach.com/help/api/tickets/TICKET_UUID/reply" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
  -H "x-workspace-id: WORKSPACE_UUID" \
  -H "Content-Type: application/json" \
  -d '{"body":"We are looking into this.","internal":false}'

Conversations

curl "https://bolrach.com/help/api/conversations?channel=chat" \
  -H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
  -H "x-workspace-id: WORKSPACE_UUID"

Public intake (no agent JWT)

curl -X POST "https://bolrach.com/help/api/public/chat/my-workspace/start" \
  -H "Content-Type: application/json" \
  -d '{"name":"Visitor","message":"Hi, I need help"}'

curl -X POST "https://bolrach.com/help/api/public/intake/my-workspace/ticket" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Website form","body":"Need a callback","email":"visitor@example.com"}'

Estate bridge (DGUMS and internal services)

Service-to-service only, over the private network: the bridge is not reachable from the internet, so the examples use $HELP_INTERNAL_URL for the service address. Each caller sends its own Authvio workload token as Authorization: Bearer, minted for the audience https://bolrach.help/api/internal. Help checks the issuer, the exact audience and the subject, and each subject may use only the route groups it was granted: reading tickets needs help-bridge:tickets.read, creating, patching and replying need help-bridge:tickets.write, and the bulk import needs help-bridge:import. A new caller gets its own subject from the Authvio workload provisioner. Tokens last ten minutes and never leave the server.

curl "$HELP_INTERNAL_URL/api/internal/bridge/health" \
  -H "Authorization: Bearer $AUTHVIO_WORKLOAD_TOKEN"

curl "$HELP_INTERNAL_URL/api/internal/bridge/tickets?workspace=dgums&status=open" \
  -H "Authorization: Bearer $AUTHVIO_WORKLOAD_TOKEN"

curl -X POST "$HELP_INTERNAL_URL/api/internal/bridge/tickets" \
  -H "Authorization: Bearer $AUTHVIO_WORKLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace":"dgums","subject":"WA escalate #42","body":"Customer needs billing help","priority":"high","channel":"chat","source":"dgums-omni","customerName":"Chioma","customerPhone":"+2348012345678","tags":["omni","whatsapp"],"externalRef":"omni:conv-uuid"}'

Related products

• bolrach.com/help agent console
• bolrach.com/support public Help entry
• DGUMS omnichannel at dgums.com/omnichannel (bridge-backed tickets)

Notes

Machine-readable OpenAPI: /openapi/help.json. The platform catalogue (Help, Geo, AI, WhatsApp, …) is at api.bolrach.com/v1. Human mail on the estate stays on Stalwart; this API is the ticket / conversation engine, not the staff mailbox MTA.