FruxonDocs

Forms

Ask a person for answers on a page they fill in, with a row per item from an automation or a set of fields from an agent in a conversation

A form sends a person one link to a page where they fill in answers, instead of asking them to write a reply. Fruxon uses forms in two places, and both open the same page:

Asked byThe person fills inThe answer goes to
Form stagesAn automation's Ask a person stageA table with a row per item and one column to answerEach item, row by row, as the person sends them
ask_formAn agent, in a conversationUp to 10 fields, one of which can be a tableThe agent's run, all at once

Form stages

An Ask a person stage can ask its question as a form. Use one when one person has to give the same kind of answer for many items, for example a destination for each of 40 customers. Answering a long list in a reply is slow and easy to get wrong. On a form, each item is a row.

What the person gets

The person gets one message with the stage's Question and a link. When the stage has no question, the message opens with "These items need your input:". Below it is a closing line. By default that line reads, for 12 items: "12 items are waiting on you in this form. You can save a draft, and submit some now and the rest later — anything you leave stays on the list." The message doesn't list the items. They are on the page.

The page doesn't ask the person to sign in, so anyone with the link can open it until it closes. It shows:

  • The question's first paragraph as its heading, then the rest of the question.
  • Asked by with the agent's display name and your workspace's name, and Answer by with the deadline.
  • A table with a row per item. The read-only columns are the fields in Show each item as. A field that holds a link, such as a PDF for each row, shows as a document icon that opens it. The last column is the answer. On a phone, each row is a card.

The answer column can be a list to choose from, several choices, yes or no, a number, a date, or text. A list can offer an extra entry, such as Other, that lets the person type their own answer.

  • Fill every empty answer with… fills all empty rows with one choice. It's offered when the answer is a single choice and at least two rows are open.
  • Save draft keeps what they've filled in without sending it.
  • Submit sends every row that has a valid answer. Each row moves its item on as soon as it's sent. Rows left empty stay on the page for later. If a row's answer is refused, its reason shows under it and the other rows still go through.
  • Sent rows move to the Done list. A sent answer can't be changed on the page.

When new items join an open question, they appear as new rows on the same page, and the person gets a short message. By default it reads "2 more have come in since I asked, and I've added them to the same form — 14 waiting on you now. Same link as before." When everything is answered, the page says so, and the link then opens a page saying the answers are in.

The page uses the person's preferred language. Its own text is in English or Hebrew, and right-to-left languages read right to left. If your workspace has a logo and accent color, the page uses them.

When no agent talks beside the form, the person can also answer by replying to the message. The reply is read back onto the items, just like a question asked as a message.

Who can get a form

A form link is made for one person. On the asking agent, the stage's contact slot must be bound to a person, not a roster role or the operator queue. Saving the automation refuses a form stage whose contact routes to a role or the queue.

If the contact can't be resolved to a person when the question goes out, for example because the participant was disabled, the question is sent as a plain message that lists the items. The Work tab then shows it as a message question, not a form.

Set up a form stage

On an Ask a person stage, choose A form they fill in under How they get asked. The stage starts with a required text column, so you can save it right away. Then set:

  • The column they fill in. Each row the person sends writes its answer to the key in Answered when this field is filled.
    • Column heading.
    • Answer type: Text, Date, One choice from a list, Several choices from a list, Yes / no, Whole number, or Number.
    • For a choice, the options the person picks from, each with a value and a label. Let them type an answer that isn't listed adds an entry they can type into, named by Label for their own answer (Other unless you change it).
    • Hint under the heading (optional), shown above the table.
    • Required — a row can't be sent with this left empty.
  • Heading for each field in Show each item as. Leave one blank to show no heading for that column.
  • Line above the link (optional) and When more items join (optional). Each shows the platform's default line until you write your own. Send no line and Send nothing when items join turn them off.
  • Agent who talks beside the form (optional), and with it Remind after and Check typed answers for. See An agent beside the form.

Ask which contact turns red when the contact goes to the operator queue or a roster role, and marks such contacts can't take a form link in its list. Closing line (optional) is only used if the question goes out as a plain message instead of the form.

