Audiences

Audiences let you segment users so you can deliver different guidance, knowledge, and tool access to different groups. You define an audience once, then attach it to guidance rules or data providers. Conversations that don’t match any audience filter receive guidance set to “Everyone.”

Creating Audiences

Navigate to Settings → Audiences
Click Create audience
Name it descriptively (for example, “Enterprise EU Customers”)
Build segmentation rules using the query builder
Save

Combine multiple conditions with AND/OR logic. The root-level group always uses AND logic.

Audience creation form with query builder showing AND/OR logic for segmenting users

Available Fields

Every field below is available in the audience builder and as a Liquid variable. Time fields use UTC.

Field	Type	Description
`channel.type`	Select	Channel of the conversation: `browser`, `app`, `api`, `slack`, `whatsapp`, `zendesk`, `salesforce`, or `voice`
`channel.browser.url`	Text	Page URL where the chat runs
`channel.browser.user_agent`	Text	Browser user agent
`channel.slack.team_id`	Text	Slack workspace ID
`channel.slack.team_name`	Text	Slack workspace name
`channel.whatsapp.phone_number`	Text	Your WhatsApp business number
`channel.zendesk.subdomain`	Text	Zendesk subdomain
`channel.zendesk.group_id`	Select	Zendesk group of the ticket
`channel.zendesk.brand_id`	Select	Zendesk brand of the ticket
`channel.zendesk.tags`	Multiselect	Zendesk ticket tags
`channel.zendesk.is_private_mode`	Boolean	Whether the Zendesk integration runs in private mode
`channel.voice.direction`	Select	`inbound` or `outbound` call
`channel.voice.from_number`	Text	Calling phone number
`channel.voice.to_number`	Text	Called phone number
`user.id`	User	botBrains user ID
`user.external_id`	Text	Your ID for the user
`user.email`	Text	Email address
`user.phone`	Text	Phone number
`user.first_name`	Text	First name
`user.last_name`	Text	Last name
`user.name`	Text	Full name
`user.zendesk_id`	Text	Zendesk user ID
`user.slack_id`	Text	Slack user ID
`user.whatsapp_id`	Text	WhatsApp ID
`user.timezone`	Text	Timezone, for example `Europe/Berlin`
`user.locales`	Multiselect	Preferred languages
`user.labels`	Multiselect	Labels on the user
`user.external_attributes`	JSON	Custom attributes you pass for the user
`user.external_id_signed`	Boolean	Whether your server signed the external ID
`user.email_signed`	Boolean	Whether your server signed the email address
`user.phone_signed`	Boolean	Whether your server signed the phone number
`user.created_at`	Date	When botBrains first saw the user
`user.last_seen_at`	Date	When the user was last active
`conversation.id`	Text	botBrains conversation ID
`conversation.external_id`	Text	Your ID for the conversation, for example the ticket ID
`conversation.integration_type`	Select	Integration that created the conversation
`conversation.tags`	Text	Conversation tags
`conversation.labels`	Multiselect	Labels on the conversation
`conversation.length`	Number	Number of customer messages
`conversation.messages.count`	Number	Number of messages
`conversation.created_at`	Date	When the conversation started
`conversation.updated_at`	Date	When the conversation last changed
`conversation.first_message_at`	Date	Time of the first message
`conversation.last_message_at`	Date	Time of the last message
`conversation.attributes.<key>`	Attribute type	Value of a conversation attribute
`time.date.now`	Date	Today’s date
`time.datetime.now`	Datetime	Current date and time
`time.hour`	Number	Current hour, `0` to `23`
`time.day_of_week`	Number	Current weekday, `0` for Monday to `6` for Sunday
`time.day_of_month`	Number	Current day of the month
`time.month`	Number	Current month, `1` to `12`
`time.year`	Number	Current year
`time.timezone`	Text	Timezone of the time fields

Operators

Type	Operators
Text	is, isn’t, contains, starts with, ends with, is empty, isn’t empty
Number	is, isn’t, less than, greater than, between, is empty
boolean	is true, is false
Date	is, before, after, between dates, in the last, in the next, is empty
Select	is one of, isn’t one of
multiselect	contains, contains any of, contains none of, is empty
JSON	text is, number is, boolean is, contains, path exists

Examples

VIP customers:

User External Attributes -> JSON text is -> "tier" = "enterprise"
AND User Labels -> contains any of -> ["vip", "premium"]

After-hours support:

(Current Hour -> less than -> 9 OR Current Hour -> greater than -> 17)
AND User Timezone -> contains -> "America"

New Zendesk users:

Channel Type -> is one of -> ["zendesk"]
AND User Created At -> in the last -> 7 days

Where to Use Audiences

Guidance rules. Attach an audience to a guidance rule to scope its instructions and tools to matching conversations. See Instruct AI Agent. Data providers. Assign a default audience to a data provider so new sources automatically inherit the scope, making knowledge available only to matching users. Knowledge sources. Scope individual sources to specific audiences so users only see relevant documentation.

Getting Started

botBrains Engineer

Train

Test

Deploy

Users

Creating Audiences

Available Fields

Operators

Examples

Where to Use Audiences

​Creating Audiences

​Available Fields

​Operators

​Examples

​Where to Use Audiences

Creating Audiences

Available Fields

Operators

Examples

Where to Use Audiences