Skip to main content

Build an agent preferences screen

Section ID: Guide/jb948nrncm#manage-end-user-settings

Let a person choose the language their assistant uses and, if your application offers it, a preferred model. Start with those reversible preferences. Add location only for a feature that needs it and can explain its use; this API currently has no clear-location operation.

After sign-in, load the profile, render saved choices with their inherited defaults, save only what the person changes, and read the profile back. Use the subsequent conversation to observe the result; model behavior can still differ from the saved preference.

The end-user record holds those saved preferences. Identity claims may be copied from the accepted sign-in token; a profile can be empty until information has been captured or saved.

The platform reads this record on every turn. Location and locale can inform context preparation when the corresponding capability is enabled. They do not guarantee that a model always uses the correct timezone or language.

Info: Every call is scoped to the caller

These request bodies do not select a user. Use a publishable key with that user's accepted JWT, or a backend secret key with the permitted X-On-Behalf-Of header. Your backend must identify the user from its authenticated application session, not accept an arbitrary user ID from a client.

1. Load the saved settings and account defaults​

Section ID: Guide/jb948nrncm#read-the-profile

Response example: Get the caller's end-user profile. Example identifiers and values are illustrative; substitute authorized values.

Render the saved preferences and available account defaults. An empty profile is a valid starting point for the settings screen.

2. Save the user’s preferred language​

Section ID: Guide/jb948nrncm#update-locale

When the person chooses another language, send its BCP-47 tag below. Read the profile again to confirm the override. Offer “use sign-in language” by clearing the override rather than guessing the identity-provider default.

Request example: Update the caller's locale override. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: {} on success.

Send an empty string to clear the override and fall back to the identity-provider locale:

Request example: Update the caller's locale override. Example identifiers and values are illustrative; substitute authorized values.

3. Offer supported model and response preferences​

Section ID: Guide/jb948nrncm#update-default-generation-config

Expose only the supported preferences your application intends users to control. Save the selected values, then read the profile back. A per-message or agent-profile choice can take precedence, so explain why a conversation may use a different setting.

Request example: Update the caller's default generation config. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: {} on success.

Variant: remember a display preference​

Section ID: Guide/jb948nrncm#update-metadata

Use metadata for an application preference such as the compact display shown below. Start from the current profile, merge the changed value, and read it back; removing a key restores your application’s own fallback rather than assigning a privileged account state.

User-editable key/value preferences. Never use this metadata as the authority for paid tiers, staff roles, access grants or onboarding completion; those require separately controlled records.

Request example: Update the caller's metadata. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: {} on success.

To delete a key explicitly:

Request example: Update the caller's metadata. Example identifiers and values are illustrative; substitute authorized values.

Section ID: Guide/jb948nrncm#location-consent-and-freshness

Coordinates are sensitive, and the current user record stores the submitted precise location. Weather results rounded to a grid do not mean the precise submitted location is absent from records or traces. Request location only for a clear user purpose, record capture time and distinguish it from lookup/cache time. The current public reference has no clear-location operation; do not promise that sending (0, 0) clears consent or location. Zero coordinates are geographically valid.

Variant: use location for local-time context​

Section ID: Guide/jb948nrncm#update-location

Request example: Update the caller's location. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response:

Response example: Update the caller's location. Example identifiers and values are illustrative; substitute authorized values.

Do not send a timezone. Travila derives the IANA zone from the coordinates and returns it in the response. This gives the agent context for phrases such as “this evening”; confirm the interpreted time before scheduling an important action.

Section ID: Guide/jb948nrncm#related

Document ID: Guide/jb948nrncm