Braze

Build better campaigns on Braze with up-to-date customer data from your data warehouse

Overview

Providing relevant and timely customer interactions relies on fresh and accurate data in your Braze account. By automatically syncing customer data from your data warehouse into Braze, you don't need to worry about data consistency or staleness. Instead, you can focus on building world-class customer experiences.

Supported syncing

Connect to Braze

Connecting Braze to Hightouch requires an API Key and Region.

API key

To find the API key, navigate to Developer Console > API Settings in Braze and create an API key.

Required permissions

The permissions the API key needs depend on what you plan on syncing.

Braze region

To find the your Braze region, use the table below.

Sync configuration

Once you've set up your Braze destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Braze destination you want to sync to.

Sync users

Hightouch supports syncing rows from your model to Braze users. This integration supports both Upsert and Update modes. In Upsert mode, Hightouch inserts new users into Braze, with all attributes kept up-to-date. In Update mode, Hightouch updates attributes on users that already exist in Braze.

Hightouch automatically normalizes some user data fields to meet Braze's specifications.

Record matching

In Upsert mode, you can match records from your source to your Braze workspace using the Braze External User ID. In Update mode, you can also match records based on Braze ID or a user alias object.

Field mapping

You can sync columns from your source to Braze's default and custom fields. If you send data for a custom field that doesn't exist, Hightouch adds the field and automatically detects its type.

You can manage your custom fields in Manage App Group > Custom Attributes in Braze.

You can also map your model columns to user aliases in Braze. This configuration only appears if you select Braze External ID for record matching.

Nested objects and object arrays

Braze supports user attributes containing JSON objects or object arrays. These objects and object arrays are commonly used to support "entities" related to each user—for example, devices, medications, pets, etc.—especially when marketing communication needs to include metadata about these related entities.

Hightouch is a great tool to sync to these types of attributes because you can leverage your data warehouse to manage these associations. To do so, you must build the full JSON object into a single column within your Hightouch data model.

Modeling nested attributes into JSON can be done directly in your warehouse with something like dbt, or you can use SQL functions appropriate for your data warehouse and build these objects within the SQL Editor in Hightouch.

Nested object array example

Let's say you want an array of a customer's pets to be an attribute named pets in Braze. You would need a data model with a column named pets and would then build the full JSON pets object array to populate that column. This array might look something like this:

[
  {
    "id": 0,
    "type": "dog",
    "breed": "Mutt",
    "name": "Rae"
  },
  {
    "id": 1,
    "type": "cat",
    "breed": "Tabby",
    "name": "Garfield"
  }
]

This full object array would need to be the value of a column in your Hightouch data model:

Then you would map this column to the pets custom attribute in Braze in your Hightouch sync configuration:

After scheduling your sync, you'd have relevant pet data on each user in Braze.

Sync events

Hightouch supports syncing events to Braze and assigning them to a user. You can send two event types to the Braze destination:

• Track Event: Sends events of a particular name when a record is added
• Track Purchase: Track when a customer makes a purchase

Hightouch lets you choose whether to create users that don't exist. For example, if you are tracking an event associated with user A and user A doesn't exist in Braze, you can either create the user or ignore the event.

Record matching

Hightouch can match events to users on different Braze fields. If you are creating users that don't exist, you can only match on Braze External ID or User Alias Object. Otherwise you can match on Braze External ID, User Alias Object, or Braze ID.

For track event type events you can alse send the event name and event timestamp. Track purchases don't require an event name.

Field mapping

Hightouch lets you pass data to the event properties of a Braze event.

Event property configuration

Hightouch lets you send all your custom properties as a single object column or as multiple columns from your model.

Sync subscription status

Hightouch supports syncing users to both Email and SMS subscription groups.

Braze has a designated set of fields to manage subscription group opt-ins independent of user attributes.

Hightouch supports syncing to existing subscription groups within Braze. You can enter a static subscription group ID or select a column from your model containing the subscription group ID.

Record matching

You can match records from your source to your Braze subscription groups by Braze External User ID, Phone Number, or Email.

Field mapping

