Guides
Profile Endpoint
To ensure seamless integration and efficient data synchronisation, it is necessary for you to implement the Profile Cloning Endpoint on your end. This endpoint will serve as a critical connection point, enabling us to retrieve your profiles data when required.
Your endpoint must implement the Profile Endpoint OpenAPI webhook specification.Siblings, favourites and home
Three optional additions let the persona profile carry more of her life: her brothers and sisters, her favourite titles, and her home. Send any of them, all of them, or none: a Persona without them is unchanged.
{
"city": "Paris",
"countryCode": "FR",
"neighborhood": "Montmartre",
"siblings": [
{ "name": "Thomas", "gender": "MAN", "age": 18 }
],
"features": {
"livingWith": "ROOMMATE",
"housingType": "APARTMENT",
"favorites": {
"movies": ["Matrix", "Gladiator"],
"tvShows": ["Casa de Papel"]
}
}
}| Field | Where | What it holds |
|---|---|---|
siblings | Root, like children | Up to 10 brothers and sisters, each with an optional name (cut to 32 characters), gender and age (a whole number from 0 to 120). An entry with none of these is ignored. |
neighborhood | Root, like city | The district she lives in, cut to 64 characters. Used only when countryCode is set, as city is. |
features.favorites | features | Her favourite titles, in up to four lists: movies, tvShows, books and music. Each list keeps its first 5 titles, each cut to 64 characters. |
features.housingType | features | The kind of home she lives in: APARTMENT, HOUSE, STUDIO, SHARED_FLAT or OTHER. |
- Persona profiles only. These fields are ignored on the user profile.
- Never rejected. A value we can't read (an unknown
housingTypeor siblinggender, afavoritesthat isn't an object, a list that isn't an array of titles) is ignored, and the rest of the profile is used as usual. - Her neighbourhood stays private. The Persona names her neighbourhood when the User asks where she lives, and may mention it in passing. She never gives a street, an address or a place to meet.
- One field per fact.
livingWith: ROOMMATEsays who she lives with;housingType: SHARED_FLATsays what kind of home it is.musicGenreslists the genres she likes;favorites.musicnames specific artists, albums or songs.
We keep a copy of each profile until its expiresAt. After adding these fields to existing Personas, give each profile a new version and send that same value as personaProfileVersion when you queue the conversation, so we fetch the profile again instead of using our older copy.
Working schedule
By default, a Persona with a job follows a made-up routine: at work from 9:00 to 17:00, with random days off, mostly on weekends. To make her talk about work at the hours that fit her job, send her working days and hours in features.workSchedule on the persona profile. It is optional: Personas without it keep the default routine, unchanged.
"features": {
"job": "Nurse",
"workSchedule": {
"MONDAY": { "start": "08:00", "end": "17:00" },
"TUESDAY": { "start": "08:00", "end": "17:00" },
"WEDNESDAY": { "start": "08:00", "end": "17:00" },
"FRIDAY": { "start": "22:00", "end": "06:00" }
}
}- One shift per day. Use the upper-case day names
MONDAYtoSUNDAY. A day you leave out is a day off: the Persona never works it. - 24-hour
HH:mmtimes, in the Persona's owntimeZone(UTC when it's missing). Anendearlier than itsstartends the next morning, as with the Friday night shift above. - Days off still happen. On a scheduled day the Persona occasionally takes the day off, as anyone does.
- What she says. She's at work during her shift, about to leave shortly before it, done for the day after it, and well before it she says she starts work later today. She also knows her hours and talks about them consistently.
- When it is ignored. Without a
job, withworkingset tofalse, or on the user profile. A schedule we can't read (an unknown day, a time that isn'tHH:mm, astartequal to itsend, or no day at all) is ignored rather than rejected: the Persona simply keeps the default routine, and replies are never blocked.
We keep a copy of each profile until its expiresAt (24 hours when you don't send one), and changing the profile on your endpoint doesn't replace that copy before then. To apply a new schedule right away, give the profile a new version and send that same value as personaProfileVersion when you queue the conversation: we fetch the profile again whenever it differs from the copy we hold. To check what we read, use Test Profile Endpoint in your project settings: a schedule we accepted is listed day by day; if it's missing or empty there, we ignored it. You can also try schedules in the Playground under the Persona's Job, or load the Working schedule test scenario.
The field is used by the chat-2 models. See the Profile data type for the full definition.