Search documentation...

K
ChangelogBook a demoSign up

Braze

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

It's important to be aware of Braze's data point consumption model when setting up Hightouch syncs. Refer to the section on syncing and data point consumption to understand how Hightouch syncs affect your Braze data point consumption.

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

Sync TypeDescriptionSupported Sync ModesAPI Reference
UsersSync records to Braze usersUpsert, UpdateUsers
EventsSend track events and track purchase type events to BrazeInsertEvents
Subscription statusUpdate subscription groups with data from your sourceUpdateSubscription status
User identificationMerge your alias-only users with an identified profile and remove the alias-only profileInsertUser identification
Catalog itemsSync records to relevant catalogsUpsert, UpdateCatalog items
Campaign triggersTrigger campaigns with context from your recordsInsertCampaign triggers
Canvas triggersTrigger Canvases with context from your recordsInsertCanvas triggers

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.

Finding an API key in the Braze dashboard

Required permissions

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

Sync TypeRequired permissions
Usersusers.track, users.export.ids, users.delete (optional if you want to rely on Hightouch for user deletions), users.alias.update (if you are updating existing users)
Eventsusers.track
Subscription statussubscription.status.set
User identificationusers.identify
Catalog itemscatalogs.add_items, catalogs.update_items, catalogs.get_item, catalogs.create, catalogs.get
Campaign triggerscampaigns.trigger.send, campaigns.list, campaigns.details
Canvas triggerscanvas.trigger.send, canvas.list, canvas.details

Braze region

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

URLRegion
https://dashboard-01.braze.comiad-01.braze.com
https://dashboard-02.braze.comiad-02.braze.com
https://dashboard-03.braze.comiad-03.braze.com
https://dashboard-04.braze.comiad-04.braze.com
https://dashboard-05.braze.comiad-05.braze.com
https://dashboard-06.braze.comiad-06.braze.com
https://dashboard-07.braze.comiad-07.braze.com
https://dashboard-08.braze.comiad-08.braze.com
https://dashboard-01.braze.eufra-01.braze.eu
https://dashboard-02.braze.eufra-02.braze.eu

Refer to the Braze endpoint documentation to view additional regions. To derive the region, remove the prefix "https://rest" from the respective value in the REST ENDPOINT column.

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.

Field nameHightouch normalization
Date of birthConvert from timestamps to year-month-date
EmailConvert to all lowercase letters
Phone numbersRemove leading plus signs (+) and white spaces

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.

If you match records with a column other than the primary key of your model, changes in the model column used for record matching will not be reflected in Braze. This is to ensure duplicate records are not created in Braze.

When syncing a large amount of rows, make sure to match the records using Braze External User ID instead of Braze ID. Using the Braze ID requires more requests which often results in slower sync speeds. See the slow initial sync section for more details.

Selecting a model column to use as the Braze external ID in the Hightouch UI

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.

Mapping model columns to fields in Braze

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.

Field mapping to Braze user aliases

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:

Value of an example "Pets" field shown in the Hightouch UI

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

Mapping the "Pets" field in the Hightouch UI

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

Pet data appearing in the Braze UI

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
To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

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.

Event configuration in the Hightouch UI

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.

Hightouch accepts a standard date time format for the timestamp and automatically converts it to the format Braze requires.

Record matching for events in the Hightouch UI

Field mapping

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

Field mapping for events in the Hightouch UI

Event property configuration

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

Event property configuration in the Hightouch UI

When using a single column, make sure that the model column's data type is Object / Array.

Sync subscription status

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

Subscription status configuration in the Hightouch UI

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.

Subscription group configuration in the Hightouch UI

Read Braze's docs for information on creating a subscription group.

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.

Selecting a model column to use as the Braze external ID in the Hightouch UI

Field mapping

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

Field mapping for users in the Hightouch UI

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.

Braze's Catalog endpoint is in early access. Contact your Braze account manager if you are interested in participating.

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.

Hightouch UI showing option to create new catalogs

With the Create a new catalog option enabled, Hightouch only creates a catalog the first time the sync runs. Hightouch doesn't modify the catalog name after the first run. If you want to change the name or fields, you have to create a new catalog using a new sync.

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.

If automatically creating a catalog, you can't add new fields or change data types after the initial sync.

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.

Hightouch can only trigger campaigns that are API-triggered. These are different from API campaigns.

Record matching

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

This destination doesn't check for duplicates. Hightouch recommends that you set delivery controls in Braze to prevent duplicated campaign messages in case your source has duplicates.

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.

Send to existing only

This destination allows you to create or update users when you trigger a campaign. To create new users, just uncheck the setting in the sync and map the user properties.

Send to existing only

Note: Mapping user propterties when using this setting is required

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.
    Screenshot of Google Sheet with test information
  2. Use the Google Sheet as a source to add yourself to Braze as a user.
    Syncing information from Google Sheet to Braze using Hightouch

    You can use the same sync to remove yourself from Braze once your testing is complete. Set the sync configuration's delete mode to "Delete destination record associated with source record," remove yourself from the source sheet and rerun the sync.

  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.

Hightouch can only trigger Canvases that are API-triggered. Only non-archived, active canvases are available in sync configuration.

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.

Send to existing only

This destination allows you to create or update users when you trigger a Canvas. To create new users, just uncheck the setting in the sync and map the user properties.

Send to existing only

Note: Mapping user properties when using this setting is required

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.

Hightouch sync strategy aims for the lowest Braze data point consumption possible. Because we make a GET request to first see what user attributes haven't changed since the last sync, sync speed is slower than other methods which overwrite all data in Braze and consume more data points.

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.

Multiple requests per user

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:

  • 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

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . 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.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Sep 17, 2024

On this page

OverviewSupported syncingConnect to BrazeAPI keyBraze regionSync configurationSync usersSync eventsSync subscription statusMerge anonymous and known usersSync catalog itemsTrigger campaignsTrigger CanvasesTips and troubleshootingSyncing and data point consumptionRequired permissionsSlow initial syncMultiple requests per userCommon errorsLive debuggerSync alerts

Was this page helpful?