Customer Integrations

For new support integrations, follow the Support Integration Guide. The Bot Widget examples below describe the legacy compatibility path, not the Conversation Hub SDK's scopes or webhook signing contract.

Open4X now combines AI, real-time support, message delivery, social inboxes, connected credentials, and usage controls behind one integration model. This page is for customer engineering teams planning a real integration.

Current status: staging is available for technical integration. Production activation still requires payment, provider, monitoring, observation, SLA, DPA, pricing, and security acceptance. Staging quotas and prices are not production commitments.

New Capabilities

Capability	Status	What customers can use	Integration
AI Model Gateway	MVP / staging testable	OpenAI-compatible Models, Chat, Streaming, Embeddings, aliases, budgets, and usage	Server API + ai:invoke
Widget real-time support	Staging POC	Fixed Loader, short-lived sessions, WebSocket, history, recovery, idempotent messages	Server-issued Session + browser Widget
Aggregate event feed	Staging POC	Tenant-wide Widget event reads, stable cursor, HMAC, and free empty polls	Bridge service polling /widget/events
Webhook Push	Beta / staging testable	Fan-out to enabled targets, Telegram and Generic Webhook, per-target results	push:send + target configuration
SocialOps	MVP	Unified inbox, threads, status, priority, assignee, notes, and reply queue	REST API + Console
Connected Accounts	Beta preparation	Encrypted API keys, bot tokens, OAuth connections, and service reuse	Console Connections + OAuth
Unified keys and billing	Beta preparation	Scopes, aliases, IPs, quotas, rate/concurrency limits, expiry, rotation, revocation, and audit	Console + API
Async Jobs	MVP / service-dependent	pending, running, succeeded, failed, and related states with callbacks	/v1/jobs + HMAC callbacks
TRON Energy Lease	MVP / sandbox	Quotes, idempotent orders, provider fulfillment, chain verification, and refunds	/v1/apps/tron

Recommended Architecture

Open4X owns communication, channels, model calls, and service-level usage accounting. The customer system remains the source of truth for users, orders, permissions, payments, and tickets.

Customer web / app
    │
    ├── Customer server issues short-lived Widget Sessions
    ├── Customer server stores Open4X API keys
    └── Customer server owns tickets, outbox, and business permissions
             │
             ├── Widget + WebSocket
             ├── Bot / SocialOps / Webhook Push
             └── Optional AI Model Gateway
                         │
                  Open4X Gateway
                         │
             Connected Accounts / Providers

Open4X should not become the single point of failure for customer login, payment, private-content authorization, or funds operations. AI is optional; Widget and human support should continue when AI is disabled.

For the lowest-effort integration, install the repository sdk/ package and expose one customer-server endpoint such as /api/open4x/session. The server checks the current user and optional order, calls createWidgetSessionForContext, and returns the short-lived session. No Open4X-specific browser key or mandatory customer database migration is needed. The same endpoint can pass context_type and context_id for order, content, dispute, or general support conversations.

Choose the client that matches the customer frontend: a hosted script for a zero-build page, mountOpen4XWidget for a custom JavaScript UI, <open4x-support-widget> for plain HTML/Vue/Svelte, or Open4XSupportWidget for React. These clients share the same session contract, so changing frontend frameworks does not change conversation storage or channel routing.

For multi-party cases, keep business IDs in external_participant_id and use the opaque participant IDs returned by Open4X. Channels are participant-scoped; audience_mode: direct sends to selected recipients, while all preserves the simple broadcast behavior. This lets a customer add Telegram, Discord, LINE, Teams, WhatsApp, or another adapter later without changing its conversation and ticket model.

Five-Step Integration

1. Create Service Instances

Create the required services in the Console and use environment-specific aliases:

ai-model:qwen122
bot
webhook-push:ops
socialops:support

Keep aliases in environment configuration rather than hard-coding them in multiple clients.

2. Issue Least-Privilege Keys

Split keys by responsibility in staging and production:

