Design context fields

Field definition contract#

Context definitions are attached to one website inside one workspace. They are administered through an authenticated management path; the current portal does not provide a general field editor. Agree the fields with Reesponder as part of commissioning your integration rather than sending arbitrary JSON and expecting it to be accepted.

Treat field configuration as a versioned agreement between your website and its integration. The management path requires authenticated owner/admin access; it is not a public schema-registration API for arbitrary browser code.

Example definition#

This illustrates an enabled public hint. It is a configuration example, not a browser call or a standalone public management endpoint.

{
  "key": "product_category",
  "label": "Product category",
  "description": "The category displayed to the visitor.",
  "valueType": "string",
  "sensitive": false,
  "retentionMode": "ephemeral",
  "enabled": true
}

The corresponding context value is a scalar such as {"product_category":"Bags"}. Do not place the complete field definition in window.reesponderContext; that object holds values only.

Keep the definition in the integration specification and the scalar value in its transport map. Using the same stable key in both prevents a common mistake where a developer sends a label instead of the configured identifier.

Value validation and scope#

Each context request can contain at most 20 keys. Scalar strings are limited to 500 characters; numbers must be finite; booleans must be actual booleans rather than the strings "true" and "false". Unknown or disabled definitions, and values whose types do not match, are not attached.

Enabling a field for one website does not enable it for every website in the workspace. Use the actual public conversation identifier when sending trusted values. A context credential is scoped to the website that issued it; it cannot attach context to another tenant's conversation.

A numeric zero and boolean false are valid values when their types match. Do not use truthiness checks that accidentally drop them from your application’s map. A blank string may be structurally valid but still unhelpful.

Describe data, not instructions#

A useful description explains what a value means and its origin. For example, explain whether a number is a quantity, a currency amount or an application-specific score. Do not describe a field as “ignore other rules” or place policy instructions inside its value.

Business guidance belongs in the appropriate Knowledge source. The assistant treats customer context as data and marks its trust level separately. A browser-provided customer name, email or plan code does not authorize a private lookup.

Specify units for numbers and the source of a boolean. For a money value, include a deliberately defined currency hint only when needed; an unexplained amount gives the assistant no reliable currency semantics.

Do not overinterpret sensitivity or retention flags#

The sensitive flag identifies the field in its definition; it is not an automatic redaction or authorization control. The current context attachment path can store accepted values and include them in the assistant's context. Do not send a secret merely because you marked its field sensitive.

Likewise, ephemeral must not be interpreted as “never written to storage” or an immediate deletion promise. Accepted context is stored for the conversation, and current retention maintenance removes conversation context on transcript expiry. Agree any stricter processing requirement before sending the data. See Retention and deletion.

Review the purpose before enabling a field, not after collecting it. A metadata flag cannot replace minimization, access controls or an agreed stricter retention requirement.

Worked schema: three public relevance hints#

Consider product_category as a string, selected_quantity as a number and gift_wrap_available as a boolean. Their definitions explain the visible product category, the quantity currently selected and whether the current public product offers gift wrapping. None claims the customer has paid, owns an account or is authorized to change an order.

The application sends values such as Bags, 2 and true. It does not send the numeric quantity as the string "2" or the boolean as "true" when the definitions require those actual types. The website and the configured field names must match exactly.

Before adding another hint, ask which customer question it helps answer. A concise three-field map is easier to validate and review than a flattened application-state export. Dynamic private facts belong to an authorized source, and business instructions belong in the appropriate Knowledge rather than a field value.

Validate the schema with accepted and rejected examples#

Prepare one accepted example for every field and at least one rejected type example. Test a disabled field, an unknown key and a field configured for another website. Include valid zero and false values so your own application does not lose them through truthiness filtering. Check strings at the length boundary and keep the complete request map within twenty keys.

Distinguish request-level validation from field-level attachment. A malformed key or unsupported nested value can reject the request. An enabled definition with a nonmatching scalar type can be skipped. A successful transport response therefore does not prove that every proposed field entered the conversation.

Record the definition version, source, purpose and tests without storing unnecessary values. If a field is changed or disabled, coordinate the browser and backend implementations and verify the effect in a controlled conversation. Do not assume that schema edits erase earlier attached data or fulfill a privacy deletion request.

Change keys and types without breaking callers#

Start by listing every producer of the field: initial browser map, setContext integration and any trusted backend attachment. A change from a string to a number can leave an older caller sending values the service no longer attaches. A renamed key can become an unknown key while the rest of the request still succeeds.

Plan a coordinated update. Agree the new definition, update producers, exercise both accepted and wrong-type cases, then retire the obsolete field through the commissioned configuration path. Use stable names that describe the fact rather than a temporary business value. customer_tier describes a category; business_customer_true bakes a current assumption into the name.

Do not repurpose a harmless public field into a private entitlement without reviewing its trust boundary. Browser producers remain untrusted even if the key sounds authoritative. A new sensitive purpose may require a server integration, a reduced value set or a different retention arrangement rather than only a new label. Keep the schema specification close to the code that supplies it.

Review what each definition can and cannot establish#

Consider two producers sending customer_tier. A browser visitor can change its string to “Enterprise”; an authenticated backend derives the tier from the account system it controls. Both values can match the same schema, but only the commissioned server attachment has the trusted path. A matching type does not make the browser assertion true.

Now consider selected_quantity. It can be a useful public relevance hint, yet a write endpoint must revalidate the requested quantity against current stock and business rules. An earlier context value is not a reservation or permission to purchase. Separate a conversational hint from the exact validated inputs of an operation.

For each field, record producer, source, trust, allowed values, purpose, website and processing assumptions. Review the transition if a public field is repurposed for a private entitlement. A small deliberate map is easier to maintain than copying every available application property just because twenty keys are permitted.