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. 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. 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. 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.

DirectionWhat it isRequired?
You call usPOST /api/integration/token to mint a player token. Authenticated with your integration key, server to server.Only to identify logged-in players
We call youYour platform API, so agents can see balances, redemptions, transactions and recent games, and approve redemptions from the thread.Optional

The three secrets

NameLooks likeWhere it lives
Sluglucky-reefPublic. Goes in the script tag. Lowercase letters, digits and hyphens, 2-40 characters.
Integration keycrm_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.

FieldTypeValidationNotes
Casino slugtext, public^[a-z0-9-]{2,40}$Served to the storefront. The equivalent of a publishable key.
Integration keysecret, write-onlystarts 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 secretsecret, write-only, optional64 hex charactersOnly 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.

AttributeRequiredMeaning
srcyeshttps://support.pryzr.tech/widget.js
data-brandyesThe casino slug. Defaults to demo if omitted, which is almost never what you want.
data-player-tokennoSigned token for the logged-in player. Omit it and everyone chats as a guest. See Player tokens.
data-colornoFallback launcher colour, used only until the portal settings load. Hex, e.g. #0f766e.
data-title, data-greetingnoFallback header text. The portal wins once it loads.
asyncrecommendedNothing 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.

ReasonMeans
formatNot two base64url parts joined by a dot.
payloadFirst part is not base64url-encoded JSON. Usually padding, or a non-URL-safe alphabet.
signatureHMAC mismatch. Wrong secret, or you signed the JSON instead of the encoded text.
subPayload has no player id.
expPayload has no expiry.
expiredExpiry is in the past. Mint a fresh one on page load.
no_secretThis 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.

Authauthorization: Bearer <integration key>
Bodyid (required), name, email, ttl
200{ token, expires_at, expires_in }
400Missing player id.
401Missing or invalid integration key.
405You sent GET.
CORSNone, by design. Not callable from a browser.

GET /api/widget/config

Launcher appearance for a casino. Called by widget.js.

Querybrand=<slug>
200{ brand, launcher }, cached 30s at the edge.
403The calling site is not on the casino's allowed list.
404Unknown casino slug.

POST /api/widget/session

Start or resume a visitor's conversation. Returns up to the last 200 messages.

Bodybrand, token (previous visitor token), playerToken, pageUrl
200{ token, player, brand, messages }
403Site not allowed.
404Unknown casino.
429Too 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.

Authx-visitor-token: <uuid>
GET?after=<ISO timestamp>, returns { messages }
POST{ body }, max 4000 characters, returns { message }
400Empty message.
401Missing or unknown visitor token.
429More 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.

EndpointPurpose
GET /players/{id}Profile, status, KYC, balances, lifetime totalsrequired
GET /players/{id}/redemptionsRecent redemptions, newest firstoptional
POST /players/{id}/redemptions/{rid}/approveApprove one pending redemptionoptional
GET /players/{id}/transactionsPurchases, bonuses, adjustmentsoptional
GET /players/{id}/gamesRecent roundsoptional
GET /players/search?q=Find players by name, email or id (max 20). Powers the inbox's player search.v2
GET|POST /players/{id}/notesStaff notes, newest first; POST adds onev2
POST /players/{id}/block · /unblockBlock the account with a reason, or lift the blockv2
POST /players/{id}/breakResponsible-play break, 1 to 90 daysv2
POST /players/{id}/adjustGC or SC ledger adjustment with a reason (we cap it at ±10,000 SC / ±10,000,000 GC per call)v2
POST /players/{id}/emailResend the verify, w9 or reset emailv2
GET /players/{id}/timelinePurchases, redemptions, adjustments, blocks, notes and KYC changes, newest firstv2

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"
}
CreateFirst call for a slug. Makes the casino (adapter http), its settings and secrets. Only slug and name are required.
UpdateEvery 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.
policiesPlain 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_emailInvited if they have no login, then made the casino's owner: portal access, the inbox, uncapped approvals and every agent right.
400Validation, with the field named in the message.
401Bad platform key.
409The 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

EventWhenExtra fields
chat.startedA visitor opens a new conversation.identified (boolean)
chat.waitingA 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.resolvedAn agent closes the conversation.messages (count), opened_at
redemption.approvedAn agent approves a redemption from the player panel. Only successful approvals.redemption_id, amount, currency, approved_by
webhook.testThe 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.

GuaranteeWhat it means for your handler
At least onceA retry can arrive after your handler already succeeded but the answer was lost. Make the handler idempotent.
One per occurrenceEach real-world event is queued once, so a conversation never produces two chat.started rows however many times the scan runs.
Not orderedA retried chat.started can land after chat.resolved. Use occurred_at, not arrival order.
One endpoint per casinoScoped 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

LimitValueApplies to
New chats per casino12 per hourPer visitor address. Guests only.
New chats overall30 per hourPer visitor address, across all casinos.
Messages20 per minutePer conversation, visitor messages.
Message length4000 charactersLonger is truncated.
Token TTL60s to 24h, default 1hValues outside the range are clamped.
History returnedLast 200 messagesOn session start.
Allowed websites20 per casinoSubdomains of a listed host are included.
Player id / name / email100 / 100 / 200 charsTruncated, 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" }
StatusMeaningWhat to do
400Bad input -- missing player id, empty message.Fix the request body.
401Bad integration key, or unknown visitor token.Check the key. A visitor token expires with the conversation.
403This website is not on the casino's allowed list.Add the domain in the portal. The widget removes itself from the page.
404Unknown casino slug.Check data-brand.
429Rate limited.Back off. See Limits.
500Our 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

SymptomCause
Everyone appears as a guestThe 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 appearsEither 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 expectThe allowed list is empty, which means allow everywhere. Add the real domains.
Works locally, 403 in productionlocalhost is allowed as a host but your production domain has not been added.
Player panel is empty for a signed-in playerThe connector is not configured, or GET /players/{id} returned a non-200. Press Check the connection.
Token works, then stops after an hourDefault 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.