Setting up home-action forms

1. The one thing to know first

This matters because the most common worry when setting up a form is "what if I haven't connected our helpdesk yet?" The answer is: set the form up anyway. It will work. Connect the helpdesk later and new submissions start flowing there as well, with no change to the form.

2. What home actions are

Home actions are the buttons on the widget's Home screen, the first thing a visitor sees when they open the chat bubble. Each one is a card with a title, an optional subtitle, and an icon.

A typical support widget shows something like:

• Ask a question opens the chat with the AI assistant
• Report an issue opens a short form (subject, description, priority)
• Talk to a human asks for a person

You configure them in the dashboard under Portal › Widgets › (your widget) › Tabs & content, in the Home action cards section. Widget templates (General purpose, Support help desk) pre-fill a sensible set, and you can edit, reorder or delete them.

3. The three modes

Every action has a mode that decides what happens when a visitor taps it.

4. Video: the whole thing end to end

One continuous recording: adding a support-ticket form in the dashboard, setting its title, subtitle and icon, choosing a destination, adding fields, saving, and then filling the form in as a visitor on a live site.

5. Step by step: building a form

6. What the visitor sees

These are captured from the widget running on an ordinary web page, loading the configuration we just saved.

7. Destinations: where answers can be sent

Read this table with the guarantee from section 1 in mind: whatever the "if it is not connected" column says, the answers are already saved on Assistable's side before the forward is even attempted.

Saved versus delivered are two separate facts

When a form is submitted the server reports two things on purpose:

In the JSON that comes back from actions/submit these are the ok and delivered fields, with delivery_error alongside them when a forward failed.

• Saved (ok) means the answers are kept. This is what decides whether the visitor sees the success screen.
• Delivered (delivered) means the forward you asked for actually happened. When it is false, delivery_error carries the reason.

They are separate so a dead destination, an expired Zendesk token or a webhook receiver that is down, never makes a visitor retype answers you already have. The flip side is that a failed forward is invisible to the visitor: they see success either way. When someone reports "the form worked but nothing arrived", the delivered flag in the submit response is the first thing to check.

The three lookups are the exception. They store nothing, so when they fail they simply fail, and the visitor sees an error.

8. Field keys and maps_to

Every field gets a random internal id such as f-a3k9 when you add it, and the raw answers are always stored under those ids. But when the answers are forwarded to a destination, each answer needs a meaningful key: a ticket needs to know which answer is the subject, GHL needs to know which is the email address. That key is what the maps_to box sets.

How the key is chosen

1. If you typed something in maps_to, that is used.
2. Otherwise the label is slugified: lowercased, with non-alphanumeric characters turned into underscores. If the result is one of email, phone, first_name, last_name or name, that is used. So a field labelled simply "Email" needs no maps_to at all.
3. Otherwise, if the field type is Email, the key is email.
4. Otherwise the random field id is used, which no destination understands.

Rule of thumb: set maps_to explicitly for any field a destination needs. The editor shows the inferred key as the placeholder text in the box, so you can see at a glance whether inference is going to do the right thing. You must set it yourself whenever the label does not slugify to what the destination expects: a field labelled "Work email address" needs email, and a ticket subject field labelled "What's this about?" needs subject.

Keys each destination looks for

9. Where the data actually landed

The submission captured in section 6 was a support-ticket form on a widget with no Zendesk and no active Gleap integration, which is the most common starting position. Here is exactly what it produced, read back from the database.

The submission record

Written for every non-lookup submission. This is the "always saved" part of the guarantee.

SELECT _id, "actionId", "actionTitle", tool, "contactName", "contactEmail",
       "contactId", "conversationId", "visitorId", "createdAt"
FROM "widgetFormSubmission"
WHERE "widgetId" = 'cmqj7kubf0001rua7841r0345'
ORDER BY "createdAt" DESC LIMIT 1;

-[ RECORD 1 ]--+---------------------------------------------
_id            | cmspi9htb000be0ruk4iaj81z
actionId       | bug-vsh3mt
actionTitle    | Report a bug
tool           | create_support_ticket
contactName    | Dana Whitfield
contactEmail   | dana.whitfield@northwind-demo.test
contactId      | cmspi54l00000e0rutazat78n
conversationId | cmspi9ht40009e0ruxneacx95
visitorId      | visitor_7a3e5fc1-915c-4026-872c-b0318561bd6a
createdAt      | 2026-08-12 03:04:05.999