You can map any source fields to user fields in Braze, for example name, email, etc.

Delete behavior

When a user is removed from a Subscription status sync, Hightouch makes an API request to set the user's subscription_state to unsubscribed.

Merge anonymous and known users

Hightouch supports merging alias-only "anonymous" users with "known" Braze users with an external ID.

It's common to have “soft-signup” workflows where all you collect from a user is an email or phone without forcing the user to create an account. This workflow results in users where all you may have is PII. When they create an account, you need to use this endpoint to “identify” these users with a new login ID.

For example, your workflow might look like this:

1. A user visits your website or app. The user doesn't have a Braze ID to start with—they only enter an email address, phone number, or some other PII. You create a user in you customer database, and an alias-only user profile in Braze via the Braze SDK. Hightouch isn't involved at this point.
2. You can use Hightouch to send user attributes or user-related events to Braze via Hightouch by matching on a user alias object, since there isn't an external ID yet. You must use Update mode.
3. Once you have a unique user ID in your customer database, you can use Hightouch to call Braze's Identify endpoint to "identify" the alias-only user using your unique user ID as the external ID in Braze. This merges the alias-only user in Braze with a known Braze user. If an external ID doesn't exist when using the Identify endpoint, Braze creates the external ID and the alias-only user is considered “identified.”
4. All subsequent updates to the user should be done in Hightouch using the external user ID, not the user alias.

Record matching

You can match and merge records using Braze user external IDs.

Field mapping

Hightouch lets you map your Braze aliases to known users using the alias label and value.

If you're adding a JSON object directly to your model, each user_alias object should consist of alias_label and alias_name as top-level attributes, rather than nested in another object.

# CORRECT FORMAT
"user_aliases": [
    {
      "alias_label": "label",
      "alias_name": "name_1"
    },
    ...
  ]

# INCORRECT FORMAT
"user_aliases": [
    {
      "user_alias" : {
        "alias_name" : "label",
        "alias_label" : "name_1"
      }
    },
    ,
    ...
  ]

Sync catalog items

Hightouch supports syncing rows from your models to your existing catalog through the Braze Catalogs API.

You can choose to create a new Braze catalog the first time the sync runs or use an existing catalog. If creating a new catalog, you can name the catalog from Hightouch. If you leave this field blank, the name defaults to the model name.

Syncing to catalog items allows either Upsert and Update modes. In Upsert mode, Hightouch inserts new catalog items into the Braze. In Update mode, Hightouch updates fields on catalog items that already exist in Braze.

Record matching

In Upsert and Update modes, you can match records from your source to your Braze workspace using the catalog item ID.

Field mapping

You can map data from your source to any existing field in your catalog.

Testing

If you are using an existing catalog, you can test your sync by syncing a single row. You can verify that a row was successfully synced by going to your Catalog and finding the synced row by its catalog item ID. If you are automatically creating a catalog, it's not possible to test by row.

Trigger campaigns

Hightouch lets you use records from your models to trigger campaigns through the Braze Campaign API.

Once configured, your Hightouch sync triggers your campaign once rows appear in your model. Hightouch triggers your campaign for every row in your model the first time you run the sync, whenever you do a full resync, and for every new row added to your query results in subsequent syncs.

Prerequisites

Before you can set up a Hightouch sync to trigger a campaign, you need set up an API-triggered campaign in Braze. See how to create an email campaign in Braze for more information.

Record matching

This destination lets you trigger a campaign for your Braze users based on their external user ID.

Field mapping

This destination allows you to customize your messages via API trigger properties. Hightouch automatically lists trigger properties you can map values with. See using the templated content included with an API request for more information.

Testing

Hightouch recommends that you test with your email before running an actual sync for your users.

You can test by following these steps:

1. Create a Google Sheet with a valid external_id and your email. You will use this to sync yourself as user in Braze. See Braze's user ID convention if you are unfamiliar with external_id.

   

2. Use the Google Sheet as a source to add yourself to Braze as a user.

   