Key	Scope	Use
Conversation Bridge Key	conversation:read, conversation:write	New Conversation Hub SDK, Sessions and replies
Conversation event operator	conversation:events:write	Webhook registration/revocation and event replay
Legacy Bot Bridge Key	bot:session:create, bot:events:read, bot:send	Legacy Widget Sessions, event sync and replies
AI Key	ai:invoke	Models, Chat, Streaming, Embeddings
Webhook Key	push:send	Webhook Push fan-out
SocialOps Key	socialops:read, socialops:write	Inbox, ingestion, reply queue

Keys belong only in the customer server or Worker Secrets. The browser receives a short-lived Widget Session Token, never a platform API key.

3. Configure Sources and Quotas

Each key can be restricted by:

• service_aliases;
• allowed_ips or CIDRs;
• UTC daily_quota;
• rate_limit_per_minute;
• concurrency_limit;
• expires_at.

Creation, rotation, revocation, expiry, and policy-denial events are recorded as audit metadata. Plaintext is shown only at creation or rotation.

4. Validate in Staging

Current staging endpoints:

API:     https://staging-api.open4x.com
Console: https://staging-console.open4x.com
Widget:  https://staging-widget.open4x.com/widget.js

Customer-facing staging integrations must use these formal open4x.com domains. The underlying workers.dev and pages.dev deployment addresses are internal fallback addresses and are not part of the integration contract.

Staging disables real AI, Telegram, Webhook, payment, and other high-risk external side effects by default. Customers can validate authentication, request shapes, status codes, idempotency, cursors, HMAC, billing metadata, and fallback behavior. Dry-run responses are not proof of real provider delivery.

5. Enable Providers After the Production Gate

Production requires real provider accounts, secrets, callbacks, allowlists, payment configuration, backup/restore, alert verification, a continuous observation window, and business/legal sign-off. The release gate blocks without a formal evidence manifest.

Widget Real-Time Support

Session

The customer server issues a short-lived Session with the Bridge Key:

POST /v1/apps/bot/widget/auth
X-API-Key: <bridge-key>
Content-Type: application/json

{
  "external_user_id": "customer-anon-001",
  "user_name": "Alice",
  "ttl_seconds": 1800
}

ttl_seconds accepts 900–3600 seconds. Use a stable customer-generated mapping for external_user_id; do not put email addresses, wallet addresses, or other sensitive identifiers there.

Only the session_token goes to the browser:

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

Real-Time and Reliable Sync

Widget supports:

• WebSocket ping/pong and connected / new_message events;
• paginated history;
• client_message_id idempotency for safe retries;
• Session refresh, revoke, and expiration close code 4001;
• message recovery through the message or event API after disconnect.

The server-side Bridge does not need one poller per conversation. Use the tenant-wide aggregate feed:

GET /v1/apps/bot/widget/events?cursor=<opaque_cursor>&limit=100
X-API-Key: <bridge-key>

Without chat_id, the feed returns incremental events for all Widget conversations owned by the authenticated tenant. Events use a stable (created_at, message_id) cursor and include event_id, conversation_id, chat_id, message_id, client_message_id, direction, visibility, and created_at.

Process events in this order:

Read → verify HMAC → deduplicate by event_id → persist customer inbox → save next_cursor

Staging response headers:

X-Open4X-Event-Timestamp: <unix_seconds>
X-Open4X-Event-Signature: sha256=<hex>

The signing payload is <timestamp>.<raw_response_body> and the algorithm is HMAC-SHA256. Production should use a dedicated event-signing secret. Aggregate event quota is separate from the generic daily API quota; empty data=[] pages do not consume the event quota but remain subject to rate and concurrency controls.

AI and Agent-Assisted Support

AI is independent from basic support. Customers can select:

Mode	Behavior
AI off	Widget, Inbox, human support, and customer ticketing only
Agent assist	Classification, summaries, and reply suggestions visible only to agents
AI reception	Public AI responses with human handoff for complex issues

AI Gateway supports OpenAI-compatible routes:

GET  /v1/apps/ai/qwen122/v1/models
POST /v1/apps/ai/qwen122/v1/chat/completions
POST /v1/apps/ai/qwen122/v1/embeddings