Through the API or the CLI, a form stage is an Ask a person stage whose ask block has "delivery": "FORM" and an answerField, the column the person fills in:

{
  "id": "ask-destination",
  "kind": "ASK",
  "ask": {
    "contactSlot": "advisor",
    "answeredWhenPath": "destination",
    "delivery": "FORM",
    "instruction": "Where should each of these customers fly?",
    "labelPaths": ["customer_name", "travel_dates"],
    "labelTitles": { "customer_name": "Customer", "travel_dates": "Dates" },
    "answerField": {
      "displayName": "Destination",
      "type": "OPTION",
      "required": true,
      "options": [
        { "value": "greece", "label": "Greece" },
        { "value": "cyprus", "label": "Cyprus" }
      ],
      "allowOther": { "label": "Somewhere else" }
    },
    "formClosing": "{{item_count}} customers are waiting for a destination."
  }
}

These fields are for forms only. The other ask fields, such as ttlHours, batchSize, and gatherMinutes, work as they do on every Ask a person stage.

FieldWhat it does
deliveryFORM. The other values are DIRECT (a message they reply to) and TOPIC (a conversation an agent holds).
answeredWhenPathThe key the answer fills on each item. It is also the answer column's name, so answerField.name isn't needed.
answerFieldThe answer column. displayName is its heading, type is one of OPTION, STRING_ARRAY (several choices), BOOLEAN, INTEGER, FLOAT, or STRING. A date is a STRING with "uiHint": "DATE". required makes it mandatory on each sent row. A choice column lists its options as value and label, with an optional description. allowOther adds an entry the person can type into: its label, at most 80 characters, and an optional prefill. description shows above the table.
labelPathsThe item fields shown as read-only columns, the same as Show each item as.
labelTitlesOptional headings for those columns, keyed by field. Each heading is 1 to 80 characters.
instructionThe question at the top of the message and the page.
formClosingThe line under the question in the message, above the link. {{item_count}} becomes the number of items on the form. Leave it out to use the default line. Set it to "" to send no line.
formJoinNoticeThe message sent when items join an open form. {{added_count}} becomes how many just joined, and {{item_count}} how many are waiting now. Leave it out to use the default message. Set it to "" to send nothing, and the rows simply appear.
dialogueAgentIdOptional. An agent that talks beside the form.
remindAfterHoursOnly with dialogueAgentId. See Reminders.
holdOtherAnswersHoursOnly with dialogueAgentId. See Answers typed outside the list.

Write instruction, formClosing, and formJoinNotice in the language the person reads. The default lines are in English.

With the CLI, fruxon triggers preview-shape <trigger> --file shape.json shows the form's messages as the person will read them. fruxon agents check <agent> warns when a form stage's contact on that agent routes to a role or the operator queue.

An agent beside the form

Name an agent in Agent who talks beside the form (dialogueAgentId), and that agent holds a conversation with the person while the form is open. The answers are still given on the form. The agent is there to help the person finish it:

  • It sends the form through its own channel and opens the conversation in its own words, once the link has gone out.
  • It answers the person's questions about the items.
  • It can fill in answers for the person to check. These show on the page with "Suggested for you. Check it, then send." A suggestion never replaces something the person filled in, and it moves nothing on until the person sends it.
  • It checks answers typed outside the list with the person.
  • It sends reminders, and tells the person when more items join. The platform's own join message isn't sent then.
  • It sends a new link if the person lost theirs. The old link stops working, and drafts are kept.

The agent can't send rows for the person. The conversation ends when every item is answered, when the wait runs out, or when an operator cancels the question. If the agent calls resolve_topic, only the conversation ends, and the form stays open.

The agent must exist and be a member of the automation's Application. A stage can't have both an agent beside the form and a sender (senderAgentId), because the agent sends the form itself.

Add these System tools to that agent. They aren't added for you, and saving doesn't check for them. fruxon agents check <agent> (CLI 2.3.11 or later) warns when the agent beside a form lacks one:

