GraphQL Contract
The widget talks to a GraphQL endpoint that must expose the Ink Live Chat
operations. The endpoint you point apiUrl at — whether Kraken directly
(pattern A) or your proxy (pattern B) — must ultimately resolve these operations.
The operation names and shapes must match what your installed widget version expects.
Required operations
| Operation | Type | Purpose |
|---|---|---|
| InkConversation | Query | Paginated conversation events (message history) and the live chat's status. A CLOSED status keeps the history read-only with the ended notice. |
| InkLiveChatConversations | Query | The account's live chats (accountNumber argument; relayId, status and lastMessageAt on each node). Used to find the open chat when a tab has none. |
| CreateInkLiveChatMessage | Mutation | Send a message; returns the conversation relayId. |
| CloseInkLiveChat | Mutation | Close the current conversation. |
Validate the exact fields and input arguments against your Kraken/Ink schema for the version you run.
Error codes the widget handles
| Code | Where | Widget behaviour |
|---|---|---|
KT-CT-7647 | CloseInkLiveChat | The chat was already closed. Treated as a successful close. |
KT-CT-7644 | CloseInkLiveChat, InkConversation | The live chat wasn't found. Treated as a successful close, and as closed when the user clicks X. |
KT-CT-7612 | InkConversation | The conversation wasn't found. Treated as closed when the user clicks X. |
KT-CT-1111 | InkLiveChatConversations | Unauthorised. The widget stops looking for open chats and joins on the first send instead. |
Backend permissions
For the widget to work end-to-end, the authenticated account user must have the
roles/permissions that allow managing and querying Ink Live Chat conversations on
your Kraken backend: CAN_MANAGE_INK_LIVE_CHAT for the mutations plus
CAN_ACCESS_CUSTOMER_QUERIES for InkConversation and
InkLiveChatConversations. If requests fail with an authorization error
(KT-CT-1111), check that the user's role grants the required
Ink Live Chat permissions.
Finding a chat started in another tab or device also needs a Kraken version where InkLiveChatConversations accepts account users and returns every live chat on an account they can administer. On older backends the widget falls back to joining the account's open chat on the first send.
Related
- Authentication — how requests reach this endpoint.
- Configuration reference —
apiUrland required fields.