JavaScript API
Control the widget from your own page: open it from your buttons, ask a question for the visitor, say who is logged in, and react when someone leaves their details.
Set up
Add one line before the widget snippet. Calls made before the widget has loaded are kept and run once it has.
<script>
window.replybash = window.replybash || function () { (replybash.q = replybash.q || []).push(arguments) }
</script>
<script src="https://app.replybash.com/embed.js" data-agent-id="acme_7Hq2k" defer></script>Commands
| Call | What it does |
|---|---|
| replybash("open") | Opens the chat. |
| replybash("open", { message: "Do you ship to Canada?" }) | Opens the chat and asks that question as the visitor. |
| replybash("close") | Closes the chat. |
| replybash("toggle") | Opens it if closed, closes it if open. |
| replybash("hide") | Hides the round button (the chat still opens from code, e.g. your own Help button). |
| replybash("show") | Shows the round button again. |
| replybash("identify", { userId, hash, name, email }) | Tells the agent who is logged in. See Identity verification below. |
| replybash("reset") | Call on logout: forgets the visitor and the open chat, so the next person starts fresh. |
| replybash("on", event, fn) | Listens to an event. replybash("off", event, fn) stops. |
Events
Events are only sent to your own page (its origin), never to other sites.
| Event | When, and what your function gets |
|---|---|
| open, close | The chat was opened or closed. |
| message | The visitor sent a message: { text, files } (files: the name and kind of any attached). |
| reply | The agent answered: { text }. |
| form.submitted | A form was sent: { form: { key, title, purpose }, answers } (answers by field id). |
| lead | The visitor left their details, in a lead form or by booking: { name, email, phone }. |
| meeting.booked | A meeting was booked: { title, start, end } (ISO times). |
| cart.added | Shopify stores: the visitor added a product to the cart from the chat: { variantId, quantity }. Refresh your theme's cart drawer here. |
replybash("on", "lead", (lead) => {
gtag("event", "generate_lead", { method: "chat" })
})
document.querySelector("#help").addEventListener("click", () => replybash("open"))Identity verification
Turn it on in Embed & share › Identity verification and copy the secret to your server. Your server signs the user's id with it; the page passes the id and the hash. A verified user's chats carry their user id, name and email, and the inbox marks them “Verified”.
import { createHmac } from "node:crypto"
// The secret from Embed & share › Identity verification. Keep it on the server.
const hash = createHmac("sha256", process.env.REPLYBASH_IDENTITY_SECRET).update(user.id).digest("hex")replybash("identify", {
userId: "u_1842", // your own id for the user
hash: "9f2c…", // from your server, as above
name: "Maya Chen",
email: "[email protected]",
})Without a valid hash the user id is ignored; name and email are kept on the chat as unverified details. Making a new secret stops old hashes from counting.
Conversation webhooks
To hear about chats on your server instead, add a destination in Integrations and tick New conversation (each chat's first message) or Conversation resolved (your team marks it resolved). They use the same signed payload as form and lead webhooks, with form empty.