Provide trusted server context

Commission the complete integration#

Before implementation, arrange enabled context field definitions, a site context credential and the way your backend receives the correct public conversation identifier. The current portal does not expose a context-credential button, and the stock widget does not emit a public conversation-ID callback.

Use Reesponder support to commission this lifecycle rather than scraping private widget state or exposing an internal management session to your application. A value labeled conversationId in your own database is not necessarily the public Reesponder conversation UUID.

Define who creates the mapping, when it becomes available, how it is authenticated and what happens if it is missing. Production attachment code should fail safely rather than guess a conversation identifier from an internal browser key.

Authenticate and authorize on your backend#

Your server must verify the application's customer session and decide which facts that customer is allowed to share. Reesponder verifies the supplied site's context credential and the target conversation's site boundary. It does not independently prove that a customer ID you send belongs to the logged-in person.

Keep the context credential in your server's secret configuration. Do not place it in the widget snippet, page source, frontend bundle, localStorage, URL or downloadable example. Send it only as Authorization: Bearer … over HTTPS. Issuing a replacement site context credential invalidates the previous one.

Authorize each record before deriving the value. An account ID supplied by the browser is input to check, not a trusted lookup permission. Limit the context credential to the agreed site and keep its version in your server configuration.

Request format#

Send POST https://api.reesponder.com/v1/widget/context/trusted with a JSON body containing the public conversation UUID and a bounded map of configured values. In this example, customer_tier must already be an enabled string field. The shell variables must be populated securely before running the request.

curl --request POST \
  'https://api.reesponder.com/v1/widget/context/trusted' \
  --header "Authorization: Bearer $REESPONDER_CONTEXT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "conversationId": "YOUR_PUBLIC_CONVERSATION_UUID",
    "values": {
      "customer_tier": "Business"
    }
  }'

A successful attachment returns 204 No Content. Do not attempt to parse a JSON body on that response. The uppercase UUID placeholder must be replaced with a real UUID received through the commissioned lifecycle.

The example is not a complete lifecycle implementation. It assumes field definitions, a private credential and an authorized mapping already exist. Do not run it with documentation placeholders or embed the shell credential in a customer-facing page.

Validation and update behavior#

The map permits at most 20 fields. Keys follow the lowercase identifier format; values are strings up to 500 characters, finite numbers or booleans. Only enabled definitions with matching types are accepted. A structurally valid request can succeed while an unknown field contributes no value, so verify your definitions before testing answer behavior.

Trusted values update their matching conversation fields. Subsequent untrusted browser context cannot replace an existing trusted value. This trust boundary is separate from the Action's customer-verification requirements; adding a trusted email field does not automatically verify an Action identity.

The request’s success means the target was authorized and structurally valid; it does not provide a per-field acceptance report. Test unknown and wrong-type definitions explicitly rather than treating a 204 response as proof that every submitted value was stored.

Handle errors without exposing secrets#

400 invalid_context_request indicates an invalid body or missing bearer-format authorization. 403 context_not_authorized indicates that the credential or target site/conversation boundary is not accepted. This endpoint is rate-limited to 120 requests per minute.

Do not solve an authorization failure by posting the credential in a support chat. Record the HTTP status, safe error code, time and field names, with values redacted. Before retrying, check the conversation mapping, credential version and website association. An Action provider's secret or installation token cannot substitute for the context credential.

A successful retry can update matching fields again, so keep repeated submissions deliberate and use the same authorized fact source. Do not repeatedly regenerate credentials to investigate a mapping error.

Worked example: attach an authorized customer tier#

Your server authenticates its own customer session and loads that customer’s current tier from its authoritative account system. The commissioned lifecycle supplies the correct public Reesponder conversation UUID for this website. Your server sends a string such as Business under the enabled customer_tier definition with the private site context bearer credential.

Reesponder verifies that the credential belongs to the target conversation’s website. It does not independently prove that your application chose the right customer. The ownership decision must therefore happen before the server sends the value. Do not accept an arbitrary account number in a request and attach another person’s facts.

After a 204 response, test a relevant safe question in the agreed lifecycle and verify that the fact is useful. Then test an unrelated-site conversation and an invalid credential; those must not authorize attachment. Browser hints cannot replace the stored trusted value, but this tier does not automatically verify an Action email or authorize a private write.

Test authorization, mapping and failure handling#

Use an authorized test customer and a controlled conversation mapping. Test the expected site, another site’s conversation, an unknown field, a disabled field, a wrong scalar type and a stale credential. Verify the 204 response without parsing JSON. Check your application’s logs contain status, timing and safe identifiers rather than the bearer secret and private context values.

Test missing mapping and expired application-session paths. The backend should decline to attach data it cannot authorize, not invent a public conversation UUID or fall back to a browser installation token. Have a documented rotation plan that updates the server configuration when a replacement context credential is issued.

Keep trusted context distinct from private Action verification and outcome recording. A submitted trusted field does not silently enable an Action, remove confirmation or prove an external event. Acceptance should name the complete commissioned lifecycle and the narrow facts it attaches, with any unimplemented hooks or stricter processing requirements identified before launch.

Rotate only as a coordinated server deployment#

Issuing a new website context credential replaces the hash used for authorization. A server still using the old value will receive an authorization failure. Treat rotation as a coordinated configuration deployment, not a routine response to every authorization or field-mapping issue. Prepare the new server configuration and rollout path before changing the credential.

Keep the credential out of client bundles, HTML, URLs, browser storage and public examples. A token placed in an environment variable is only private if that variable stays server-side and is not serialized into frontend code. Review your framework’s distinction between public and private configuration rather than choosing a reassuring variable name.

After a deliberate rotation, verify the new credential against an authorized conversation and the expected enabled field. Confirm the old credential no longer authorizes a new attachment. Keep a safe version label and deployment time for diagnostics, but do not log the raw secret. Your installation token, Action provider token and customer session all have different purposes and cannot substitute for this credential.

Agree the data lifecycle before sending private facts#

Review the purpose, field definition, source, trust and retention assumptions for each value. Send only the facts that the conversation needs. A tier or entitlement summary is usually easier to review than an entire account object. Nested objects are outside the transport contract; flattening them does not remove the need for authorization and minimization.

Accepted values are stored for conversation use. The sensitive metadata flag does not automatically redact them, and ephemeral mode does not mean they are never persisted. If your business needs stricter processing than the documented conversation retention path, agree it before enabling the integration. Do not add private data first and rely on clearContext in the visitor’s browser to remove it later.

Define how your backend handles sign-out, account switching and updated facts in the commissioned lifecycle. Those transitions must preserve the correct customer/site/conversation relationship. The current stock widget’s two context methods do not supply that authenticated lifecycle, and a reload can retain a conversation identifier. Document the complete behavior rather than relying on an implementation detail.