Integration guide and API reference
Put live chat on a casino site.
One script tag puts a chat bubble on the site. Players talk to your agents in a single inbox. Optionally tell us who is logged in, and optionally let us read balances and redemptions from your platform.
Base URL https://support.pryzr.tech
Quickstart
Three steps. Step 1 gets you a working chat for anonymous visitors; steps 2 and 3 are optional and can come later.
- 1
Paste the tag
Put this before the closing </body> tag on every page that should show the bubble. Replace your-casino with the casino's slug from the owner portal.
<script src="https://support.pryzr.tech/widget.js"
data-brand="your-casino"
async></script>
That is a complete, working integration. Everything else -- colours, wording, the AI assistant, policies -- is configured in the owner portal with nothing to redeploy.
- 2
Identify the logged-in player
Ask us for a short-lived token from your server, then hand it to the tag. This is what lets an agent see who they are talking to. Guests can always chat without it.
curl -X POST https://support.pryzr.tech/api/integration/token \
-H "authorization: Bearer $PRYZR_INTEGRATION_KEY" \
-H "content-type: application/json" \
-d '{"id":"player-123","name":"Maya","email":"maya@example.com"}'
# {"token":"eyJzdWIi....signature","expires_at":"2026-09-19T15:34:51Z","expires_in":3600}
<script src="https://support.pryzr.tech/widget.js"
data-brand="your-casino"
data-player-token="eyJzdWIi....signature"
async></script>
- 3
Lock it to your domains
In the owner portal, add the casino's websites to the allowed list. Until you do, the widget works on any site that pastes the tag. An empty list means wide open, not locked.
How it fits together
There are two separate API directions. Keeping them straight saves a lot of confusion.
| Direction | What it is | Required? |
|---|
| You call us | POST /api/integration/token to mint a player token. Authenticated with your integration key, server to server. | Only to identify logged-in players |
| We call you | Your platform API, so agents can see balances, redemptions, transactions and recent games, and approve redemptions from the thread. | Optional |
The three secrets
| Name | Looks like | Where it lives |
|---|
| Slug | lucky-reef | Public. Goes in the script tag. Lowercase letters, digits and hyphens, 2-40 characters. |
| Integration key | crm_lucky-reef_9f2c... | Secret. Server only. Mints player tokens. Never put it in a browser. We store only its SHA-256 hash, so a lost key cannot be recovered, only replaced. |
| Signing secret | (32 bytes) | Secret. Only needed if you sign tokens yourself instead of calling us. Server only. |
All three are per casino. Nothing is shared between casinos, including player identity: the same person at two casinos is two unrelated contacts.
Read this first if you run many brands
Multi-tenant launchers
Everything is already scoped per casino, so running many brands through one launcher works. What is worth knowing before you build:
- One tenant = one casino = one slug. Each has its own theme, wording, policies, AI instructions, allowed domains, integration key, signing secret and agent access list.
- Player ids are scoped to the casino. We key a contact on
(casino, your player id). Reusing player-123 across two tenants creates two separate people, which is what you want. - One tag per site. The launcher templates the slug and the per-request player token into the page. Nothing else changes between tenants.
- Agents are assigned per casino. An agent sees only the casinos they have been given, which is how one support team covers many brands without leaking between them.
Credentials are per tenant, entered once
There is no platform-wide key. Each casino has its own slug and its own integration key, exactly like a per-tenant Clerk or Finix configuration. A launcher stores both against the tenant and templates them in; nothing else changes between brands.
For platform and white-label launchers
Adding Engage to a launcher
If your launcher has a provider settings screen -- the kind where you paste a Clerk secret key or Finix merchant credentials per tenant -- Engage drops in the same way. Three fields, one of them optional.
| Field | Type | Validation | Notes |
|---|
| Casino slug | text, public | ^[a-z0-9-]{2,40}$ | Served to the storefront. The equivalent of a publishable key. |
| Integration key | secret, write-only | starts crm_<slug>_ | Server side only. Store it write-only and show configured .... with a Replace button; we only keep its hash, so it can never be read back from us either. |
| Signing secret | secret, write-only, optional | 64 hex characters | Only if you mint tokens yourself instead of calling us. Leave it empty otherwise -- most launchers never need it. |
Both values come from the owner portal: create the casino, then Install tab, then create an integration key. It is shown once.
What the storefront renders
<script src="https://support.pryzr.tech/widget.js"
data-brand="{casino_slug}"
data-player-token="{token}"
async></script>
What your server calls
POST https://support.pryzr.tech/api/integration/token
authorization: Bearer {integration_key}
content-type: application/json
{"id": "<your player id>", "name": "...", "email": "..."}
Auth is a static bearer token, so it fits anywhere an API-key provider already fits. There is no OAuth flow and no token refresh to manage.
The step that must not be skipped
A new casino starts with an empty allowed-websites list, and empty means the widget works on any site, not none. Put that in your card's help text. If your launcher already knows each tenant's storefront domain, the safest flow is to set it in the portal immediately after creating the casino.
Staging and production
There is no sandbox/live switch on a casino. If you need a staging environment, make a second casino -- lucky-reef-staging -- with its own key and its own allowed domains. It is a real casino with real conversations, just one nobody points a production storefront at. Every casino also gets https://support.pryzr.tech/try/<slug>, a hosted page running its real widget, which covers most of what you would use a sandbox for.
Getting told when something happens
We POST to one HTTPS address per tenant with HTTP Basic auth, in the same shape your launcher already uses for its other providers. The owner sets it in the portal. See Webhooks.
Doing it unattended
A launcher that runs many casinos does not need a human in the portal. With one platform-level key it creates the casino, sets its domains, connector, webhook and policies, and invites agents, all in two calls. See Provisioning API.
The script tag
The loader is a single file with no dependencies. It renders the launcher button in a shadow root, so it cannot inherit or leak your site's CSS, and it only loads the chat window itself when someone opens the chat (or has an existing conversation). A page view with no chat costs one cached request.
| Attribute | Required | Meaning |
|---|
src | yes | https://support.pryzr.tech/widget.js |
data-brand | yes | The casino slug. Defaults to demo if omitted, which is almost never what you want. |
data-player-token | no | Signed token for the logged-in player. Omit it and everyone chats as a guest. See Player tokens. |
data-color | no | Fallback launcher colour, used only until the portal settings load. Hex, e.g. #0f766e. |
data-title, data-greeting | no | Fallback header text. The portal wins once it loads. |
async | recommended | Nothing on the page waits for the widget. |
The tag is safe to include more than once by accident -- the loader guards against double-mounting.
Browser API
For single-page apps, call these instead of reloading when a player signs in or out. Calls made before the widget finishes loading are queued, so you never have to wait for a ready event.
window.PryzrEngage.identify(token) // sign a player in, or identify(null) to sign out
window.PryzrEngage.open() // open the chat window
window.PryzrEngage.close() // close it
// window.CRMWidget is kept as an alias for older snippets.
Events
The chat window posts messages to the host page. Listen if you want to react, for example to hide your own help button while the chat is open.
window.addEventListener("message", (e) => {
const type = e.data && e.data.type;
if (type === "crm-widget:opened") {} // chat window opened
if (type === "crm-widget:closed") {} // closed
if (type === "crm-widget:unread") { e.data.count } // unread reply count
if (type === "crm-widget:ready") {} // chat window booted
if (type === "crm-widget:state") { e.data.hasChat } // this visitor has a conversation
});
Player tokens
A player token tells us which of your players is chatting. It is signed, short-lived, and minted on your server for the current request. There are two ways to get one.
Option A: ask us (recommended)
No crypto on your side. Your server posts the player to us with the integration key and gets a token back.
POST https://support.pryzr.tech/api/integration/token
authorization: Bearer <integration key>
content-type: application/json
{
"id": "player-123", // required, your own player id, max 100 chars
"name": "Maya Thompson", // optional, max 100 chars
"email": "maya@example.com", // optional, max 200 chars
"ttl": 3600 // optional seconds, default 3600, clamped 60..86400
}
200 OK
{
"token": "eyJzdWIiOiJwbGF5ZXItMTIzIiwiZXhwIjoxNzg5...signature",
"expires_at": "2026-09-19T15:34:51Z",
"expires_in": 3600
}
This endpoint sends no CORS headers on purpose. A browser cannot call it, which means a leaked key cannot be used from a page. sub is accepted as an alias for id.
Option B: sign it yourself
One HMAC, no network call to us. Use the casino's signing secret from the portal.
payload = base64url(JSON) // no padding, URL-safe alphabet
signature = base64url(HMAC_SHA256(payload, signing_secret))
token = payload + "." + signature
The payload:
{
"sub": "player-123", // required, your player id
"exp": 1789800000, // required, Unix seconds when it stops working
"name": "Maya Thompson", // optional
"email": "maya@example.com"// optional
}
// Node, no dependencies
const crypto = require("crypto");
const b64 = (b) => Buffer.from(b).toString("base64url");
function playerToken(secret, player, ttl = 3600) {
const payload = b64(JSON.stringify({
sub: player.id,
name: player.name,
email: player.email,
exp: Math.floor(Date.now() / 1000) + ttl,
}));
const sig = b64(crypto.createHmac("sha256", secret).update(payload).digest());
return payload + "." + sig;
}
The one mistake everybody makes: sign the base64url text of the payload, not the raw JSON. The signature is over the exact string that becomes the first part of the token.
Why a token gets rejected
The token checker in the portal returns one of these reasons. Note the important behaviour below the table.
| Reason | Means |
|---|
format | Not two base64url parts joined by a dot. |
payload | First part is not base64url-encoded JSON. Usually padding, or a non-URL-safe alphabet. |
signature | HMAC mismatch. Wrong secret, or you signed the JSON instead of the encoded text. |
sub | Payload has no player id. |
exp | Payload has no expiry. |
expired | Expiry is in the past. Mint a fresh one on page load. |
no_secret | This casino has no signing secret yet. |
A bad token does not raise an error. The chat silently falls back to an anonymous guest. This is deliberate -- a broken token must never stop a player getting help -- but it means a misconfigured integration looks like it is working while no agent can see who anyone is. If players are showing up as guests, check the token in the portal before looking anywhere else.
API reference
One endpoint is for you. The other three are what the widget itself calls -- documented so you can debug what you see in the network tab, not because you need to call them.
POST /api/integration/token
Mint a player token. Server to server. This is the one you call.
| Auth | authorization: Bearer <integration key> |
|---|
| Body | id (required), name, email, ttl |
|---|
| 200 | { token, expires_at, expires_in } |
|---|
| 400 | Missing player id. |
|---|
| 401 | Missing or invalid integration key. |
|---|
| 405 | You sent GET. |
|---|
| CORS | None, by design. Not callable from a browser. |
|---|
GET /api/widget/config
Launcher appearance for a casino. Called by widget.js.
| Query | brand=<slug> |
|---|
| 200 | { brand, launcher }, cached 30s at the edge. |
|---|
| 403 | The calling site is not on the casino's allowed list. |
|---|
| 404 | Unknown casino slug. |
|---|
POST /api/widget/session
Start or resume a visitor's conversation. Returns up to the last 200 messages.
| Body | brand, token (previous visitor token), playerToken, pageUrl |
|---|
| 200 | { token, player, brand, messages } |
|---|
| 403 | Site not allowed. |
|---|
| 404 | Unknown casino. |
|---|
| 429 | Too many new chats from this address. |
|---|
GET POST /api/widget/messages
Poll for replies, or send one. Authenticated with the visitor token from the session call.
| Auth | x-visitor-token: <uuid> |
|---|
| GET | ?after=<ISO timestamp>, returns { messages } |
|---|
| POST | { body }, max 4000 characters, returns { message } |
|---|
| 400 | Empty message. |
|---|
| 401 | Missing or unknown visitor token. |
|---|
| 429 | More than 20 messages a minute in one conversation. |
|---|
Your platform API (optional)
Expose these and an agent sees the player's balances, redemptions, transactions and recent games beside the conversation, and can approve a redemption without leaving it. You enter the base URL and an API key in the owner portal; we send the key as authorization: Bearer <key>.
Only the first is required. Skip the rest and those panels are simply empty -- nothing breaks.
| Endpoint | Purpose | |
|---|
GET /players/{id} | Profile, status, KYC, balances, lifetime totals | required |
GET /players/{id}/redemptions | Recent redemptions, newest first | optional |
POST /players/{id}/redemptions/{rid}/approve | Approve one pending redemption | optional |
GET /players/{id}/transactions | Purchases, bonuses, adjustments | optional |
GET /players/{id}/games | Recent rounds | optional |
GET /players/search?q= | Find players by name, email or id (max 20). Powers the inbox's player search. | v2 |
GET|POST /players/{id}/notes | Staff notes, newest first; POST adds one | v2 |
POST /players/{id}/block · /unblock | Block the account with a reason, or lift the block | v2 |
POST /players/{id}/break | Responsible-play break, 1 to 90 days | v2 |
POST /players/{id}/adjust | GC or SC ledger adjustment with a reason (we cap it at ±10,000 SC / ±10,000,000 GC per call) | v2 |
POST /players/{id}/email | Resend the verify, w9 or reset email | v2 |
GET /players/{id}/timeline | Purchases, redemptions, adjustments, blocks, notes and KYC changes, newest first | v2 |
v2 rows are optional too. They unlock the matching buttons in the player panel for agents who hold the right (can_manage_players for notes, blocks, breaks and emails; can_adjust_balances for adjustments). Every write carries idempotency-key: crm-<action>-<uuid> and a JSON body whose by is the agent's display name. Answer a non-2xx with {"error": "message"} and the agent reads that message.
{id} is your own player id -- the same value you put in the token as sub. The approve call must be idempotent: we send an idempotency-key header and may retry. Return 409 if the redemption is no longer pending.
Required response shape
GET /players/player-123
{
"id": "player-123",
"name": "Maya Thompson",
"email": "maya@example.com",
"status": "active", // active | closed | self-excluded
"kyc_status": "verified",
"joined_at": "2025-11-02T10:04:00Z",
"last_login_at": "2026-09-19T08:12:00Z",
"state": "TX",
"balances": {
"gold_coins": 150237,
"sweeps_coins": 205.58,
"redeemable_sc": 275.55
},
"lifetime": { "purchases_usd": 459.90, "redeemed_usd": 350.00 },
// v2, all optional. Send what you have; the panel shows what it gets.
"phone": "+1 555 010 1234",
"vip_level": 2,
"flags": { "blocked": false, "block_reason": null, "self_excluded_until": null,
"on_break_until": null, "kyc_note": null },
"limits": { "daily_usd": 200, "weekly_usd": null, "monthly_usd": 1000 },
"tax": { "w9_status": "on_file", // none | requested | on_file
"ytd_prizes_usd": 350.00 },
"notes_count": 2,
"tags": ["vip", "imported"]
}
The full contract, including redemption, transaction and game-round schemas, is in the OpenAPI 3.1 spec. Generate a server stub from it, point the portal at your base URL, then press Check the connection -- it tests each endpoint separately and tells you exactly what is missing or malformed.
For launchers that run many casinos
Provisioning API
One platform-level key, two endpoints. Your launcher creates a casino, keeps it up to date and manages who may work its inbox, with nobody signing in to the portal. Ask us for the key; it is per platform, not per casino, and belongs on your server only.
POST /api/platform/brands
Create a casino, or update one you created. Idempotent on slug.
POST https://support.pryzr.tech/api/platform/brands
authorization: Bearer {platform_key}
content-type: application/json
{
"slug": "prizeparadice", // required; ^[a-z0-9-]{2,40}$
"name": "Prize Paradice", // required on create
"color": "#e11d48",
"logo_url": "https://prizeparadice.com/brand-assets/img/logo.png",
"domains": ["prizeparadice.com", "prizeparadice.pryzr.xyz"],
"connector": { "base_url": "https://prizeparadice.com/api/crm/prizeparadice", "api_key": "pcrm_..." },
"webhook": { "url": "https://prizeparadice.com/api/crm/prizeparadice/webhooks",
"username": "...", "password": "..." },
"policies": { "terms": "...plain text...", "rules": "...", "privacy": "...", "responsible_play": "..." },
"support_email": "support@prizeparadice.com",
"owner_email": "owner@prizeparadice.com"
}
200
{
"brand_id": "uuid",
"slug": "prizeparadice",
"widget_signing_secret": "...", // same value on every call; never rotated here
"script_url": "https://support.pryzr.tech/widget.js",
"portal_url": "https://support.pryzr.tech/portal",
"inbox_url": "https://support.pryzr.tech/inbox"
}
| Create | First call for a slug. Makes the casino (adapter http), its settings and secrets. Only slug and name are required. |
|---|
| Update | Every later call is a partial update: only the keys you send change. Re-POST {slug, name, policies} to refresh the AI's policies and nothing else. An explicit null clears connector, webhook or logo_url. |
|---|
| policies | Plain text or Markdown, up to 60 KB each. They feed the widget's Help & rules list and the AI assistant, so it answers from the real rules. Policies the owner added in the portal are left alone. |
|---|
| owner_email | Invited if they have no login, then made the casino's owner: portal access, the inbox, uncapped approvals and every agent right. |
|---|
| 400 | Validation, with the field named in the message. |
|---|
| 401 | Bad platform key. |
|---|
| 409 | The slug belongs to a casino that was created in the portal, not by your platform. |
|---|
POST /api/platform/brands/{slug}/agents
Invite or update a person who works this casino's inbox. Idempotent.
POST https://support.pryzr.tech/api/platform/brands/prizeparadice/agents
authorization: Bearer {platform_key}
content-type: application/json
{ "email": "rep@prizeparadice.com", "name": "Sam",
"can_approve_redemptions": true, "can_manage_players": true, "can_adjust_balances": false,
"approval_limit": 300 } // optional, USD
200 { "ok": true, "invited": true, "user_id": "uuid", "display_name": "Sam",
"can_approve_redemptions": true, "can_manage_players": true, "can_adjust_balances": false,
"approval_limit": 300 }
Someone with no login gets an invite email and chooses a password; someone who already has one is granted straight away. Rights map to what your roles mean: owner/manager → all three, support → manage players + approve, viewer → do not call this at all.
DELETE /api/platform/brands/{slug}/agents
Body { "email" }. Takes this casino away from that person. Their login and other casinos are untouched. 200 { ok, revoked }; revoked is false when there was nothing to remove.
All three answer 404 for an unknown slug and 409 for a casino your platform did not create. No CORS headers: server to server only. Every call is written to the Engage audit log as actor platform.
Webhooks
Chat is the one part of a casino that nobody can poll for. Webhooks let us tell you instead: we POST a small JSON body to one HTTPS address per casino when something happens. The owner sets the address in the portal under Webhooks. There is nothing to configure in code, and nothing is ever sent from the browser.
Same shape as your other providers
One URL per tenant, HTTP Basic auth, a static password. If your platform already receives /api/v1/<provider>/webhooks/<tenant-slug> from someone else, point us at the same shape and reuse the handler.
The events
| Event | When | Extra fields |
|---|
chat.started | A visitor opens a new conversation. | identified (boolean) |
chat.waiting | A player's message has gone unanswered past the casino's threshold (default 3 minutes) and no agent has the inbox open. This is the one to wire to your alerting. | waiting_since, waiting_minutes |
chat.resolved | An agent closes the conversation. | messages (count), opened_at |
redemption.approved | An agent approves a redemption from the player panel. Only successful approvals. | redemption_id, amount, currency, approved_by |
webhook.test | The owner pressed “Send a test event” in the portal. Never fired by real activity. | message |
What a delivery looks like
POST https://api.yourplatform.com/api/v1/pryzr/webhooks/lucky-reef
content-type: application/json
authorization: Basic bXl1c2VyOm15cGFzcw==
user-agent: PryzrEngage-Webhook/1
{
"event": "chat.waiting",
"occurred_at": "2026-01-31T14:02:11Z",
"casino_slug": "lucky-reef",
"conversation_id": "3f7c9a12-1f4e-4a55-9d2e-0b6f8c1d7e40",
"player_id": "player-123",
"waiting_since": "2026-01-31T13:58:40Z",
"waiting_minutes": 3
}
Every body carries event, occurred_at (UTC, ISO 8601), casino_slug and conversation_id. player_id is your own id for the player -- the same value you put in sub when you minted the token -- and is null for a guest.
No message text, ever. A webhook body carries ids, counts and times. If you want to read what was said, open the conversation in the inbox. That keeps player chat out of your logging pipeline by default.
Answering
Reply with any 2xx. Your body is ignored, so an empty 200 is ideal. Anything else -- including a timeout after 8 seconds -- counts as a failure. Failures are retried at 1, 2, 4, 8 and 16 minutes, six attempts in total, then dropped. The portal shows the last status, the last error and the ten most recent deliveries.
| Guarantee | What it means for your handler |
|---|
| At least once | A retry can arrive after your handler already succeeded but the answer was lost. Make the handler idempotent. |
| One per occurrence | Each real-world event is queued once, so a conversation never produces two chat.started rows however many times the scan runs. |
| Not ordered | A retried chat.started can land after chat.resolved. Use occurred_at, not arrival order. |
| One endpoint per casino | Scoped like everything else. A launcher registers the same URL shape per tenant and reads casino_slug or the path to tell them apart. |
Rules for the URL
https:// only, on a public hostname. Loopback, .local and private ranges (10.x, 192.168.x, 172.16-31.x, 169.254.x) are rejected when you save.- It cannot point back at
https://support.pryzr.tech. Our own endpoints create the records that fire events, so that would loop. - Basic auth is optional but recommended. We never send your password anywhere else, and the portal will not read it back to you -- only replace it.
Checking it works
Save the address, then press Send a test event in the portal. It posts a webhook.test body immediately -- even while delivery is switched off -- and the response code appears in the panel a second or two later. That verifies DNS, TLS, your auth and your handler in one click, before a real player is involved.
Limits
| Limit | Value | Applies to |
|---|
| New chats per casino | 12 per hour | Per visitor address. Guests only. |
| New chats overall | 30 per hour | Per visitor address, across all casinos. |
| Messages | 20 per minute | Per conversation, visitor messages. |
| Message length | 4000 characters | Longer is truncated. |
| Token TTL | 60s to 24h, default 1h | Values outside the range are clamped. |
| History returned | Last 200 messages | On session start. |
| Allowed websites | 20 per casino | Subdomains of a listed host are included. |
| Player id / name / email | 100 / 100 / 200 chars | Truncated, not rejected. |
Identified players are not subject to the new-chat limits -- those exist to stop anonymous flooding, and a signed token already proves the player is real.
Errors
Every error is JSON with a single human-readable field.
{ "error": "that integration key is not valid" }
| Status | Meaning | What to do |
|---|
400 | Bad input -- missing player id, empty message. | Fix the request body. |
401 | Bad integration key, or unknown visitor token. | Check the key. A visitor token expires with the conversation. |
403 | This website is not on the casino's allowed list. | Add the domain in the portal. The widget removes itself from the page. |
404 | Unknown casino slug. | Check data-brand. |
429 | Rate limited. | Back off. See Limits. |
500 | Our fault. | Retry once, then tell us. |
Testing
- Sandbox. Every casino gets
https://support.pryzr.tech/try/<slug> -- a pretend casino page on our servers running that casino's real widget, with buttons to switch between a guest and a signed-in player and a live event log. Safe to send to a developer before anything is installed. - Token checker. Paste a token your server minted into the portal's Install tab. It tells you whether it is valid and, if not, exactly which of the reasons above applies.
- Connection check. Tests each of your platform endpoints and reports them separately.
- Test webhook. The Webhooks tab posts a
webhook.test body to your endpoint on demand and shows the status code it answered with, so you can prove DNS, TLS, auth and your handler before a real player is involved. - Setup checklist. The Install tab shows what we have actually observed: whether the widget has been seen on a real page, whether a token has been verified, whether the connector answered.
Troubleshooting
| Symptom | Cause |
|---|
| Everyone appears as a guest | The token is invalid and falling back silently. Check it in the portal. Most often the HMAC was computed over the JSON instead of the base64url text. |
| No bubble appears | Either the slug is wrong (404) or the site is not on the allowed list (403, and the widget removes itself). Check the network tab for /api/widget/config. |
| Bubble appears on a staging site you did not expect | The allowed list is empty, which means allow everywhere. Add the real domains. |
| Works locally, 403 in production | localhost is allowed as a host but your production domain has not been added. |
| Player panel is empty for a signed-in player | The connector is not configured, or GET /players/{id} returned a non-200. Press Check the connection. |
| Token works, then stops after an hour | Default TTL is 3600s. Mint a fresh token on each page load rather than caching one. |
Still stuck?
Open the sandbox for the casino, reproduce it there, and send us the slug and roughly when it happened. We can see the same requests from our side.