Input fields and customer-visible results

Define stable input keys#

An Action has up to eight inputs. Each key starts with a lowercase letter and contains lowercase letters, digits or underscores, with a maximum length of 40 characters. Keys must be unique. A customer label is required and can be up to 80 characters.

The following keys are reserved: verified_email, customer, idempotency_key, __proto__, constructor and prototype. Choose a task-specific key such as order_reference, product_code or preferred_date instead.

Required fields must contain a nonblank string. Input values are trimmed and limited to 1,000 characters each. Values that have not been defined are rejected. The runtime does not pass an arbitrary conversation object to your endpoint.

Keep keys machine-oriented and labels customer-oriented. A label can explain “Reference printed on your order confirmation” while the key stays order_reference. Renaming a key changes the request contract; update the endpoint and repeat the test accordingly.

Validate business formats at your endpoint#

Custom Action inputs are strings. A date such as 2026-10-15, a quantity such as 2 and a stock reference such as SKU-104 remain strings in the request. Parse and validate their formats in your own service.

Check acceptable dates, lengths, ranges and enumerated values before changing anything. A field label such as “Quantity” is a collection hint, not a database constraint. Where the task depends on authorization or availability, validate those conditions at execution time, even if a previous read showed them.

The same distinction applies to optional values. An omitted optional string should have a documented default in your service. It should not mean unrestricted search, unlimited quantity or permission to change all records.

Map scalar JSON fields#

Custom HTTP requires at least one result mapping and permits up to eight. Paths use dot notation: status, reference and order.delivery_date. Each segment contains letters, digits or underscores. A full path can be up to 150 characters, and its customer-visible label up to 80.

Only string, number and boolean values are exposed. They are converted to text and limited to 1,000 characters per result. Nulls, objects, missing fields and unmapped data are omitted. Do not design a mapping around a raw array or the complete order object; return a deliberate scalar summary instead.

Output paths are an allowlist, not a way to browse arbitrary provider objects in the widget. Protected property names are rejected in any path segment. Design an explicit response object rather than using internal object shapes as a permanent public contract.

Return a useful summary#

{
  "order": {
    "reference": "ORDER-1042",
    "status": "Dispatched",
    "delivery_date": "2026-10-08"
  },
  "internal_note": "Staff-only note"
}

Map order.reference to “Order”, order.status to “Status” and order.delivery_date to “Expected delivery”. The internal note is not a customer result. Prefer omitting sensitive data at your endpoint as well, rather than relying only on the mapping filter.

If all mapped values are missing or nonscalar, the run reports output_mapping_empty. A 2xx response by itself is not a useful Action result. Match the JSON spelling and nesting exactly, and rerun the saved test after a mapping change.

A false boolean and the number zero are scalar values and can be displayed. Test these intentionally: an available quantity of zero is meaningful information, while a missing quantity is an absent result. Do not make your adapter collapse the two states.

Include links deliberately#

A mapped full HTTPS URL can become a labeled result link in the widget. Return a destination customers are allowed to open, such as an account page or a request confirmation page. Do not put an API bearer credential in that URL. Private downloads need their own appropriately scoped authorization.

Keep status statements factual. Returning “Request received” is different from “Refund approved” or “Booking confirmed”. Your endpoint owns that distinction, and Reesponder can only display the data it receives. Write result fields for the real state of the business operation.

Use a status and a reference alongside a link so the outcome remains understandable even if the visitor does not open it. The destination page has its own authentication boundary and must not disclose another customer's record merely because the URL is known.

Worked example: an appointment request#

A service accepts a request for a callback at a preferred date. Define required strings service_reference and preferred_date, plus an optional notes field. The labels explain the expected date format and what the visitor should include. Your endpoint parses the date, rejects past or unavailable dates and enforces the relevant customer authorization.

Do not infer typed validation from the label. The string “next Tuesday” and 2026-10-15 are both strings in the request, but your service must decide which formats it supports. If an optional note is omitted, choose a safe documented default rather than forwarding an undefined value into business logic.

Return a small JSON object such as {"request":{"reference":"REQ-1042","status":"Received for review"}}. Map request.reference and request.status. The response says that a request was received; it should not say “Appointment confirmed” unless the owning booking system has actually reserved the appointment.

Test an allowed date, a disallowed date and an omitted optional note. Check both the endpoint's recorded request and the displayed result. A well-formed card is not evidence that the date was valid or that a reservation occurred.

Check the actual field boundary#

Test a blank required value, an unknown input key, a long string and a value with leading or trailing whitespace. Confirm that the endpoint receives only the defined trimmed strings and any separately verified identity. Do not design a contract around arbitrary transcript content.

For results, test a known string, zero, false, a missing path, a null and a nested object. The first three are scalars; the latter cases are omitted. Test a response with a staff-only field and confirm it is not displayed. Save and rerun the test after changing a key, path or label.

Write a field contract that survives changes#

For each input, document four things: the stable key, the customer label, whether it is required and the validation applied by the destination. This gives your support team a way to understand a rejected value without asking a developer to inspect a raw payload. For order_reference, specify which reference appears on the confirmation and whether a leading # is accepted.

For each output, record the exact JSON path, its customer label and the business meaning. “Status” may mean delivery state, request-processing state or payment state. Use a more specific label when those could be confused. Return the currency with an amount or provide a formatted customer-safe amount; a bare numeric total is often ambiguous.

Changing an input key is a contract change, even when the visual label is identical. Coordinate the endpoint update with the Action revision. Changing only a result label still requires a new test because it changes what the customer sees.

Keep examples synthetic and representative. Include optional omissions and a normal negative business result, not just the largest successful provider record. This documentation can be a short shared specification; it should not contain the bearer token or another customer's details.

Diagnose a response that looks empty or misleading#

When the endpoint returns 2xx but the card has no useful result, compare the response object with the saved mappings. Spelling and nesting must match exactly. If the response changed from order.status to status, the old path cannot find the value. Do not repair this by mapping the entire object; add the correct scalar path and retest.

If only some fields are missing, inspect whether their values are absent, null or nonscalar. A response that contains an array of shipments needs your adapter to summarize the intended shipment into a scalar field. The widget is not a table renderer for arbitrary nested arrays.

If a displayed value is misleading, inspect its meaning rather than only its path. An internal code such as queued_review should become an accurate customer-safe description in your adapter. Do not rename a pending request “Complete” just to make the result look positive.

Keep debugging data in authenticated server logs linked to the run reference. Return the minimum intended result to Reesponder. Test the repaired contract with an expected fixture, then enable the new saved revision so a previous successful test cannot approve stale paths.