Use Idempotency-Key and X-Request-ID. Responses can expose estimated cost, final cost, and token usage for attribution by tenant, user, service, and request.

AI should not independently authorize private content, issue refunds, withdraw funds, sign wallets, ban users, settle disputes, or perform other high-risk actions. Tool execution and permission-aware RAG remain customer-side or future-module responsibilities.

Webhook Push and SocialOps

Webhook Push fans one message out to multiple configured targets:

POST /v1/apps/webhook-push/ops/send
X-API-Key: <webhook-key>

Targets are enabled independently. All success returns 200, partial success returns 207, and all failure returns 502. Telegram targets require an active Telegram Bot Connected Account and a chat ID.

SocialOps is suited to support, operations, and developer collaboration:

• unified threads, inbox, status, priority, and assignee;
• normalized generic webhook, Telegram, and GitHub events;
• public replies separated from internal notes;
• replies stored in an action queue before provider delivery;
• provider failures retained as audit errors instead of being silently dropped.

Slack, Discord, Teams, X/Twitter, Meta, Instagram, WhatsApp, and LINE require provider applications, OAuth, callback validation, and outbound support one by one. A provider appearing in the Console catalog does not mean it is production-ready without configuration.

Tenant Telegram configuration

A tenant must provision its own Telegram Connected Account and channel mapping. Check the tenant configuration and provider acceptance record; the presence of an adapter does not confirm that this tenant can send real messages.

The Open4X Telegram + SocialOps path supports the following once the customer provisions the provider:

1. Create a Bot with Telegram's BotFather and deliver the Bot token through a secure channel.

2. Create an active telegram-bot Connected Account in Console > Connections.

3. Create and enable socialops:support, binding the connected_account_id and Telegram chat_id.

4. After a Bot Service is created or updated, Open4X registers the webhook automatically. The staging webhook URL is:

   https://staging-api.open4x.com/v1/apps/bot/webhook/platform

5. The user must start the Bot, or the Bot must be added to the target group with the required permissions. Incoming messages then enter a SocialOps thread and Inbox.

After the provider is configured and real delivery is enabled, the customer operations can reply from Console > SocialOps or through:

POST /v1/apps/socialops/support/threads/{thread_id}/replies
X-API-Key: <socialops-key>
Content-Type: application/json

Replies enter an action queue first. Successful delivery records the Telegram message_id; provider failures remain auditable. The Bridge, AI, and Webhook Push keys do not replace the Telegram Bot token. The Bot token must remain in an encrypted Connected Account.

Staging currently disables real Telegram external delivery by default, so a configured staging flow is initially dry-run only. A real staging test needs a dedicated the customer Bot, channel binding, provider switch, and inbound/reply/failure/retry acceptance. A Telegram Bot cannot initiate a private conversation with a user who has never started it.

Third-Party Authorization

Connected Accounts let a customer configure a credential once and reuse it:

1. Select a provider in Console Connections.
2. Authorize with an API key, bot token, or OAuth.
3. Open4X encrypts the credential and returns only redacted status.
4. A service references the connection with connected_account_id.
5. Revoking or disabling the connection stops subsequent use.

OAuth providers require Client ID, Client Secret, callback URL, origin, and encryption-key configuration in the target environment. For Discord, a message that OAuth is not configured means DISCORD_CLIENT_ID and related settings are missing; repeated authorization cannot fix deployment configuration.

Security and Operations

• API keys, bot tokens, and provider keys never enter the browser, logs, docs, or Git.
• Default logs retain request ID, service, model, token usage, status, latency, and cost, not full prompts or responses.
• External URLs must use HTTPS and pass SSRF checks.
• The customer system owns users, orders, payments, tickets, and private-content authorization.
• Customer outboxes or ticket systems should retry and fall back when Open4X or a provider is unavailable.
• Production requires explicit retention, deletion, DPA, data-region, status-page, SLA, maintenance, and service-credit rules.

Related Documentation

• API Reference
• AI Model Gateway
• Widget Service
• Webhook Push
• SocialOps
• Connected Accounts
• Enterprise Readiness
• Security and Operations
• Pricing and Billing