Custom facts

Custom facts are the details AI analysis extracts from every customer conversation, such as an order number, a recipient name, or a policy number. Use custom facts to define the details that matter to your business. AI analysis then looks for these details in each conversation analyzed after you save the fact, and records them for that person. Extracted facts appear in the AI customer context card in Inbox and on the person profile. Custom facts are part of Customer context, which turns conversation history into a reusable customer summary and facts.

To access custom facts, go to Customer Profiles → Configuration → Custom facts tab.

Key capabilities of custom facts:

• Business-specific details: Extract the details your business needs, not generic categories.
• Account-wide setup: Define facts once for your whole account. Each fact applies to all conversations analyzed after you save the fact.
• Agent handoff: Extracted facts appear in the AI customer context card that human agents see in Inbox at handoff.

Before you begin [#before-you-begin]

Before you create custom facts, check the following:

• Turn on AI analysis in Insights settings. AI analysis extracts custom facts, so it does not extract any facts while it is turned off.
• To show facts to human agents in Inbox, go to Inbox → Settings → Productivity → Inbox AI → AI customer context tab. Turn on Show AI customer context to agents and select the queues. For details, see AI customer context settings.
• Turn on Customer context on the Custom facts tab. For details, see Turn Customer context on or off.
• You need the profile/context/manage permission to set up Customer context and create, edit, and delete custom facts. The Customer profile manager role includes this permission by default. For details, see Customer context permissions.

How custom facts work [#how-custom-facts-work]

Keep the following in mind when you work with custom facts:

• Going forward only: When you create, edit, or delete a fact, the change applies only to conversations analyzed after you save it. AI analysis does not analyze past conversations again, and past conversations keep the facts extracted at the time.
• Conversation messages only: AI analysis extracts facts from the messages exchanged in the conversation. Messages sent from Journeys or Broadcast are not part of the conversation, so AI analysis does not extract facts from them.
• Language: Custom facts use the same language setting as AI analysis in Insights.
• Fact definition: Each custom fact has a name, a type, and a description. The name is unique per account. The type is Text, Number, Boolean, or Date. You cannot change the type after you save the fact. The description tells AI analysis what to extract.
• Stored per conversation: AI analysis stores the values of a fact for each conversation. When a fact changes across conversations, the person profile shows the most recent value.
• Guardrails: Guardrails prevent prohibited content from being stored as a fact value.
• Validation: If a fact definition is invalid or prohibited, Customer Profiles shows an error and does not save the fact.
• No near-duplicates: A defined list of facts prevents near-duplicate facts, such as language, preferred_language, and spoken_language.

Turn Customer context on or off [#turn-customer-context-on-or-off]

The Custom facts tab has a global toggle that turns Customer context on or off for your account. While Customer context is turned off, AI analysis does not extract custom facts or build new Customer context. If Show AI customer context to agents is on in Inbox, agents still see the context collected before you turned Customer context off.

To turn Customer context on or off:

1. Go to Customer Profiles → Configuration → Custom facts tab.
2. Turn on the Enabled toggle to start Customer context. Turn off the toggle to stop it.

Customer context also requires AI analysis. The AI analysis setting in Insights settings is one account-level setting that controls topic detection, outcome evaluation, interaction summaries, and Customer context.

Create custom facts [#create-custom-facts]

To create a custom fact:

1. Go to Customer Profiles → Configuration → Custom facts tab.
2. Select Create custom fact.
3. In the Name field, enter a name for the fact, for example, order_number. The name must be unique within your account. If the name already exists, the error An interaction fact with this name already exists appears.
4. In the Description field, describe the fact. Example description: The order number the customer is asking about, as digits only.
5. In the Type field, select a type: Text, Number, Boolean, or Date. The type determines the kind of value AI analysis extracts for the fact.
6. Select Save.

There is a limit on the number of custom facts per account. If you reach it, the error You have reached the maximum number of interaction facts appears.

AI analysis starts extracting the fact from conversations analyzed after you save it.

Follow these tips to get useful results:

• Name facts clearly: Human agents read fact names in the AI customer context card. Use names that are easy to understand at a glance, such as policy_number or delivery_date.
• Track the identifiers customers quote: Order, policy, and ticket numbers help agents find the correct record without asking the customer again.
• Keep the list focused: Add only the facts your agents use, so the AI customer context card stays easy to scan.

For guidance on names and descriptions, see Write effective fact descriptions.

Write effective fact descriptions [#write-effective-fact-descriptions]

AI analysis uses the description of a custom fact to decide what to extract. Clear definitions give more consistent values across conversations.

Follow these best practices when you define custom facts:

• Use one fact per concept: Define a separate fact for each detail. For example, define order_number and delivery_date as two facts instead of one fact that covers the whole order.
• Describe what to extract and the expected format: State exactly which detail AI analysis must look for and how the value must look. Example description: The order number the customer is asking about, as digits only.
• Avoid near-duplicate facts: Before you create a fact, check the facts you already have. Facts such as language, preferred_language, and spoken_language capture the same detail and split the values across several facts.
• Use clear snake_case names: Use short, lowercase names with underscores, such as order_number or policy_number. Human agents read these names in the AI customer context card.
• Do not capture sensitive or regulated data: Do not define facts that capture sensitive or regulated data, such as health information. Do not use AI analysis with Protected Health Information (PHI). For details, see the HIPAA notice in Before you begin.

Edit custom facts [#edit-custom-facts]

You can edit the name and description of a custom fact. You cannot edit the type.

You can edit a custom fact at any time. Edits apply only to conversations analyzed after you save them. Values already extracted for past conversations do not change.

To edit a custom fact:

1. Go to Customer Profiles → Configuration → Custom facts tab.
2. Select the custom fact you want to edit.
3. Edit the Name or Description field.
4. Select Save.

Review suggested facts [#suggested-facts]

You can get suggestions for facts worth tracking. AI analysis reviews a sample of your past conversations and suggests relevant facts, each with a name and a description.

Keep the following in mind:

• On demand: AI analysis generates suggestions when you request them.
• Limits: The number of suggestions and how often you can request them are limited. There is also a limit on the number of custom facts per account.
• You stay in control: Only suggestions that you approve become custom facts. You can edit, delete, or add facts at any time.
• Similar facts: A suggestion can still be similar to a fact you already have, for example, under a different name. Review each suggestion before you approve it.

To review suggested facts:

1. Go to Customer Profiles → Configuration → Custom facts tab.
2. Select Suggest facts.
3. Review each suggestion and compare it with the custom facts you already have.
4. Select Approve for each suggestion you want to keep, and select Dismiss for the rest.

Approved suggestions become custom facts. AI analysis starts extracting them from conversations analyzed after you approve them.

Delete custom facts [#delete-custom-facts]

You can delete one or more custom facts at the same time.

To delete custom facts:

1. Go to Customer Profiles → Configuration → Custom facts tab.
2. Select the checkbox next to each fact you want to delete.
3. Select Delete.
4. To confirm the deletion, select Delete.

Manage custom facts over API [#manage-custom-facts-over-api]

You can also create, view, update, and delete custom facts over the public API. Use the API to manage your custom facts from your own systems. For details, see the Context API.

To create, update, or delete custom facts, your API key needs the context:manage or people:manage scope. To view custom facts, any of context:view, context:manage, people:read, or people:manage is enough.

In the API, the type of a fact is the valueType field. Its values are STRING, NUMBER, BOOLEAN, and DATE. The Text type in the web interface is STRING in the API.