Conversational Agents

Conversational Agents is a channel that lets your users talk with an AI agent to complete tasks you define. You create conversational workflows that describe what the agent should do for your brand. For example, a workflow can help a user purchase items based on their preferences.

important

Conversational Agents is currently in beta. Contact your Braze account manager if you’re interested in participating in this beta.

Before you deploy to production, consult your legal team about the implications of using conversational AI.

How it works

A conversational workflow is a task you want an agent to complete. Each workflow includes a purpose, channel settings, a target audience, and natural-language steps. In a step, add tools so the agent can search catalogs, set attributes, log events, or call webhooks.

After you create workflows, see Settings for brand guidelines and channel behavior. Use Preview a conversation, Create simulations, and Review conversation history to test the experience and review tool calls.

Set up the web chat widget

To show the Conversational Agents chat widget on your site, complete the following steps in the Braze Web SDK.

Step 1: Set up SDK authentication

Enable SDK authentication for your web app.

Step 2: Install the Web SDK

Install either of the following:

Step 3: Initialize with user-supplied JavaScript enabled

In your initialize call, set allowUserSuppliedJavascript: true:

1
2
3
4

braze.initialize("{YOUR_API_KEY}", {
  baseUrl: "{YOUR_SDK_ENDPOINT}",
  allowUserSuppliedJavascript: true
});

Replace {YOUR_API_KEY} with your Web SDK API key and {YOUR_SDK_ENDPOINT} with your SDK endpoint.

Step 4: Enable the chat widget

Before you open a session, call braze.automaticallyManageChat():

1
2

braze.automaticallyManageChat();
braze.openSession();

Create a conversational workflow

Use a conversational workflow to define a task, choose channels and an audience, and tell the agent what to do in each step.

Step 1: Set up workflow details

Go to Agent Console > Conversational Agents, then set up the details for your workflow:

1. Enter a name for the workflow.
2. Enter a purpose that describes what this workflow does, so the agent knows when to use it.
3. Select the channels this workflow is enabled for. Supported channels are SMS, RCS, WhatsApp, and Web.
   • For web, select which web apps this workflow is enabled for.
   • For SMS, RCS, and WhatsApp, select which subscription groups this workflow is enabled for.
4. Select the segments a user must belong to in order to access this workflow.

For SMS, RCS, and WhatsApp, some inbound message triggers can block the agent. On the Settings page, review the triggers that may block agents for each subscription group.

Step 2: Write workflow steps

Add the steps the agent should take to complete the workflow. A workflow can have up to 10 steps. Each step needs an instruction, which can be up to 5,000 characters.

For steps with a single goal, write the instruction in one to three short sentences. Keep the rules clear, and end with an explicit question or confirmation so the agent knows how to phrase its next response to the user.

Step 3: Add tools to steps

Steps can include tools the agent uses while it works. In the Instructions of a step, tools are inserted by entering / and appear as tags in the instruction. A step can reference up to 10 tools.

Tools

You can add any of these tools to a step:

Search knowledge sources

Use this tool to help the agent query and understand a Braze catalog. Create knowledge sources for catalogs such as:

• Product catalog
• FAQ
• Size charts

First, create the knowledge source on the Knowledge sources page. Then, in the instruction text box, enter / and select Search knowledge sources. Select an existing conversational knowledge source tool, or select Create new search tool.

When you create a new tool, enter a name and description, then select a knowledge source. After you select a knowledge source, choose which fields the agent can access.

Set a workflow attribute

Use this tool to set an attribute the agent can reuse later in the same workflow. Workflow attributes are scoped to the workflow they are set in. Use them as custom event properties, custom attribute values, and webhook parameters.

When you create the attribute, you can optionally add Allowed values:

• Leave allowed values empty to let the agent set any value of that type based on the conversation.
• Add allowed values to limit the agent to a subset you define. Use this when later tools (such as Call webhook, Log custom event, or Set custom attribute) should reuse a controlled value instead of an open-ended agent choice.

In Instruction, enter / and select Set workflow attribute. Select an existing workflow attribute, or select Create new attribute.

When you create a new attribute, enter a name and description, then select the type. After you select the type, optionally add allowed values.

Get a workflow attribute