3. Build your campaign in Braze. See Braze's guide on how to build a campaign for more information. When setting up your campaign schedule, make sure to select API-triggered Delivery.
4. Set up your campaign trigger sync and run it on Hightouch.
5. Verify that you are able to receive your campaign message. If you need to make corrections and thus want to re-run the sync, click Resync full query next to the Run button. Also note that your re-eligibility settings in Braze campaign must be loosely set for you to re-trigger the sync and actually receive the email.

Trigger Canvases

Hightouch lets you use records from your models to trigger Canvases through the Braze Canvas API.

Once configured, your Hightouch sync triggers your Canvases once rows appear in your model. Hightouch triggers your Canvases for every row in your model the first time you run the sync, whenever you do a full resync, and for every new row added to your query results in subsequent syncs.

Prerequisites

Before you can set up a Hightouch sync to trigger a Canvas, you need set up an API-triggered Canvas in Braze. See Braze Ideas & Strategies for more information and best practices.

Record matching

This destination lets you trigger a Canvas for your Braze users based on their external user ID.

Field mapping

This destination allows you to customize your messages via Canvas entry properties. Hightouch automatically lists Canvas entry properties you can map values to.

See Braze's docs on using the templated content included with an API request for more information.

Tips and troubleshooting

Syncing and data point consumption

Hightouch only syncs data that needs updating to minimize the number of API requests made to your destinations. Braze pricing is based on data points, which count the number of updates you (and Hightouch) make. These are some key points to understand how Hightouch syncs affect your Braze data point consumption:

When syncing arrays without nested objects, you consume one Braze data point per API call:

• Creating an array consumes one data point.
• Updating arrays consumes one data point per value updated.

When syncing arrays of objects, you may consume multiple data points with one API call:

• Creating an array of objects consumes one data point per attribute added within each object. For example, creating two pet objects with four attributes each (id, type, color, and size) consumes eight data points.
• Updating an array of objects consumes one data point per attribute changed.
• Removals consume one data point per removal criteria. For example, removing objects where id = 4 removes one object and costs one data point. Removing objects where type = dog may remove many objects but still only consumes one data point.

When syncing records that don't exist in Braze, Hightouch updates all mapped attributes with the values from your query results. This means you consume one data point per attribute per created record.

When syncing new records in the model that already exist in Braze, Hightouch first gets the user attributes from Braze, calculates which columns actually changed, and then only sends the changes for those columns. Each updated attribute equals one data point consumed.

When syncing records that have been previously synced to Braze, Hightouch compares the new record's columns to the previously sent record's columns, calculates which columns actually changed, and then only sends the changes for those columns. Each updated attribute equals one data point consumed.

Required permissions

If your syncs are failing, check that the REST API key you use to connect Braze to Hightouch has the correct permissions for your sync type or types.

Slow initial sync

If you're using a Braze ID to match user records, your initial sync may be slow. When Hightouch updates Braze with new records or fields, we query users in Braze for change data capture.

Braze allows batch searches on external IDs, but only allows querying for one user at a time if using Braze IDs. That means Hightouch needs to make a separate request for each user if using Braze IDs.

It's best to match records on external ID rather than Braze ID. This speeds up the initial sync and limits the number of requests to make to Braze.

Batch size limitation

Hightouch limits the update batch size to 35 attributes per API request rather than the 75 allowed by Braze. This is because of a Braze limitation when updating nested objects in an array.

When updating an attribute's value in a nested object to null, Braze's API doesn't let you combine this change with other non-null updates. Therefore, when updating values to null, Hightouch sends the full nested object with the _merge_objects parameter set to false.

Setting _merge_objects to true deep merges your update with the existing object data. See the Braze API documentation for more details.

This means the same user may require two update actions in one API request:

• Updates to nested objects with non-null values with _merge_objects:true
• Updates setting one or more attributes in nested objects to null with _merge_objects:false

Hightouch processes 35 users at once in case each user in the update requires two update actions.

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

400 - The value provided for the phone number field is not a valid phone number

This error can happen if the phone numbers you're syncing to Braze are being marked as invalid because of provider errors or because they're deactivated. It might also happen if a number is on an opt-out list or if it's already taken by another user in Braze.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.