Skip to main content

Support Ticket Handoff

Available from SDK 0.16.0.
The Moss assistant can collect a support request in conversation, draft a ticket, and show it to the user for review. When the user confirms, the SDK hands the approved ticket to your application, which files it through your own backend. Moss never holds a credential for your ticketing system, and the requester’s identity is attached by your backend from your own session — it never transits Moss.
Ticket filing is configured per application in the Moss dashboard, including the intake form the assistant collects against. Contact Moss to enable it for your application.

How it works

  1. Collect — the assistant gathers the ticket fields in conversation, validated against your configured intake form.
  2. Review — the widget renders the drafted ticket as a preview card in the chat. The user can edit the description and confirm or cancel.
  3. Hand off — on confirm, the SDK calls the onSupportTicket callback you registered at initialization, passing the confirmed ticket and a handoff id.
  4. File — your page forwards both to your backend over your own session-authenticated channel. Your backend attaches the requester and files the ticket.
  5. Confirm — your callback resolves with the outcome. The assistant shows the user the result, including the ticket id when you provide one.

Registering the callback

Registering onSupportTicket is also the capability signal: the SDK reports it at session init, and the backend offers ticket filing only to sessions that registered it. A page that doesn’t register the callback is never offered a flow it cannot finish.
The callback owns the transport: use your application’s normal session and CSRF semantics. The SDK never touches your cookies.

The handoff

Your callback receives a SupportTicketHandoff: SupportTicketPayload uses the Zendesk ticket-create shape, in Zendesk’s own casing, so your backend can attach the requester and post it without translation: Fields the user left unset are absent rather than empty — Moss omits what it cannot determine instead of guessing.

The outcome

Resolve your callback with a SupportTicketOutcome:
ticketId may be passed as your ticketing system returns it, a whole number, or as text; Moss records it as text. Past Number.MAX_SAFE_INTEGER a number may already have been rounded, so Moss records the filing without it; pass an id that large as text. A fraction names no ticket and is dropped the same way. SDKs before 0.16.16 type ticketId as string, so a typed host returning a number needs a cast there. The resolution is the ticket’s outcome, not an acknowledgement.
  • Resolve { ok: true } only once the ticket really exists, with ticketId when your backend can name it. The user is shown “Submitted on your behalf” on the strength of that value alone.
  • Resolve { ok: false } when filing failed or was refused. errorCode and errorDetail land in the handoff’s audit trail; they are never shown to the user. From Moss 0.16.16, either one sent as a whole number is recorded as text, and any other value that isn’t text is dropped.
  • Do not resolve early to release the SDK. A callback still pending after 15 seconds, or one that rejects, is treated as unknown rather than failed: the card tells the user the request was handed over without a confirmation, because your backend may well have filed it. Late resolutions are ignored.

Repeated submits

From Moss 0.16.16, when the user submits the same card again before your backend’s outcome is recorded, for example after a lost response, Moss accepts the repeat and calls onSupportTicket again under the same handoffId. Deduplicating on handoffId gives the user one ticket. A repeat whose values differ from the first submit is refused and never reaches your callback.
Treat handoffId as an idempotency key on your backend. If the same handoff reaches you twice, return the original result — never file a second ticket for one confirmation.

Responsibilities

Next Steps

Configuration

Full SDK configuration reference

Authentication

JWT setup for SDK sessions