Customer Service

CS API overview

Day-to-day integration is widget + site appKey; admin APIs follow console roles.

Model: domain → sites (appKey) → members / sessions / tickets / tags / quick replies / escalation.

POST /api/v1/cs/handshake — site handshake → visitor JWT
POST /api/v1/cs/conversations — send message (auto-creates session)
GET /api/v1/cs/conversations/current — current session
POST /api/v1/cs/conversations/:id/end — explicitly end the current visitor conversation
POST /api/v1/ws/ticket — one-time WebSocket ticket

Capability handshake

{ "available": true, "capabilities": { "visitorEndConversation": true } }

Expose visitor end when the capability is strictly true. A successful end returns { closed: true, alreadyEnded, conversation, satisfaction }. The conversation must have customerService.status="closed" and a monotonic stateVersion.

alreadyEnded=true is an idempotent retry of the same ended conversation. For HTTP 409, branch on errorCode, resync the current conversation, then decide whether to retry.

Do not call /end merely because the host page is hidden, refreshed, or the panel is collapsed. Call it only after the visitor explicitly confirms the end.

Prefer the Widget for websites. Contracts: /api-spec + console responses. CS pages are hidden when the platform feature flag is off.