Skip to main content

Prefill Ticket Fields from a Host App

Prefill ticket custom fields in your support widget's contact form and chat handoff using signed user tokens or page context values matched by field key.

Your host app can prefill ticket custom fields in the widget's contact form and chat handoff contact card. Values come from either a verified signed user token or page context, and they're matched directly by field key with no mapping required.

Provide prefill values

  1. Identify the ticket custom-field keys
    Use the same keys defined in your Help Center's ticket custom fields. Each value you supply must match a field key exactly.

  2. Supply values through a signed user token
    Include field keys and their values in a verified signed user token. These values take precedence over page-context values. They're hidden from visitors and can't be changed by them.

  3. Supply values through page context
    Provide field keys and values through widget configuration or by updating the widget context. These values are shown to visitors in the form and remain editable.

If the same field key appears in both sources, the signed-token value wins. Values are checked against the field's type and available options. Unmatched or invalid values aren't applied. This includes fields hidden from visitors: they can still receive valid prefill values from either source.

Verify prefills in the contact form

  1. Open the widget and choose the contact form
    Open your host app's support widget and select "Contact" to send a form request. The contact form appears with its custom ticket fields above the message field.

  2. Check page-context values
    A page-provided value appears in its matching field and can be edited by the visitor. If there's no usable prefill for a field, the visitor fills it in themselves.

  3. Confirm signed-token values are hidden
    Fields filled from a verified signed token don't appear in the form. The visitor can't see or edit them.

  4. Complete the form and submit
    Enter a message and fill in any visible custom fields. Required fields are marked with an asterisk. If a required field is empty, the form shows "Please fill in this field." and blocks submission. For number fields, an invalid entry shows "Please enter a number."

    Choose "Next" to continue to the contact-details step if a valid email isn't already present. If one is, the form skips that step and offers the send action directly. On the details step, enter or confirm the name and email. A valid email is required.

  5. Send the request
    Choose the send control to submit. Valid prefilled values are saved with the ticket. The server re-checks all values, so anything it can't accept won't be saved. On success, you see a "Message sent" confirmation. If you choose to send another message, cleared custom fields return to their page-provided values.

Verify prefills in the chat handoff contact card

  1. Start a chat and reach the handoff
    Choose "Ask" in the widget and describe your issue. If the chat offers human support and a handoff is available, proceed to the contact card.

  2. Check the handoff card fields
    The card shows required fields only. Page-provided values appear and can be edited. Fields filled by signed claims stay hidden. The card may briefly show "Getting the details ready…" while preparing fields. If preparation takes longer than ten seconds or fails, it falls back to asking for all required form fields.

  3. Complete and send the handoff
    Fill in any required fields still needing a value, enter or confirm "Your email," and optionally add a "Message for the support team." Choose "Send to support" to submit. If a required field is blank or invalid, the card marks it for correction and won't submit until it's fixed. Required fields filled by a valid signed claim count as complete even though they aren't shown.

What happens to prefilled values

Matching, valid values are saved with the ticket on submission. If a visitor changed a page-provided value, the visitor's choice is saved. Signed-token values that fail validation are left blank rather than replaced by the page-context value for that field.

When the host app updates the page context, the new set of values replaces the previous set. A signed claim can also expire: if it's no longer valid when the widget requests fields, its value won't prefill and the visitor may be asked for that field instead.

After a ticket is created, you can check where each field value originated using ticket field source indicators in the inbox.

Last updated HappySupportPowered by happysupport.ai
© 2026 HappySupport. All rights reserved.