Merchant Quick Start: Your First Live Chat
Building with an AI coding assistant? Use the website support chat prompt with this guide.
Connect a signed-in website customer to a human operator in the hosted Open4X Conversation Hub. Start with text chat only; AI, Telegram and ticket synchronization are separate integrations. Last reviewed: September 14, 2026.
::: important Before you start This is a low-code integration, not a copy-and-paste-only setup. Your developer must implement a protected server-side Session endpoint. Registration, a loader script, or creating a Bot Service alone is not enough. Feature deployment is not acceptance for your merchant account: test the actual website and tenant before opening access to customers. :::
1. Register and Prepare
Register at Open4X, then open the Console. Prepare your registration email, merchant name, HTTPS website/test-page URL, website framework, developer contact, stable website user IDs, operators and fallback contact channel. Do not share your password.
Your merchant account and your website customers are different identities. Start with authenticated website users. Anonymous support requires a server-verifiable guest session, not a browser-supplied arbitrary user ID.
The Conversation Hub is empty until conversations are created. AI and Telegram are not prerequisites for this flow.
2. Confirm the Environment
| Setting | Production |
|---|---|
| Console | https://console.open4x.com |
| Workbench | https://console.open4x.com/dashboard/conversations |
| API base URL | https://api.open4x.com |
| Widget page | https://widget.open4x.com |
| Loader | https://widget.open4x.com/widget.js |
Confirm the authorized test environment with your integration contact. Staging requires the complete staging set of credentials and URLs supplied in your package. Do not mix environments or substitute production when a staging hostname fails. This guide uses Conversation Hub, not legacy /v1/apps/bot/... Session APIs.
3. Obtain a Dedicated Bridge Key
Minimum server-side scopes are conversation:read and conversation:write.
On the API Keys page, click Create New Key, enter a name, select conversation:read and conversation:write, then click Create Key. No scopes are selected by default; at least one is required. Add conversation:events:write only when managing event webhooks or replay. bot:send is not a substitute for conversation scopes; leave unrelated permissions unchecked.
Existing keys are not changed automatically. Create a dedicated conversation key, update and verify your server configuration, then revoke the old key if no longer needed.
Confirm tenant, environment, expiry, scopes, requests per minute, concurrency, daily quota, source/IP policy and cost ceiling. There is no universal free quota implied by this guide. Deliver the key securely, preferably directly into your server's Secrets, never through ordinary chat, screenshots, source control or browser code.
Store OPEN4X_API_BASE=https://api.open4x.com and OPEN4X_BRIDGE_KEY server-side. Do not use public build variables such as VITE_ or NEXT_PUBLIC_ for secrets. An IP allowlist uses your server's egress IP, not the visitor's IP. A website domain restriction does not replace key protection.
From the server, call GET /v1/conversations/credentials/status with Authorization: Bearer <Bridge Key> and verify its policy metadata. Request conversation:events:write only when adding your own event integration. Basic chat does not need AI scopes or browser supervision credentials.
4. Implement Your Session Endpoint
First select the intended entry-point contract: customer consultation, group agents and merchant administrators need different Sessions. Copy the customer checklist or agent checklist to review an existing backend. Do not issue the account's highest privilege to every page.
Your developer implements POST /api/open4x/session on your website. Open4X does not host that merchant endpoint. Authenticate the visitor, enforce your CSRF/origin and rate-limit policies, and derive identity from your server-side session. The following examples are server-to-server requests, not browser calls using the Bridge Key.
Create or Reuse a Conversation
Call POST /v1/conversations with:
{
"external_conversation_id": "website:support:site-user-123",
"conversation_type": "general_support",
"participants": [
{ "external_participant_id": "site-user-123", "role": "customer", "display_name": "Website customer" },
{ "external_participant_id": "merchant-support", "role": "support_agent", "display_name": "Merchant support" }
]
}Replace the user placeholder per authenticated visitor. This naming rule reuses one general consultation per customer. Add a site prefix for multiple sites, or a stable ticket ID for separate cases; do not generate a new random business ID on every page load.
Read the conversation ID and participants from data. Match exactly one active customer and support participant by external ID and role. Stop if a required participant is missing, ambiguous or inactive; never fall back to broadcasting. Use returned Open4X participant IDs, not your external IDs.
Issue a Short-Lived Token
Call POST /v1/conversations/{id}/widget-session with:
{
"external_user_id": "site-user-123",
"user_name": "Website customer",
"participant_id": "<returned customer participant ID>",
"recipient_participant_ids": ["<returned support participant ID>"],
"ttl_seconds": 1800
}Choose roles and recipients server-side. Return only the short-lived data.session_token and data.expires_in to the current visitor, for example { "data": { "session_token": "<token>", "expires_in": 1800 } }. Set Cache-Control: no-store. Never log tokens or share personalized HTML through a public cache.
TTL supports 900–3600 seconds. Reauthenticate before obtaining a replacement token. Destroy the old widget on logout or account switching. The minimal flow can reuse existing identity data without a dedicated Open4X database table; synchronization and compensation require durable storage later.
5. Mount the Website Widget
For multiple previous conversations, see Customer Conversation List, including message excerpts, unread counts and read receipts. This extension is deployed to the production domains and requires a merchant customer-session endpoint; this section remains the single-chat flow.
For server-rendered HTML, insert a safely attribute-escaped, dynamically issued token:
<script
src="https://widget.open4x.com/widget.js"
data-token="SERVER_ISSUED_SESSION_TOKEN"
data-widget-url="https://widget.open4x.com"
data-gateway-url="https://api.open4x.com">
</script>For single-page applications, call your Session endpoint first and initialize the component with its response. Obtain a confirmed SDK release and checksums from your integration contact; do not assume a public npm release or treat a local preview as the production package. See the developer integration guide.
Allow the loader's script origin and Widget iframe origin in CSP. Configure HTTPS/WSS API connect-src where requests actually originate. Merchant Session CORS, cookies and CSRF remain your responsibility. Do not disable CSP or enable unrestricted origins to work around errors. Pinned assets, SRI and browser compatibility must be specified in the delivery package; widget.js is not itself an immutable version.
Checkpoint: the chat launcher opens, a test message sends, and browser requests do not contain the Bridge Key.
6. Reply From the Workbench
- Send a message from the website.
- Open Conversation Hub under the same tenant/team as the Bridge Key.
- Select the conversation and choose Join. Use Take over only for exclusive support handling.
- Choose Public reply, select the customer recipient, and send.
- Verify the reply appears in the customer's original website conversation.
- If you took control, Release when finished. Closing the browser does not release control.
Internal notes are not customer replies. Selecting all participants is not private multi-party routing. The hosted administrator workbench polls for messages approximately every three seconds; this is not a delivery SLA.
Start with the merchant owner. Later, invite colleagues and assign separate team roles instead of sharing passwords. conversation:supervise exposes tenant-wide conversations and notes and must not be granted to website customers or creators. See administration.
7. Accept the Integration
| Test | Pass condition |
|---|---|
| Website message and operator reply | Both arrive in the same conversation with correct recipients |
| Refresh and re-login | History resumes according to your business rules; no accidental new conversation |
| Disconnect and reconnect | History recovers without duplicate display |
| Two separate customers | Neither can access the other's conversation |
| Internal note | Does not appear in the customer Widget |
| Expiry, logout, account switching | Authentication is renewed or old UI closed; no identity reuse |
| Open4X outage | Login, orders and payments continue; a fallback contact channel remains |
| AI disabled | Human chat works without sending data to a model |
Record environment, date, responsible staff, conversation IDs, failure request IDs and conclusions. Redact screenshots. Do not include full tokens, keys or private customer content. HTTP 200 and health checks do not replace acceptance.
8. Troubleshooting
Use the prompt for the failing entry: customer, website agent, merchant administrator/Console, or loading/origin/version. Require the sanitized evidence record, separating confirmed causes from hypotheses. Customer recipient controls suggest a credential/entry mismatch. Same-tag missing chats require checking actual group grants and support routing, not just metadata tags.
| Symptom | Check |
|---|---|
| Missing scope checkboxes | Open the production Console and hard-refresh; create a dedicated key as described in step 3 |
| Empty workbench | Conversation creation, matching tenant/environment and list filters |
| Permission denied | Team role; participant access is not tenant administrator access |
| Reply unavailable | Joined status, text, synchronization, competing controller and public recipient selection |
| 401/403 | Merchant login, Key scope/source policy, or expired Widget token; do not broaden privileges |
| 409 | Changed idempotency payload or stale control revision; do not retry blindly |
| 429 | Actual Key rate/concurrency/daily limits; honor Retry-After |
| CORS or blank Widget | Session endpoint, HTTPS, environment URLs, cookies and CSP; never expose the Key to bypass errors |
| New conversation after refresh | Unstable external conversation or user IDs |
9. Merchant Handover Checklist
Confirm and record: merchant email and tenant/team; integration contact; environment and URLs; secure key delivery, scopes, expiry and source policy; quotas and cost ceiling; SDK/Loader release and checksums; Session endpoint owner; fallback contact channel; operators; acceptance results; and contractual retention, deletion, region, DPA, pricing and SLA. Unconfirmed fields are not promises.
Add order support, Telegram, files, multi-party routing, AI or ticket synchronization only after this flow passes. Order support needs server-side order authorization; ticket synchronization needs verified Webhooks, durable deduplication, outbox and reconciliation.
Developer guide · Conversation API · Administration · OpenAPI.