Send data to Braze¶
Braze is a leading marketing automation platform that allows users to create custom experiences based on sophisticated customer attributes and segments, then map those experiences to campaigns.
Amperity can send customer profile and custom attributes to Braze, attaching the data that is sent from Amperity to customer profiles that already exist in Braze.
This topic describes the steps that are required to send custom attributes to Braze from Amperity:
About custom attributes¶
Attributes in Braze describe your customers.
Profile attributes describe who your customers are. For example: names, birthdates, email addresses, and phone numbers.
Custom attributes describe how your customers have interacted with your brand. For example: purchase histories, loyalty status, and value tiers.
When user profile fields and custom attributes are available in Braze they can be used to build out audience segments and to apply personalization to your campaigns.
Customer profiles¶
Attributes in Braze describe your customers.
Profile attributes describe who your customers are. For example: names, birthdates, email addresses, and phone numbers.
Custom attributes describe how your customers have interacted with your brand. For example: purchase histories, loyalty status, and value tiers.
When user profile fields and custom attributes are available in Braze they can be used to build out audience segments and to apply personalization to your campaigns.
What about email and phone subscription status?
Braze uses two fields to track email and phone subscription status: email_subscribe and push_subscribe. The values for these fields are not modified by Amperity even when the fields are sent from Amperity with the correct values. Braze is your source of truth for customer consent and for tracking email and phone subscription status.
The following table describes the default user profile fields that are most commonly updated from Amperity:
Braze default field |
Amperity field name |
Description |
|---|---|---|
external_id |
varies |
Required. The external_id is a unique identifer for user profiles in Braze. The external_id is a unique identifier that exists in another system, such as the Amperity ID, a loyalty ID, or some other unique customer identifier. |
first_name |
given_name |
Optional. |
last_name |
surname |
Optional. |
Optional. |
||
phone |
phone |
Optional. |
home_city |
city |
Optional. |
country |
country |
Optional. Must be in ISO 3166-1 alpha-2 format. |
dob |
birthdate |
Optional. Must be in “YYYY-MM-DD” format. |
gender |
gender |
Optional. Accepted values: “M”, “F”, “O” (other), “N” (not applicable), “P” (prefer not to say), or NULL. |
Note
Default user profile fields also exist for alias_name, alias_label, current_location, date_of_first_session, date_of_last_session, email_open_tracking_disabled, email_click_tracking_disabled, facebook, language, marked_email_as_spam_at, push_tokens, subscription_groups, time_zone, and twitter.
These fields are not commonly sent to Braze from Amperity, but if your brand chooses to update these user profile fields from Amperity, be sure to use the exact name of the default field name, send the correct value (or values), and to use lowercase.
Custom attributes¶
Custom attributes in Braze are represented by a set of custom-named fields. The names of these fields are determined by your brand. They may already exist in Braze, in which case you will want to shape the output that is sent from Amperity to align to the names you already have.
The names of custom attributes that can be managed by Amperity are defined by your brand. The names are strings, may contain hyphens, spaces, or underscores, may include numbers, and may contain a mix of lowercase and uppercase letters. For example, custom attribute can have names that:
Already exist within your organization.
Are exactly the same as Amperity standard output, such as “One and Done” or “L12M Monetary” (the “monetary” component of an RFM score), or “Early Repeat Purchaser”.
Align to marketing goals and/or terminology that exists within your brand’s segmentation strategy.
Verify the names of custom attributes that will be sent to Braze from Amperity. Amperity will add a custom attribute whenever there isn’t a matching name.
Tip
Avoid sending custom attributes as duplicates of default user profile fields. For example, birthdates should be sent to Braze as a user profile field named “dob”. If they are sent as “birthday”, “Birthdate”, or any other string, a custom attribute will be created and the values in the “dob” field will not be updated.
Important
Your brand’s list of custom attributes should be a list that is mostly static, remains stable over time, and is focused on your most valuable customers.
Only update custom attributes for customers to which your brand is currently engaged. Define an audience in Amperity that is some combination of “high value” (historical or predicted), “active” (has purchased recently), and are “contactable” (with an opt-in status of true for phone numbers and/or email addresses).
This will help ensure that you are only updating custom attributes for your most valuable customers. Custom attributes will be updated only for those customers have a matching “external_id” or “braze_id” within Braze.
About data points¶
Braze uses data points to determine when to update segment membership, to identify which types of messages should be sent, and how to apply message personalization.
You can send custom attributes to Braze from Amperity by attaching attributes from your customer profiles in Amperity, such as first and last names, email addresses, phone numbers, physical locations, SMS and email consent status, purchase histories, and so on.
Data points are part of the billing and pricing structure in your Braze contract. Some data points are non-billable; many data points are billable.
Carefully review the lists of non-billable and billable data points , and then review those lists against the attributes you will send to Braze from Amperity to determine which of those attributes are considered billable or non-billable data points.
Talk with your Braze representative to clarify if an attribute sent from Amperity is a billable or non-billable data point.
Important
Connected Content does not write data to user profiles, which means you can use Connected Content to dynamically populate values into messages without consuming data points.
Customer attributes table¶
Build a table that contains all of the attributes in Braze that your brand wants to manage from Amperity. The columns in this table must be correctly mapped to requirements for user profile fields and should contain the list of custom attributes that will be maintained.
To add a Braze customer attributes table
|
Open your customer 360 database and add a table named “Braze Customer Attributes”. Use SQL to define the default user profile fields that are required by Braze: SELECT
mc.amperity_id
,mc.amperity_id AS external_id
,mc.given_name AS first_name
,mc.surname AS last_name
,mc.email
,mc.phone
,mc.city AS home_city
,mc.country
,mc.birthdate AS dob
,mc.gender
FROM Merged_Customers
You may include custom attributes that map to other fields in your customer 360. For example, to use transaction attributes as custom attributes in Braze you can extend the table to include fields from the Transaction_Attributes_Extended table: SELECT
mc.amperity_id
,mc.amperity_id AS external_id
,mc.given_name AS first_name
,mc.surname AS last_name
,mc.email
,mc.phone
,mc.city AS home_city
,mc.country
,mc.birthdate AS dob
,mc.gender
,ta.L30D_purchase_channels
,ta.L30D_order_revenue
,ta.L30D_order_frequency
,ta.L3M_purchase_channels
,ta.L3M_order_revenue
,ta.L3M_order_frequency
,ta.L12M_rfm_score
,ta.L12M_recency
,ta.L12M_frequency
,ta.L12M_monetary
,ta.lifetime_order_revenue
,ta.one_and_done
,ta.multi_purchase_channel
,ta.first_to_second_order_days
,ta.days_since_latest_order
,ta.latest_order_datetime
,ta.early_repeat_purchaser
FROM Merged_Customers mc
LEFT JOIN Transaction_Attributes_Extended ta
ON mc.amperity_id = ta.amperity_id
LEFT JOIN Customer_Attributes ca
ON mc.amperity_id = ca.amperity_id
|
|
Validate the table, and then click Next. Name the table “Braze Customer Attributes”, and then save the table. Verify that the table is accessible to the Segment Editor and to the Edit Attributes editor within campaigns. |
Get details¶
Braze requires the following configuration details:
|
Configuration details for Braze.
|
Add destination¶
Configure Amperity to send custom attributes directly to Braze.
To add a destination
|
|
Open the Destinations tab to configure a destination for Braze. Click the Add Destination button to open the Destination dialog box. 
Enter a name for the destination and provide a description. For example: “Braze” and “This sends custom attributes to Braze”. From the Plugin drop-down, start typing “br” to filter the list, and then select Braze. |
|
|
Credentials allow Amperity to connect to Braze. The credential type is set automatically. You may use an existing credential or you may add a new one. 
Select an existing credential from the Credential drop-down. – or – Select Create a new credential from the Credential drop-down. This opens the Credential dialog box. 
Enter the name for the credential, and then add a description. Add the API key for your instance of Braze. 
When finished, click Save. |
|
Each destination has settings that define how Amperity will deliver data to Braze. These settings are listed under the Settings section of the Destination dialog box. 
Select the Braze instance . Select the user identifier. The external_id is a unique identifier for your customers, such as the Amperity ID. The braze_id is a unique identifier for existing Braze customers. |
|
Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them. Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII. What is restricted access to PII? Restricted PII access is enabled when the Restrict PII Access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow. You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options: 
Note To allow business users to use this destination with campaigns, you must enable the Make available to campaigns option within the data template. This allows users to send campaign results from Amperity to Braze. The other two settings may be configured within the data template instead of the destination. |
|
Review all settings, and then click Save. 
Important You must configure a data template for this destination before you can send data to Braze. |
Add data template¶
A data template defines how columns in Amperity data structures are sent to downstream workflows. A data template is part of the configuration for sending query and segment results from Amperity to an external location.
To add a data template
|
|
From the Destinations tab, open the menu for a destination that is configured for Braze, and then select Add data template. This opens the Add Data Template dialog box. 
Enter the name of the data template and a description. For example: “Braze” and “Send custom attributes to Braze.”. |
|
|
Verify business user access to queries and orchestrations and access to segments and campaigns. A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data. 
If business user access was not configured as part of the destination, you may configure access from the data template. |
|
|
Verify all configuration settings. 
Note When the settings required by Braze were are not configured as part of the destination, you must configure them as part of the data template before making this destination available to campaigns. |
|
|
Review all settings, and then click Save.
After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Braze. |
Workflow actions¶
A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.
Open the Workflows tab to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.
|
|
You may receive a notifications error for a configured Braze destination. This appears as an alert in the notifications pane on the Destinations tab. 
If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page. |
|
|
On the Workflows page, review the individual steps to determine which step(s) have errors that require your attention, and then click Show Resolutions to review the list of workflow actions that were generated for this error. 
|
|
|
A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Braze, including: |
|
|
Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to re-run the workflow. |
Invalid credentials¶
The credentials that are defined in Amperity are invalid.
To resolve this error, verify that the credentials required by this workflow are valid.
Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Braze if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Missing required field¶
A unique identifier must be provided to Braze. There are two options:
Recommended. The external_id , which is a unique identifier for your customers. This may be the Amperity ID or it may be some other unique identifier.
The braze_id , which is a unique identifier for existing Braze customers and may be available when Braze is also a data source for your tenant.
For campaigns
To resolve this error, verify that “external_id” or “braze_id” are included in the list of attributes that are being sent to Braze.
Open the Campaigns page, and then open the segment used with this workflow.
Verify that “external_id” or “braze_id” is included in the list of attributes for each recipient group that sends audiences to Braze. Update the list of attributes for each recipient group if required.
Return to the workflow action, and then click Resolve to retry this workflow.
For orchestrations
To resolve this error, verify that “external_id” or “braze_id” are included in the query results.
Open the Queries page, and then open the query used with this workflow.
Verify that “external_id” or “braze_id” is included in the query results. Update the query if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Status 401 error¶
A “Status 401” error is an authorization error: Amperity was unable to connect to Braze. This may be a transient error; however, this type of error is more likely caused by a configuration issue within Amperity. For example, the currently-configured API key is invalid because the API key was rotated.
To resolve this error, verify that the credentials required by this workflow are valid.
Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Braze if required.
Return to the workflow action, and then click Resolve to retry this workflow.