Conversation Hub

Conversation Hub is the reusable cross-channel session contract for website support, Telegram operators, authors, and future IM providers.

P0/P1 Integration

1. Create or upsert a tenant conversation.
2. Issue a short-lived Widget Session from your server.
3. Link the Widget channel and the Telegram operator/author channel.
4. Register an event Webhook, verify HMAC, deduplicate by event_id, and commit events to your outbox.
5. Send replies with a stable client_message_id; use reply_to_message_id for threaded replies.

The customer server keeps API keys and Connected Account identifiers. The browser receives only the Widget Session token.

Base URL

https://api.open4x.com

Staging uses the environment-specific Gateway URL supplied in the staging package.

Core Endpoints

Method	Endpoint	Purpose
POST	/v1/conversations	Create or upsert a conversation by external ID
POST	/v1/conversations/{id}/widget-session	Issue a 15–60 minute Widget Session
POST	/v1/conversations/{id}/channels	Link Widget or Telegram channel
POST	/v1/conversations/{id}/messages	Create a public or internal message
GET	/v1/conversations/{id}/messages	Read paginated history
GET	/v1/conversations/events	Read tenant-wide incremental events
POST	/v1/conversations/webhooks	Register signed event delivery
POST	/v1/conversations/telegram/identities/bind	Create one-time Telegram binding link
GET	/v1/conversations/credentials/status	Verify the API key policy without exposing its secret
GET	/v1/conversations/inbox	Read a tenant-scoped work queue
PATCH	/v1/conversations/{id}	Update status, priority, or locale
POST	/v1/conversations/{id}/assignments	Assign or transfer a creator/support agent
POST	/v1/conversations/{id}/presence	Publish online, typing, away, or offline state
POST	/v1/conversations/{id}/messages/{messageId}/receipts	Record delivered/read state
POST	/v1/conversations/deliveries/{deliveryId}/retry	Retry a dead-letter channel delivery
GET	/v1/conversations/{id}/deliveries	Inspect provider delivery attempts and errors
POST	/v1/conversations/attachments/{attachmentId}/scan-result	Publish tenant scanner result

API keys need conversation:read, conversation:write, and conversation:events:write as appropriate. JWT requests are scoped to the authenticated tenant.

Message Contract

{
  "channel_type": "telegram_operator",
  "sender_role": "creator",
  "visibility": "public",
  "text": "您好，我来帮您处理。",
  "client_message_id": "knv-reply-1001",
  "reply_to_message_id": "msg_...",
  "source_channel_id": "chn_..."
}

internal_note must use visibility: internal. Internal messages are never delivered to Widget or Telegram. Reusing a client_message_id with the same payload returns the original message; changing the payload returns 409.

Telegram Loop

Knoveria creates a Telegram binding link, the operator opens the Bot, and Open4X emits telegram.identity.started. Knoveria then links the operator's Telegram chat to the relevant conversation. A Telegram inbound message is stored once, the source channel is skipped, and the message is delivered to the Widget channel. The reverse direction follows the same rule.

Telegram users must start the Bot before a private Bot message can be delivered. Bot credentials stay in an active telegram-bot Connected Account and are never sent by the browser.

The telegram.identity.started event includes binding_id, identity_id, external_user_id, external_chat_id, telegram_user_id, participant_id, the envelope event_id, and the per-conversation sequence.

Operations and Attachments

Assignments are tenant-scoped and use customer-owned identifiers. replace_active_role: true ends other active assignments with the same role before adding the new assignee. Presence is a heartbeat-style record: online/away expires within 120 seconds and typing within 15 seconds. Receipt state is monotonic and cannot move from read back to delivered.

Attachment requests must include a tenant-owned storage key or public HTTPS download URL, filename, MIME type, and byte size. Open4X never downloads arbitrary URLs. New records are pending; the tenant’s scanner must set clean before a provider adapter is allowed to expose the file. The current text delivery path does not claim full binary support for every channel.

Webhook HMAC and Recovery

The signature covers <unix_timestamp>.<raw_body> and is sent as X-Open4X-Event-Signature: sha256=<hex>. Verify the timestamp and signature before parsing. Use event_id for deduplication and the opaque cursor only after the event is committed to the customer outbox.

Delivery retries use exponential backoff for up to eight attempts. Failed deliveries become dead_letter; authorized bridge operators can replay an event. See the OpenAPI contract and the Conversation Hub implementation contract.

Every channel delivery also reports environment and dry_run. A dry_run=true result is simulated and must not be treated as Telegram delivery confirmation.