Persona API

Overview

The Persona API provides read and update access to your AI Agent’s persona - the settings that define how the AI Agent communicates, configured in the dashboard under Config > Settings > Preferences. The persona controls the AI Agent’s personality, tone, emoji usage, and manners, so you can manage these settings programmatically instead of only through the dashboard.

The persona is a single configuration object per AI Agent. Agent identity settings (the Agent’s name and avatar) are not part of the persona and are not managed through these endpoints.

Endpoints

Two endpoints are available:

Get persona (GET /v2/persona): Returns the current persona configuration.
Update persona (PATCH /v2/persona): Partially updates the persona. Only the fields included in the request body are changed; omitted fields keep their existing values. A field that is not part of the public persona schema returns a 400.

Fields

The following fields are read through GET and can be written through PATCH:

Field	Type	Description
`personality`	array of strings	Personality traits that shape the Agent’s tone (for example, `friendly`, `professional`).
`emoji_usage`	boolean	Whether the Agent may use emoji in replies. Applies to messaging and email channels.
`allowed_emojis`	string	A string of emoji the Agent is limited to. When set, the Agent uses only these emoji; when empty, it may use any emoji that fit the message.
`default_timezone`	string	An IANA time zone identifier (for example, `America/Toronto` or `UTC`) used for time references. An unrecognized value returns a `400`.
`company_description`	string \| null	A description of the company’s products and services.
`community_guidelines_url`	string \| null	A link to community guidelines the Agent should follow.
`message_length`	string	Preferred reply length. One of `concise` or `normal`.
`ask_for_more_help`	boolean	Whether the Agent asks if more help is needed.
`no_customer_pi`	boolean	Whether the Agent avoids mentioning end users’ personal information.
`no_competitors`	boolean	Whether the Agent avoids discussing competitors. When enabled, list the names to avoid in `competitor_names`.
`competitor_names`	string \| null	A comma-separated list of competitor names the Agent should avoid mentioning. Used only when `no_competitors` is enabled.
`enable_acknowledgment_messages`	boolean	Whether the Agent sends acknowledgment messages.

For guidance on configuring these settings, see Persona and Personality setup.

Authentication

Requests are authenticated with a Bearer API key. See Authentication for details on generating and using API keys.