Batch Conversation Status

Released

Both batch endpoints were deployed to the production API on 2026-09-14. Upgrade the SDK source delivery package, or call the HTTP endpoints directly without an SDK upgrade.

Use POST /v1/conversations/order-statuses on https://api.open4x.com from your server with an API Key holding conversation:read.

{"external_participant_id":"agent-123","external_order_ids":["ORDER-001","ORDER-002"]}

The data array contains external_order_id, has_conversation, has_messages, has_unread, unread_count and conversation_count for each unique requested ID, in first-occurrence order. An existing empty conversation has has_conversation=true and has_messages=false. Inaccessible and unknown contexts both return false flags and zero counts.

Create conversations with context_type=order and context_id equal to your order ID. The viewer must be an active customer, creator or support_agent participant; an assignment alone is insufficient. Resolve their stable external participant ID from your authenticated server session and validate order authorization. Never trust browser-supplied viewer identity or expose the API Key.

Only this tenant's accessible conversations and publicly visible messages are counted. Own messages, internal notes, inaccessible recipients and conversations pending deletion do not contribute unread counts. Counts use per-viewer read receipts; querying never marks messages read. Synchronize participant revocation when business access changes.

Send 1-100 IDs, each at most 200 characters, without control characters or leading/trailing whitespace. Key rate limits, origin restrictions and quotas still apply. One batch is one API request, not an exemption from billing. Query only the visible order page; refresh on focus or message events and back off polling. Show errors separately from empty results and disable shared caching on the merchant response.

await client.getOrderStatuses(authenticatedParticipantId, orderIds);
await client.getContextStatuses(authenticatedParticipantId, 'resource', resourceIds);

The generic route POST /v1/conversations/context-statuses accepts external_participant_id, context_type, context_ids; the response uses context_id instead of external_order_id. No order database or schema migration is required.

See the OpenAPI specification for request, response and error contracts.