ToolWhat the agent does with it
list_batch_itemsReads every row: whether it's waiting, held, or answered, its answer or draft, and its data.
suggest_batch_answersFills in suggested answers on rows that are still waiting.
confirm_batch_answerSettles an answer typed outside the list.
resend_batch_form_linkSends the person a new link. It can't be used within 5 minutes of the last change to the question.

The agent is told what happens on the form. Opening the form, saving a draft, and sending some rows are noted for its next turn without starting one. An answer typed outside the list, a reminder, and new items joining start a turn. Every turn is a billed agent run. At the start of every turn, the agent also sees how many rows are waiting, held, and answered.

Answers typed outside the list

When the answer column allows the person to type their own answer, an agent beside the form can check it before it moves the item on:

  1. The person sends a row with a typed answer. The row shows "Sent. It isn't on the list, so it will be checked with you in the chat." and stays open.
  2. The agent gets a turn with what they typed and up to three close options from the list, and asks them in the chat.
  3. The agent settles it with confirm_batch_answer, either as one of the listed options or as the person's own words.

If nobody settles it within Check typed answers for (holdOtherAnswersHours, 12 hours by default), the answer moves on as typed. That also happens 15 minutes before the question's deadline. Set the field to 0 to move typed answers on right away. With no agent beside the form, they always move on as typed.

Reminders

Reminders need an agent beside the form, because the agent writes each one in its own words. Remind after (remindAfterHours) lists hours of quiet, one entry per reminder: [24, 48] by default, at most five, each up to 720. Quiet counts from the latest of these: the form being sent, the person opening it, saving a draft, or sending rows, a message either way in the chat, and the previous reminder. Set it to [], or off in the console, to send no reminders. No reminder goes out when nothing is waiting or the person asked to be contacted later.

When the wait runs out

The link works until the stage's Wait up to runs out. New items joining don't extend it. When it runs out:

  • The link closes, and opening it shows that it has expired.
  • Unsent drafts are discarded.
  • The agent's conversation beside the form ends.
  • Items still waiting fail this attempt and are asked again on a later pass, or become DEAD with no attempts left. See Items and their states.

Watch a form

On the automation's Work tab, an open form is listed with the open questions as Form for its contact slot, with how many rows are drafted. Agent suggestions and held answers count as drafted. A form with an agent beside it is marked with an agent and has Open conversation. An item waiting on a form says Waiting for a person to answer on a form.

Show rows on the question opens the form's rows:

  • At the top, Opened and when, or Not opened yet. This is about the current link: after a new link is sent, it says Not opened yet until the person opens the new one.
  • Each row has a chip: Waiting, Being checked (an answer typed outside the list that the agent beside the form is checking), Answered, or Closed.
  • A row that's still asked shows what's saved on it and when, marked Suggested by the agent, Typed, not on the list, or Not sent yet (a draft the person saved).
  • An answered row shows its answer as stored: an option's value, not its label.

In a workspace that protects what people answer, the rows are withheld.

When the person lost the link, or it never reached them, an Editor can send a new one with Send a new link on the question. It's offered on an open form that went out and hasn't reached its deadline. Once you confirm:

  • The person gets the question again with a new link, through the same channel as before.
  • The old link stops working. Anything saved on the form is kept.
  • It's refused within 5 minutes of the last change to the question, which includes the last link sent, even one that failed to send. The message says when to try again.
  • If the channel doesn't take the message, you see what it said. A new link was still made, so the old one no longer works: fix the channel, then send again.

The agent beside the form can do the same with resend_batch_form_link.

From the CLI

A form's rows in --answers and resend-form-link need CLI 2.3.12 or later.

  • fruxon triggers ledger batches <trigger> lists the open questions and labels a form as a form.
  • fruxon triggers ledger batches <trigger> --answers <batch> shows whether the link has been opened, each row's state on the form, and what's saved on it.
  • fruxon triggers ledger resend-form-link <trigger> <batch> sends a new link. It asks before sending; in agent mode, pass --yes. It exits 0 when the link was sent, 13 when the question is no longer open, 17 when the channel didn't take the message, and 18 when it's too soon, with the time to try again.
  • fruxon triggers ledger cancel-batch <trigger> <batch> takes a form back. The link closes, and the question's items return to READY.

