Support Integration Guide

New merchants should start with Your First Live Chat for account setup, dedicated credentials, the website Session endpoint, Widget and acceptance steps. This page is the developer reference; do not mix its staging examples with production credentials.

Use Conversation Hub for new order, creator and platform-support integrations. Legacy Bot Widget APIs remain a separate compatibility path with different scopes, sessions and signing credentials.

1. Quick Start

The current delivery targets staging POCs. Real Telegram delivery and production activation require separate acceptance. These are configured targets, not live availability claims:

Component	Staging URL
API	https://staging-api.open4x.com
Console	https://staging-console.open4x.com
Widget	https://staging-widget.open4x.com
Loader	https://staging-widget.open4x.com/widget.js

Verify DNS and HTTPS first, then call GET /v1/conversations/credentials/status from your server to check the actual key policy. Do not substitute production URLs when staging DNS is unavailable.

The minimum flow is: authorize the user and order, create the conversation and participants, issue a Session, open the Widget, reply from Inbox, and recover history after reconnecting. Keep AI off for this first acceptance.

2. Customer Components

For a page without a build step, use the hosted loader with a server-issued token:

<script src="https://staging-widget.open4x.com/widget.js"
  data-token="SERVER_ISSUED_SESSION_TOKEN"
  data-widget-url="https://staging-widget.open4x.com"
  data-gateway-url="https://staging-api.open4x.com">
</script>

Insert the token safely on the server; never insert an API key. The loader URL is mutable. Obtain pinned assets and checksums through the frozen delivery package.

The repository SDK is source version 0.1.0, not a verified public npm release. Obtain its directory from the frozen package and install it locally:

npm install ./vendor/open4x-conversation-sdk

Keep the package release identifier and checksum. Its TS/TSX exports require a TypeScript-capable bundler; plain HTML cannot directly import them. React needs version 18 or later.

import { Open4XSupportWidget } from '@open4x/conversation-sdk/react';

export function OrderSupport({ orderId }: { orderId: string }) {
  return <Open4XSupportWidget
    sessionUrl="/api/open4x/session"
    contextType="order"
    contextId={orderId}
    conversationType="order_support"
    scriptUrl="https://staging-widget.open4x.com/widget.js"
    widgetUrl="https://staging-widget.open4x.com"
    gatewayUrl="https://staging-api.open4x.com"
  />;
}

Plain JavaScript can use mountOpen4XWidget; Vue/Svelte can use the custom element <open4x-support-widget>. Explicitly configure all three staging URLs. These wrap the existing Widget, not complete role-specific workspaces.

3. Creator Experience

Your server owns creator identity and order authorization. Create the conversation and creator participant, create a one-time Telegram binding, let the creator open the Deep Link, consume telegram.identity.started, link the returned Chat ID to the participant and conversation, then create the Assignment.

Do not accept another creator's participant ID from the browser. Stop business delivery after unbinding. A web creator workspace can use server APIs; the React Widget wrapper is not a complete creator-workspace SDK.

4. Agent Workspace

The hosted Console workspace is /dashboard/conversations, with conversation lists, messages, status and reply audiences. A custom customer backend can use Inbox, message and assignment APIs. A complete embeddable agent workspace is not an existing delivery commitment.

Console tenant accounts and your own agent identities are different authorization systems. Never give creators or browsers a tenant management key. Internal notes use sender_role: internal_note and visibility: internal; your own consumers must also filter internal content.

5. Server Authorization

Operation	Minimum scope
Conversation/event reads and credential status	conversation:read
Conversation, participant, Session and message writes	conversation:write
Webhook registration/revocation and event replay	conversation:events:write
Legacy Bot Session / events / send	bot:session:create / bot:events:read / bot:send
Optional AI	Separate key: ai:invoke

Pass the Bridge Key using Authorization: Bearer on the server. Re-authorize browser-supplied order IDs, derive roles and recipients on the server, and apply your application's cross-site request protections to its Session endpoint.

Session TTL is 900–3600 seconds. Minimal integration needs a protected server endpoint but no mandatory Open4X-specific database table. Ticket synchronization, deduplication and recovery need durable storage; reuse existing databases or queues.

6. Multi-party Orders

Use context_id for the order and external_conversation_id for a stable business conversation ID. A is the customer, B the agent and C the creator. Default all is broadcast, not isolated A/B and C/B communication.

1. Resolve participants by external ID, role and active status.
2. Fail if any required participant is missing; do not issue a token.
3. Issue A's Session with A's participant_id and B's recipient_participant_ids.
4. Send private replies using direct and explicit recipients. Agent-mediated forwarding uses relay, explicit recipients and relay_from_message_id.

createWidgetSessionForContext combines requests; it does not resolve participant IDs or build private routing automatically. Use explicit conversation creation, participant validation and createWidgetSession for private sessions. The frozen SDK README contains that example.

7. Webhooks and Recovery

Protocol	Signing key	Signed input
Conversation outbound Webhook	Dedicated registered secret	Timestamp + . + raw request body
Legacy Widget event polling	Current Bridge API Key, staging contract	Timestamp + . + raw response body

Both use HMAC-SHA256 but their keys are not interchangeable. Conversation headers are X-Open4X-Event-Timestamp and X-Open4X-Event-Signature: sha256=<hex>. The SDK defaults to a 300-second timestamp window. Verify before parsing and deduplicate by event_id.

Persist the event and deduplication marker atomically, or durably enqueue it, before returning 2xx. Use an inbox for received events and an outbox for outgoing business operations. Advance incremental cursors only after durable processing. Repeated events should receive a successful acknowledgment without duplicate messages.

Callbacks time out at 10 seconds, with eight total attempts including the first. Retry minimum delays are 30, 60, 120, 240, 480, 960 and 1920 seconds after failure; scheduled processing may occur later. Final failures enter dead_letter; replay preserves the event ID. See the protocol.

Keep ordinary tickets available during outages. Retries retain client_message_id; a changed-payload 409 requires investigation, not endless retry. Read actual key quotas rather than assuming a universal free allowance.

8. Launch Acceptance

• Verify API, Console and Widget custom domains, HTTPS and matching environments.
• Test real authorization, Session expiry/revocation and reconnect recovery.
• Test A/B and C/B isolation, unauthorized creators and internal-note filtering.
• Test duplicate messages/events, recovery and ordinary-ticket fallback.
• Complete the human flow with AI off.
• Enable real Telegram per tenant and test delivery, reply and unbinding; dry_run is not delivery confirmation.
• Separately accept binary attachments, production pricing, quotas, retention, DPA and SLA.

This is an acceptance checklist, not a claim that these tests have passed. Production settings come from the customer's frozen package and agreement. Schemas are in OpenAPI.