Use this tool to retrieve the value of a workflow attribute set in an earlier step.

Log a custom event

Use this tool to log a Braze custom event. In the instruction text box, enter / and select Log custom event. Select an existing log custom event tool, or select Create new custom event tool.

When you create a new tool, select the custom event, then enter a name and description. Choose the event properties to send with the custom event. Each custom event property can use one of the following sources:

You don’t have to set a value for every property. Some property types aren’t supported.

Select Required if the tool should fail when the property value is blank.

To send a user into a Canvas, log a custom event that the Canvas uses as an entry property.

Set a custom attribute

Use this tool to set a custom attribute on the user. In the instruction text box, enter / and select Set custom attribute. Select an existing set custom attribute tool, or select Create new custom attribute tool.

When you create a new tool, enter a name and description, then select the custom attribute the tool should set. A custom attribute can use one of the following sources:

note

Custom attributes are set asynchronously. If the agent reads a custom attribute after setting it, the value may still be stale.

Get a custom attribute

Use this tool to retrieve a custom attribute.

Get a user attribute

Use this tool to retrieve a standard user profile field. In the instruction text box, enter a forward-slash (/) and select Get user attribute. Choose one of the following fields:

• External ID
• Braze ID
• Email
• First name
• Last name
• Phone

Call a webhook

Use this tool to call a webhook. In the instruction text box, enter / and select Call webhook. Select an existing webhook tool, or select Create new webhook.

When you create a new tool, enter a name and description, then add variables. Variables let you include personalized values in the webhook URL, body, or headers.

A variable can use one of the following sources:

After you set variables, choose the request method. The following request methods are supported:

• GET
• POST
• PUT
• PATCH
• DELETE

Then enter the URL. To use variables in the URL, reference them with {{variable_name}} syntax. For example:

1

https://myurl.com/create/{{user_id}}

Next, set the request body. Leave the body empty, or enter a string that can include {{variable_name}} placeholders. For most APIs, send a JSON body. For example:

1
2
3
4
5
6
7

{
  "user": {
    "id": "{{external_id}}",
    "favorite_color": "{{favorite_color}}",
    "is_called_by_agent": true
  }
}

You can also set headers using variables. For credentials, create Connected Content credentials in the dashboard and reference them in this tool.

Webhook responses can be large, so you can extract only the fields the workflow needs. Create response fields with a JMESPath expression that points to a value in the response body. The response body must be valid JSON for those fields to extract successfully. Reference those fields later with the Get webhook response tool.

Get a webhook response

Use this tool to reference a webhook response field extracted from a previous Call webhook step.

Settings

Configure brand guidelines and channel behavior for Conversational Agents. Go to Agent Console > Conversational Agents, then select Settings.

Brand guidelines

Select brand guidelines for the agent to follow in its responses. Create and manage guidelines from Content > Brand Guidelines, then choose one here.

Web settings

Set an Opening message. This is the first message users see when they start a web conversation.

SMS, RCS, and WhatsApp settings

Configure the following:

Triggers that may take priority include:

• Keyword triggers
• Action-based campaigns
• Action-based Canvas entry
• Canvas action path
• Canvas exit

Preview a conversation

There are two ways to preview:

• When you edit a saved workflow, preview that workflow only. Preview is unavailable until you save a new workflow.
• On the Settings page, preview the experience for a web app or subscription group. Optionally, select Include draft workflows to test draft workflows before you make them active.

In both cases, preview as a specific user.

note

Preview mode does not log custom attributes or custom events.

Create simulations

Go to Agent Console > Conversational Agents, then select Simulations.

Create simulation cases that describe a user scenario and expected outcomes. Run a simulation to test those cases against your workspace’s conversational workflows. You can mock webhook responses so cases stay predictable while you evaluate agent behavior.

Review conversation history

On the Conversational Agents page, select Conversation history. This page shows conversations with real users and conversations from preview.

Use conversation history to review tool calls and confirm the agent behaves as expected.

Example

Flash & Thread, a fictional clothing retail brand, might use this two-step shopping workflow.

• Step 1: Asks the user what product category they’re shopping for.
• Step 2: Uses the Set workflow attribute tool to capture a product_category attribute as a string. This attribute records the product category the user says they’re shopping for today from Step 1.