API

EndpointDoes
GET …/ledger/batchesEach question's deliveryMode, which is FORM, or DIRECT when the contact couldn't get a form, and draftCount, the rows saved but not sent
GET …/ledger/batches/{batch}/answersOn a form, form.openedAt, and on each item form.status (WAITING, HELD, ANSWERED, or CLOSED) and, on a row that's still asked, form.draft with value, text, suggested, held, and savedAt. A field with no value is left out.
POST …/ledger/batches/{batch}:resendFormLinkSend a new link. outcome is SENT, TOO_SOON with retryAfter, FAILED with the channel's detail, or NOT_OPEN. Needs triggers:write and Editor access to the Application.
POST …/ledger/batches/{batch}:cancelTake the question back and return its items to READY

See the Automations API for the rest.

Ask with a form from an agent

An agent can send a form during a conversation with the ask_form tool (Ask with a Form, in Chat User Tools). Its run pauses until the person sends the form, then picks up with their answers. Use it when the agent needs several values at once, a choice from options it found, or a table for the person to check, such as the items it read from a photo of a delivery note.

Add the tool to the agent's step in Agent Studio. The agent calls it with:

ParameterWhat it does
titleRequired. Shown at the top of the page and as the message that carries the link.
introOne or two lines under the title.
ttl_hoursHow long the form stays open: 1 to 72 hours, 24 by default.
fieldsRequired. 1 to 10 fields, in the order shown.

Each field has a key (its answers come back under it), a type, and a label, plus an optional description and required (true by default). The types are text, yes_no, choice, multi_choice, number, date, and table:

  • choice and multi_choice take up to 12 options, each a string or value, label, and description. allow_other lets the person type their own answer, with an optional prefill.
  • suggested is the value the page starts with.
  • One field can be a table, with up to 8 columns in the same vocabulary plus read_only, and up to 100 rows.
[
  {
    "key": "supplier",
    "type": "choice",
    "label": "Which supplier is this?",
    "options": [{ "value": "sup_812", "label": "Green Leaf Market", "description": "Company no. 514389568" }],
    "allow_other": { "label": "New supplier", "prefill": "Green Leaf Ltd" },
    "suggested": "sup_812"
  },
  {
    "key": "items",
    "type": "table",
    "label": "Items",
    "columns": [
      { "key": "sku", "label": "SKU", "read_only": true },
      { "key": "name", "type": "text", "label": "Name" }
    ],
    "rows": [{ "sku": "10002", "name": "Oregano" }]
  }
]

The person gets a message with the title and the link. The agent never sees the link, so it shouldn't write one or repeat the questions in the chat. On the page, the person can save a draft, and sends the whole form at once with Send answers. If an answer is missing or refused, the marked fields have to be fixed before the form can be sent.

ask_form works only in a direct conversation with a known person, not in a group, and with one open form at a time. Don't use it for passwords, card numbers, or other secrets. An operator can't answer an ask_form form from the Inbox.

What comes back

The tool's result has a status:

StatusMeaning
submittedThe person sent the form. The answers are in the result, by field key.
person_wrote_againThe person wrote in the chat instead. The form stays open. If they send it later, the answers reach the agent as a new message.
expiredThe form wasn't sent before ttl_hours ran out.
withdrawnThe run was cancelled, so the form was taken back.
not_submittedThe form wasn't sent for another reason. The agent is told to say so and offer to send it again.

Form stages and ask_form compared

Form stageask_form
FieldsOne answer column, a row per itemUp to 10 fields, one of which can be a table
SendingRow by row, some now and the rest laterThe whole form at once
Open forUp to 720 hoursUp to 72 hours
An agent beside it, suggestions, reminders, new items joiningYesNo

Next steps

On this page