Replyze is AI customer support for your website: an AI agent that answers from your knowledge base and hands the chat to your team when it should, live chat on your site, and one shared inbox for web chat, email, WhatsApp and Telegram (Messenger and Instagram are in beta). This repository is the developer reference: how to embed the chat widget, control it from JavaScript, verify signed-in users, use the REST API, receive webhooks and connect AI agents over MCP. Every example in examples/ runs as is.
Create a free account · Live demo · OpenAPI spec
-
Get an API key. Create a free account, open Settings → Integrations → Developer and create a key with the
conversations:readscope. The key starts withrpz_live_and is shown once. Whether a workspace has the REST API depends on its plan (pricing); without it, calls answer403 plan_required. -
Check the key.
export REPLYZE_API_KEY=rpz_live_... curl https://client.replyze.chat/api/v1/me -H "Authorization: Bearer $REPLYZE_API_KEY"
The answer names the key, its scopes and its workspace:
{"object":"api_key","id":7,"name":"My first key","prefix":"rpz_live_AbC123","scopes":["conversations:read"],"expires_at":null,"workspace":{"id":1,"name":"Acme"}} -
List your open conversations.
curl "https://client.replyze.chat/api/v1/conversations?status=open&limit=5" -H "Authorization: Bearer $REPLYZE_API_KEY"
Next: send a reply from Node.js, Python or PHP, receive webhooks, or put the chat on your site. The live demo is replyze.chat itself: the chat bubble in the bottom-right corner is the Replyze widget.
- Add the chat widget to your site
- JavaScript API
- Identity verification
- REST API
- Webhooks
- MCP server for AI agents
- More from Replyze
- Development
Paste this before </body> on every page. Your widget token (wgt_...) is in the dashboard under Settings → Integrations → Install widget, which also shows this snippet with your token filled in.
<script>
window.ReplyzeConfig = {
token: 'wgt_YOUR_TOKEN_HERE',
apiUrl: 'https://client.replyze.chat'
};
</script>
<script src="https://cdn.replyze.chat/widget.js" async></script>The script loads asynchronously, so it doesn't hold up your page. A full page with the JavaScript API wired up is in examples/widget/index.html.
Where the snippet goes on WordPress, Shopify, Wix, Webflow, Google Tag Manager, React, Laravel and other platforms, with a troubleshooting list (allowed domains, Content-Security-Policy, ad blockers): add-live-chat-to-website. Packages that do it for you: React and Next.js, Vue and Nuxt, WordPress, React Native and Expo, Flutter.
window.ReplyzeConfig |
What it does |
|---|---|
token |
Your widget token. Required. |
apiUrl |
The Replyze API. https://client.replyze.chat (the default). |
language |
The chat's interface language ("de", "pt-BR", "ar"...), over the visitor's browser and the widget settings. |
tracking |
false turns off visitor tracking (the visitor cookie, page views and heartbeats), for example until the visitor accepts analytics cookies. The chat works either way. Turn it on later with Replyze.setTracking(true). |
overrides |
Look and behaviour set from your page, each one over the dashboard's widget settings: color ("#1eabd2" or rgb(...)), position ("bottom_left" or "bottom_right"), theme ("light" or "dark"), bot_name, bot_avatar (an https URL), welcome_message, show_greeting_teaser (true/false), auto_open_delay (seconds, 0 to 300). A value that doesn't fit is ignored. |
If your Content Security Policy doesn't allow inline scripts, put the settings on the script tag:
<script src="https://cdn.replyze.chat/widget.js"
data-token="wgt_YOUR_TOKEN_HERE"
data-api-url="https://client.replyze.chat"
data-language="en"
async></script>data-tracking="false" turns off visitor tracking, as tracking: false does above.
Once the script has loaded, window.Replyze controls the widget.
| Method | What it does |
|---|---|
Replyze.open() / close() / toggle() |
Open, close or toggle the chat window |
Replyze.show() / hide() |
Show or hide the launcher and the chat; the widget keeps running while hidden |
Replyze.identify(email, name) |
Tell the chat who the visitor is |
Replyze.identify({ user_id, email, name, user_hash }) |
The same for a signed-in user, verified with a signature from your server: see Identity verification. Another person than the one this browser was identified as (another user_id, or else another email) starts as a new visitor first, as after reset() |
Replyze.setUser({ email, name, data }) |
Name and email, plus custom data in data |
Replyze.setData({ plan: 'pro', seats: 12 }) |
Custom data on the visitor's contact: text, numbers, true/false, or null to remove a key. Keys that match a contact field fill it; others are kept as extra data. Up to 50 keys at a time. |
Replyze.pushEvent('Signed up', { plan: 'pro' }) |
An event on the visitor's timeline in the inbox, with the page it happened on. Names are 1 to 64 characters. |
Replyze.setLanguage('de') |
The chat's interface language, over the browser's and the widget settings |
Replyze.sendMessage('Hi!') |
Send a message as the visitor |
Replyze.openArticle(12) |
Open the widget on a help article (the widget needs its Home or Help tab) |
Replyze.setTracking(false) |
Turn visitor tracking off or on, for example from a cookie banner |
Replyze.reset() |
The visitor signed out of your site: forget them (chat, contact, visitor cookie), also in your site's other open tabs. The next chat starts as a new visitor. Safe to call as the page loads, while the widget is still restoring the previous visitor's chat. |
Replyze.on(event, callback) / off(event, callback) |
Listen to the events below |
| Event | When | Callback gets |
|---|---|---|
ready |
The widget has started: once, after the calls queued before the script loaded have run and window.Replyze is the widget's API, so a queued on('ready', ...) hears it. A listener added after that is called right away. (Before 13 November 2026 the widget fired it too early for any listener.) |
nothing |
open / close |
The chat window opened or closed | nothing |
message:sent |
The visitor sent a message | { text }, or { file } for an upload |
message:received |
A reply arrived from the AI or the team | the message |
identified |
identify() went through |
{ verified }: true when the signature checked out |
reset |
reset() finished |
nothing |
unread |
The unread count changed (the launcher's badge) | the count |
Replyze.on('unread', (count) => {
document.querySelector('#help-badge').textContent = count || '';
});The script is async, so window.Replyze doesn't exist for the first moments. Calls made earlier can wait in a queue that the widget runs when it starts:
<script>
window.ReplyzeConfig = { token: 'wgt_YOUR_TOKEN_HERE', apiUrl: 'https://client.replyze.chat' };
window.Replyze = window.Replyze || { _queue: [] };
</script>
<script src="https://cdn.replyze.chat/widget.js" async></script>
<script>
// Runs the call now if the widget is there, else queues it.
function replyze(method, ...args) {
if (window.Replyze && window.Replyze._initialized) window.Replyze[method](...args);
else window.Replyze._queue.push([method, ...args]);
}
replyze('on', 'open', () => console.log('The chat was opened'));
replyze('identify', 'jane@example.com', 'Jane Doe');
</script>Without verification, identify() only labels the visitor. With it, a signed-in user of your site becomes the same contact on every device and browser, marked as verified in the inbox, and nobody can chat as someone else by calling identify() with their email.
- Turn it on in Settings → Chat Widget → Identity (owners and admins). Copy the secret it creates and keep it on your server only.
- When a user is signed in, your server computes
user_hash: the hex HMAC-SHA256 of the user's id as a string, keyed with the secret. A user without an id is signed by their email in lower case, without spaces around it. - The page passes it to the widget:
Replyze.identify({
user_id: '42', // the same id you signed
email: 'jane@example.com',
name: 'Jane Doe',
user_hash: '<the signature from your server>',
});- When the user signs out, call
Replyze.reset()so the next person on that computer starts fresh.
A wrong user_hash changes nothing: the widget stays the anonymous visitor it was. With verification turned on, an identify() that has a user_id but no valid user_hash is refused.
On the server
// Node.js
const crypto = require('crypto');
const userHash = crypto.createHmac('sha256', process.env.REPLYZE_IDENTITY_SECRET)
.update(String(user.id))
.digest('hex');# Python
import hashlib, hmac, os
user_hash = hmac.new(os.environ["REPLYZE_IDENTITY_SECRET"].encode(), str(user.id).encode(), hashlib.sha256).hexdigest()// PHP
$userHash = hash_hmac('sha256', (string) $user->id, getenv('REPLYZE_IDENTITY_SECRET'));Runnable versions with the email fallback are in examples/identity/. Check your code against this test vector (the secret is made up):
| Secret | Signed | user_hash |
|---|---|---|
f3a1c9e07b2d4e68a5c1d9b3e7f20486a9c3e5d7f1b3a5c7e9d1f3b5a7c9e1d3 |
user id 42 |
61b4b465a57ec25065d5a3b377329c00ab8e1c5562756729d26d880f39d8ec13 |
| same | email Jane@Example.com (no id) |
74baeda7d2f63e1df51c7aeea059bcf644fdca57ec0fcaba9a0f7b0e1b5eaaf9 |
The REST API reads and changes one workspace: conversations and messages, contacts, the knowledge base and analytics. Whether your workspace has it depends on its plan (pricing); without it, calls answer 403 plan_required.
- Base URL:
https://client.replyze.chat/api/v1 - Authentication: an API key, sent as
Authorization: Bearer rpz_live_...(or asX-Api-Key: rpz_live_...). Owners and admins make keys in Settings → Integrations → Developer, with the scopes the key needs. A key acts as the workspace, not as a person; it is shown once and can be revoked at any time. - Spec:
openapi.json(OpenAPI 3.1), the same document ashttps://client.replyze.chat/api/v1/openapi.json. Import it into Postman, Insomnia or an OpenAPI code generator.
curl "https://client.replyze.chat/api/v1/conversations?status=open" \
-H "Authorization: Bearer $REPLYZE_API_KEY"| Scope | Allows |
|---|---|
conversations:read |
Read conversations, their messages and notes, the team and the tags |
conversations:write |
Start conversations, send replies and internal notes, assign, resolve, reopen and tag |
contacts:read |
Read contacts |
contacts:write |
Create and update contacts |
knowledge:read |
Read knowledge base articles and categories, search the knowledge the AI answers from |
knowledge:write |
Create and update articles and categories |
analytics:read |
Read the analytics summary |
A write scope includes the read scope of the same resource.
| Method | Path | What it does |
|---|---|---|
| GET | /me |
The API key and its scopes |
| GET | /agents |
The teammates |
| GET | /tags |
The tags |
| GET | /conversations |
List conversations (filters: status, channel, contact_id, assigned_agent_id, unassigned, team_id, tag_id, q, created_since, updated_since) |
| POST | /conversations |
Start a conversation with a contact |
| GET | /conversations/{id} |
One conversation |
| POST | /conversations/{id}/assign |
Assign it to a teammate or a team |
| POST | /conversations/{id}/resolve |
Resolve it |
| POST | /conversations/{id}/reopen |
Reopen it |
| POST | /conversations/{id}/tags |
Tag it |
| DELETE | /conversations/{id}/tags/{tagId} |
Remove a tag |
| GET | /conversations/{id}/messages |
Its messages, oldest first |
| POST | /conversations/{id}/messages |
Send a reply ("type": "reply") or an internal note ("type": "note") |
| GET | /conversations/{id}/messages/{messageId} |
One message |
| GET | /contacts |
List contacts |
| POST | /contacts |
Create a contact |
| GET / PATCH | /contacts/{id} |
Read or update a contact |
| GET / POST | /articles |
List or create knowledge base articles |
| GET / PATCH | /articles/{id} |
Read or update an article |
| GET / POST | /categories |
List or create categories |
| GET / PATCH | /categories/{id} |
Read or update a category |
| GET | /knowledge/search?q=... |
Search everything the AI answers from |
| GET | /analytics/summary |
The Analytics page's headline numbers |
-
JSON in, JSON out. Every object has an
objectfield naming its type. Times are ISO 8601 in UTC. -
Pagination. Lists answer
{ "object": "list", "data": [...], "has_more": true, "next_cursor": "..." }. Passcursor=<next_cursor>for the next page andlimit(1 to 100; default 25, and 50 for a conversation's messages) for its size. Lists are newest first, except a conversation's messages, which are oldest first.updated_sincereturns only what changed since then, for syncing. -
Errors.
{ "error": { "code": "...", "message": "...", "details": { ... } } }:Status code400 bad_request401 missing_api_key,invalid_api_key,api_key_revoked,api_key_expired403 insufficient_scope(the scope indetails.required_scope),plan_required,workspace_suspended404 not_found: no such record in this workspace (another workspace's records are "not found" too), or no such endpoint405 method_not_allowed409 contact_exists(the contact indetails.contact_id),idempotency_in_progress422 validation_failed(details.errorsper field),idempotency_key_reused429 rate_limited(details.retry_afterin seconds)500 server_error -
Idempotency. Send
Idempotency-Key: <a unique value>(up to 255 characters) with a POST. Sent again with the same key within 24 hours, it returns the first answer (withIdempotent-Replayed: true) instead of doing it twice, so a retry never sends a message twice. The same key with a different request is refused (422 idempotency_key_reused), and so is a retry while the first request is still running (409 idempotency_in_progress). Server errors,409and429answers are not kept, so you can retry those with the same key. -
Rate limit. 120 requests a minute per key, and 600 a minute for all the keys of a workspace together. Every answer has
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(Unix time); a 429 hasRetry-After(seconds). -
Audit. What a key changes, and every conversation or contact it reads, is in the workspace's audit log under the key's name.
| Language | List open conversations | Send a reply |
|---|---|---|
| cURL | curl/list-conversations.sh |
curl/send-message.sh |
| Node.js 18+ (fetch, no SDK) | node/list-conversations.mjs |
node/send-message.mjs |
| Python (requests) | python/list_conversations.py |
python/send_message.py |
| PHP (cURL) | php/list-conversations.php |
php/send-message.php |
All of them read the key from the REPLYZE_API_KEY environment variable.
Webhooks send events to your server as they happen. Add one in Settings → Integrations → Developer → Webhooks: the URL, the events to send, and the signing secret, which is shown only once.
| Event | When | data |
|---|---|---|
conversation.created |
A conversation's first message from the visitor or the team | conversation |
conversation.assigned |
A conversation was given to a teammate or a team | conversation |
conversation.resolved |
A conversation became resolved | conversation |
message.created |
A message from the visitor, the team or the AI (not internal notes, system lines or spam) | message, conversation |
contact.created |
A contact with a name, email or phone (an anonymous visitor counts from the moment they give one) | contact |
contact.updated |
A known contact's details changed | contact, changed (the fields) |
Each event is a JSON POST:
{
"id": "0b9f6a52-3c1e-4d7a-9e21-5f8c2b7d1a40",
"event": "message.created",
"created_at": "2026-11-12T10:15:00.000000Z",
"workspace_id": 1,
"data": { "message": { "...": "..." }, "conversation": { "...": "..." } }
}with these headers:
| Header | Value |
|---|---|
X-Replyze-Event |
The event name |
X-Replyze-Event-Id |
A copy of the body's id, the same on every retry. Not signed |
X-Replyze-Timestamp |
A copy of the body's created_at, in Unix seconds. Not signed |
X-Replyze-Signature |
sha256= and the hex HMAC-SHA256 of the raw request body, keyed with the signing secret |
Only the body is signed. X-Replyze-Event-Id and X-Replyze-Timestamp are conveniences, for logs or routing; anyone who captured a request can send it again with new values in them. So take the id and the time from the body, never from these headers.
Check every request before you trust it, in this order:
- Compute the HMAC over the raw bytes you received (not over re-serialized JSON) and compare it with
X-Replyze-Signaturein constant time, as bytes. No match: answer401. - Parse the body. If its
created_atis more than 5 minutes away from now, answer400: it is an old request sent again. - If you have already handled its
id, answer200and stop: it is a retry.
Answer with any 2xx within 10 seconds and do the work afterwards. A network error, a timeout or a 5xx is retried twice, after 30 seconds and then 3 minutes, with the same body, so a 5-minute window lets the retries in; any other answer is final. Redirects are not followed, so a 3xx counts as a failed delivery. The URL must be a public http:// or https:// address. Requests come with User-Agent: Replyze-Webhooks/1.0.
// Node.js
const crypto = require('crypto');
function verifyReplyzeSignature(rawBody, header, secret) {
if (typeof header !== 'string') return false;
const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));
const received = Buffer.from(header); // compare bytes: a non-ASCII header has more bytes than characters
return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}
// createdAt from the signed body, not the X-Replyze-Timestamp header
function isFresh(createdAt, maxAgeSeconds = 300) {
const sent = typeof createdAt === 'string' ? Date.parse(createdAt) : NaN;
return Number.isFinite(sent) && Math.abs(Date.now() - sent) <= maxAgeSeconds * 1000;
}# Python
import hashlib, hmac, time
from datetime import datetime
def verify_replyze_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
# compare bytes: compare_digest raises TypeError on str with non-ASCII characters
return isinstance(header, str) and hmac.compare_digest(expected.encode(), header.encode("utf-8", "replace"))
# created_at from the signed body, not the X-Replyze-Timestamp header
def is_fresh(created_at: str | None, max_age_seconds: int = 300) -> bool:
try:
sent = datetime.fromisoformat(created_at.replace("Z", "+00:00")).timestamp()
except (AttributeError, TypeError, ValueError):
return False
return abs(time.time() - sent) <= max_age_seconds// PHP
function verify_replyze_signature(string $rawBody, mixed $header, string $secret): bool {
return is_string($header) && hash_equals('sha256=' . hash_hmac('sha256', $rawBody, $secret), $header);
}
// $createdAt from the signed body, not the X-Replyze-Timestamp header
function replyze_is_fresh(mixed $createdAt, int $maxAge = 300): bool {
$sent = is_string($createdAt) && preg_match('/^\d{4}-\d{2}-\d{2}T/', $createdAt) ? strtotime($createdAt) : false;
return $sent !== false && abs(time() - $sent) <= $maxAge;
}Complete receivers that do all three steps: Express, Flask, plain PHP. Test vector: secret 9f86d081884c7d659a2feaa0c55ad015 and the body in examples/webhooks/test-body.json give sha256=912da3252eccfa6203a07400fd4a24081c10f35882012b0a50b7b12844a78979. CI starts each of the three receivers on every push and checks that a freshly signed event is handled once, that a wrong, missing or non-ASCII signature gets 401, and that the test body, sent again with a new X-Replyze-Timestamp and X-Replyze-Event-Id, gets 400: its created_at is old.
To try a receiver on your machine, start it with the test secret:
cd examples/webhooks/node-express && npm install
REPLYZE_WEBHOOK_SECRET=9f86d081884c7d659a2feaa0c55ad015 node server.js &and send it an event made and signed just now (the receivers refuse anything older than 5 minutes):
# Send a signed test event
SECRET=9f86d081884c7d659a2feaa0c55ad015
BODY='{"id":"test-'$(date +%s)'","event":"message.created","created_at":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","workspace_id":1,"data":{"message":{"id":501,"conversation_id":88,"sender_type":"visitor","content":"Where is my order?"}}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')
curl -i http://localhost:3000/replyze/webhook \
-H "Content-Type: application/json" \
-H "X-Replyze-Event: message.created" \
-H "X-Replyze-Signature: sha256=$SIG" \
--data-binary "$BODY"The answer is 200 OK and the receiver prints the message. Run only the curl command again and it sends the same event, like a retry: 200, and nothing printed. test-body.json with its test-vector signature gets 400 Too old, however fresh its headers: that is the replay check working. --data-binary sends the bytes as they are; -d would strip line breaks from a file and change the signature.
No-code tools (Zapier, Make, n8n) connect with their HTTP modules: a webhook trigger ("Catch Hook") for events, and HTTP requests with an API key for actions.
Replyze runs a remote MCP server at https://client.replyze.chat/api/mcp (streamable HTTP, authenticated with an API key). It lets Claude, Cursor, VS Code and other MCP clients search and read your conversations, reply to customers, leave internal notes, assign conversations, look up contacts and search your knowledge base; the key's scopes decide which tools the agent gets. In Claude Code, for example:
claude mcp add --transport http replyze https://client.replyze.chat/api/mcp \
--header "Authorization: Bearer $REPLYZE_API_KEY"Setup for Claude Desktop, Cursor, VS Code and other clients: Replyze/replyze-mcp.
A public help center is an MCP server too, with no key: https://client.replyze.chat/api/mcp/kb/<your-help-center-slug> lets anyone's assistant search and read your published articles. See Replyze/knowledge-base-mcp-server.
| Repository | What is inside |
|---|---|
| add-live-chat-to-website | Copy-paste code to add live chat to HTML, WordPress, Shopify, Wix, Webflow, React, Next.js, Vue, Laravel and more |
| react-live-chat | React and Next.js live chat component |
| vue-live-chat | Vue and Nuxt live chat component |
| wordpress-live-chat | WordPress live chat and AI chatbot plugin |
| react-native-live-chat | Live chat and AI support in React Native and Expo apps |
| flutter-live-chat | Live chat and AI support in Flutter apps |
| replyze-mcp | The Replyze MCP server for Claude, Cursor and VS Code |
| knowledge-base-mcp-server | Your public help center as an MCP server, no key needed |
Everything in examples/ is checked on every push (.github/workflows/ci.yml): the spec is linted with Redocly, every example is syntax-checked, and the webhook and identity examples run against the test vectors above. To run the same checks locally (Node.js 18+, Python 3.10+, PHP 8.1+):
npx @redocly/cli lint openapi.json
bash scripts/check-syntax.sh
node --test tests/*.test.mjsThe end-to-end webhook tests start the Express, Flask and PHP receivers; they need npm install in examples/webhooks/node-express and pip install -r examples/webhooks/python-flask/requirements.txt, and run with RUN_RECEIVERS=1 node --test tests/*.test.mjs.
The code in this repository is MIT licensed.