Skip to main content

Build an agent preferences screen

Section: DOC-CP-identity-access-end-users#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.

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: DOC-CP-identity-access-end-users#read-the-profile.

curl -X POST https://api.travila.ai/api/v1/enduser/get \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Reference: Get the caller's end-user profile · Request fields.

Response:

{
  "endUser": {
    "subject": "user_123",
    "tenantId": "tenant_abc",
    "email": "jane@example.com",
    "emailVerified": true,
    "name": "Jane Doe",
    "givenName": "Jane",
    "picture": "https://…",
    "signInProvider": "google.com",
    "locale": "en-US",
    "zoneinfo": "Europe/London",
    "location": {
      "latitude": 51.5072,
      "longitude": -0.1276,
      "timezone": "Europe/London",
      "updatedAt": "2026-08-14T09:31:02Z"
    },
    "localeOverride": "es-MX",
    "defaultGenerationConfig": {
      "model": "google/gemini-3.6-flash",
      "temperature": 0.4,
      "languagePreference": "es"
    },
    "metadata": {
      "preferredView": "compact"
    },
    "firstSeenAt": "2026-01-14T09:12:00Z",
    "lastSeenAt": "2026-08-14T09:30:58Z",
    "updatedAt": "2026-08-14T09:31:02Z",
    "createdAt": "2026-01-14T09:12:00Z"
  }
}

Reference: Get the caller's end-user profile · Response fields.

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: DOC-CP-identity-access-end-users#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.

curl -X POST https://api.travila.ai/api/v1/enduser/update-locale \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "locale": "es-MX"
}'

Reference: Update the caller's locale override · Request fields.

Response: {} on success.

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

{
  "locale": ""
}

Reference: Update the caller's locale override · Request fields.

3. Offer supported model and response preferences​

Section: DOC-CP-identity-access-end-users#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.

curl -X POST https://api.travila.ai/api/v1/enduser/update-generation-config \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "model": "google/gemini-3.6-flash",
    "temperature": 0.4,
    "maxOutputTokens": 2048,
    "languagePreference": "es"
  }
}'

Reference: Update the caller's default generation config · Request fields.

Response: {} on success.

Variant: remember a display preference​

Section: DOC-CP-identity-access-end-users#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.

curl -X POST https://api.travila.ai/api/v1/enduser/update-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "preferredView": "compact",
    "dismissedWelcome": "true"
  }
}'

Reference: Update the caller's metadata · Request fields.

Response: {} on success.

To delete a key explicitly:

{
  "metadata": {
    "dismissedWelcome": ""
  }
}

Reference: Update the caller's metadata · Request fields.

Section: DOC-CP-identity-access-end-users#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: DOC-CP-identity-access-end-users#update-location.

curl -X POST https://api.travila.ai/api/v1/enduser/update-location \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "latitude": 51.5072,
  "longitude": -0.1276
}'

Reference: Update the caller's location · Request fields.

Response:

{
  "location": {
    "latitude": 51.5072,
    "longitude": -0.1276,
    "timezone": "Europe/London",
    "updatedAt": "2026-08-14T09:31:02Z"
  }
}

Reference: Update the caller's location · Response fields.

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: DOC-CP-identity-access-end-users#related.

Document ID: DOC-CP-identity-access-end-users. Section identities and revisions.