Developers

Drive the chat from your code.

Pre-authenticate visitors so contacts are known, open and close the widget on demand, and stream support events to your stack — all from your existing JavaScript and server.

Get startedWebhook events
Quick start

Install

Paste this once in your site's <head>. Everything else is optional.

install.html
<!-- Paste once, just before </head> -->
<script async src="https://your-helpbird-host/api/embed?id=YOUR_PROJECT_ID"></script>

Replace YOUR_PROJECT_ID with your own project ID from Settings → Install. The async loader injects the chat button and iframe (it never blocks your page) and exposes a global window.HelpBird object. If the project is inactive or the widget is hidden, the script is an empty no-op — a stale tag never breaks the host page.

Method

HelpBird.identify()

Tell the widget who the visitor is so the conversation lands on a known contact — the email matches or creates the contact and attaches their cross-conversation history.

Signature

HelpBird.identify({ email, name?, user_id?, hmac? })

Parameters

  • user_id — your own identifier for the visitor. optional
  • email — used to match or create the contact and build their history. required
  • name — display name shown to your agents. optional
  • hmac — server-signed digest for verified identity. optional

Safe to call any time after the loader has run — the widget picks it up even if the visitor hasn't opened the chat yet.

example.html
<script>
  // Any time after the loader has run — one object:
  HelpBird.identify({
    email: "jane@acme.com",           // required — matches/creates the contact
    name: "Jane Doe",                 // optional — shown to your agents
    user_id: "your-internal-user-42", // optional — your own identifier
    hmac: "<hmac from your server>",  // optional — verified identity
  });
</script>
Method

open() & close()

Show or hide the chat widget from your own UI — wire it to a "Contact support" button, a help menu, or an exit-intent flow.

Methods

  • HelpBird.open() — open the widget panel.
  • HelpBird.close() — collapse the widget back to the launcher.

Both are safe to call any time after the loader has run.

support-button.html
<button onclick="HelpBird.open()">Contact support</button>
Server · Pro

Verified identity

Pre-authenticate your visitors with your existing login system. Sign the visitor's identifier server-side with your project's identity secret, pass the digest to identify, and the contact arrives already known — with a verified badge your agents can trust.

How it works

  • The digest is HMAC-SHA256(secret, identifier), hex-encoded. The identifier is the user_id you pass to identify(), or the email if you don't pass one.
  • The secret is in Settings → Install → Identity verification (account owner, Pro). Keep it server-side — never ship it in page JavaScript. Rotating it there invalidates every signature made with the old one.
  • On a valid signature the conversation is marked verified, so agents know exactly who they're helping.

Why use it

  • Visitors never re-type their name or email — the contact is known from the first message.
  • Only signed calls get the Verified badge. Unsigned calls still work but aren't marked verified, so agents can tell the difference.
  • Conversation history attaches to the right contact every time.
server.ts
// Sign once per page load, server-side.
import { createHmac } from "node:crypto";

// Identifier: your user_id if you pass one to identify(), else the email.
const hmac = createHmac("sha256", process.env.HELPBIRD_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

// Render it into the page, then:
//   HelpBird.identify({ user_id: String(user.id), email: user.email, name: user.fullName, hmac });
Server · Pro

Webhooks

Subscribe to support events from outside the browser — Slack notifications, CRM sync, Zapier flows, custom analytics, anything. We POST a signed JSON payload; you verify the signature and process.

Configure

Settings → Webhooks. Add a URL, pick events, and keep the shared secret somewhere safe — it signs every delivery.

Events

  • message_posted — a new message from a visitor or an agent.
  • mention_received — a teammate is @mentioned in an internal note. data.mentions lists who.

Headers

  • Content-Type: application/json
  • X-Helpbird-Event — the event name (matches the body's event field).
  • X-Helpbird-Signature — hex-encoded HMAC-SHA256 over the raw request body, keyed with your shared secret.

Behavior

  • Best-effort delivery. We don't queue or retry — design your receiver to be idempotent.
  • 6-second timeout per delivery. Slow receivers are recorded as failed and we move on.
  • The last HTTP status and error per endpoint are visible in the admin panel.

Payload

message_posted.json
{
  "event": "message_posted",
  "project_id": 123,
  "data": {
    "comment_id": 67890,
    "room_id": 12345,
    "channel": "12345",
    "username": "Jane Doe",
    "message": "Hi, my order shipped to the wrong address.",
    "is_admin": false,
    "mentions": []
  }
}

Verifying the signature

verify.ts
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: Buffer, headerSig: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    expected.length === headerSig.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(headerSig))
  );
}

Common patterns

Slack relay

Subscribe to message_posted; format and forward to a Slack incoming-webhook.

CRM sync

On message_posted, log the message against the conversation in your CRM — room_id is a stable key.

Mention alerts

On mention_received, page the on-call lead so an at-risk conversation gets picked up fast.

Back to adminNeed help? Get in touch →