The raw answers live on the same row, keyed by field id:

SELECT jsonb_pretty(values) FROM "widgetFormSubmission"
WHERE _id = 'cmspi9htb000be0ruk4iaj81z';

{
    "f-19tc": "Dana Whitfield",
    "f-a36o": "dana.whitfield@northwind-demo.test",
    "subject": "Checkout fails on the final step",
    "priority": "high",
    "description": "Adding a cordless drill to the basket works, but pressing
                    Pay returns an error: 'order could not be created'.
                    Happens in Chrome and Safari, reproduced three times
                    this morning."
}

The support ticket

Created because the action's destination was a support ticket. Subject, priority and requester are all populated from the mapped fields, and destination records where it was routed.

SELECT _id, subject, priority, status, source, "requesterName",
       "requesterEmail", destination, "externalId", "externalUrl",
       "contactId", "conversationId", "submissionId", "createdAt"
FROM "supportTicket"
WHERE "widgetId" = 'cmqj7kubf0001rua7841r0345'
ORDER BY "createdAt" DESC LIMIT 1;

-[ RECORD 1 ]--+-----------------------------------
_id            | cmspi9htq000ce0ruzahypobs
subject        | Checkout fails on the final step
priority       | high
status         | open
source         | home-action
requesterName  | Dana Whitfield
requesterEmail | dana.whitfield@northwind-demo.test
destination    | in-app
externalId     |
externalUrl    |
contactId      | cmspi54l00000e0rutazat78n
conversationId | cmspi9ht40009e0ruxneacx95
submissionId   | cmspi9htb000be0ruk4iaj81z
createdAt      | 2026-08-12 03:04:06.014

destination = in-app is the fallback working exactly as designed: no helpdesk was connected, so the ticket lives in Assistable and the team works it from the Inbox. Had Zendesk or Gleap been connected, this would read zendesk or gleap and the row would also carry the external ticket id and URL.

The contact

The name and email fields were mapped to contact.name and contact.email, so the visitor was matched to (or created as) a contact, and the submission and ticket are both linked to it.

SELECT _id, "firstName", "lastName", name, email, phone,
       "subAccountId", "createdAt"
FROM contact
WHERE email = 'dana.whitfield@northwind-demo.test';

-[ RECORD 1 ]+-----------------------------------
_id          | cmspi54l00000e0rutazat78n
firstName    | Dana
lastName     | Whitfield
name         | Dana Whitfield
email        | dana.whitfield@northwind-demo.test
phone        |
subAccountId | 1753298396627x629167684234041700
createdAt    | 2026-08-12 03:00:42.228

Note that contact.name was split into firstName and lastName automatically, and the same contact id appears on both the submission and the ticket above, so the visitor's history stays joined up.

And in the Inbox

The submission also opened a conversation containing the answers as a readable message, retitled with the ticket subject. That conversation is what your team actually replies to when no helpdesk is connected.

SELECT c._id, c."lastChannel", c."lastSubjectLine", c."contactEmail",
       c."previewText"
FROM conversation c
JOIN "widgetFormSubmission" s ON s."conversationId" = c._id
WHERE s._id = 'cmspi9htb000be0ruk4iaj81z';

-[ RECORD 1 ]---+---------------------------------------------------
_id             | cmspi9ht40009e0ruxneacx95
lastChannel     | Live_Chat
lastSubjectLine | Checkout fails on the final step
contactEmail    | dana.whitfield@northwind-demo.test
previewText     | Adding a cordless drill to the basket works, but
                | pressing Pay returns an error: 'order could not be
                | created'. Happens in Chrome and Safari, reproduced
                | three times this morning.

One exception: a submission that is nothing but a rating, for example a bare NPS score with no comment, does not open a conversation. Those are stored in the submission and feedback records only. Ticket destinations are exempt from the exception: create_ticket and create_support_ticket always open a conversation, even from a bare rating. If you want NPS responses to be visible to your team, add an optional comment field to the survey.

10. Troubleshooting

First diagnostic step for any form problem: open browser dev tools, go to the Network tab, submit the form, and read the JSON response of the actions/submit request. The widget deliberately shows only a generic message; the response body carries the real reason.