Skip to main content

Braze integration

The following section outlines how to get started with a Rokt Calendar and Braze integration.

Rokt Calendar & Braze integration setup#

Rokt Calendar is a dynamic calendar marketing technology that enables partners to push 1:1 events and promotional communications—in the form of calendar events and notifications—across a proprietary network of subscriber calendars. You can access Rokt Calendar’s services through a Braze webhook to send messages to your end users.

Braze Webhook

The integration allows Rokt Calendar subscribers and associated subscription data to be pushed into Braze, where this information is added to existing user profiles as custom attributes. If there is no match between the calendar subscriber and the Braze user, a new user is created in Braze.

You can use the Braze Canvas to define a journey that targets a segment of your audience. The calendar event is used as a communication method—the same way you might already be using SMS, email, and push notifications. Audience segmentation can be done based on any of the standard Braze user attributes, as well as custom attributes generated through the calendar subscription.

To define the content of the calendar event, you need to create a Braze webhook template. The template can then be used for the creation of the calendar event.

Read on for guidance on:

  • General requirements
  • Integration setup
  • Webhook setup
  • Generating calendar subscribers
  • Using the webhook template (creating or defining an event)

Setup requirements#

RequirementOriginWhoDescription
Rokt Calendar OAuth credentialsRokt CalendarRokt Calendar account managerUse these credentials to connect your Braze and Rokt Calendar accounts. It is set up for each new Braze client and added to Connected Content in Braze by going to:.

Manage App Group > Connected Content > Add Credential
Rokt Calendar accountRokt CalendarRokt Calendar account managerA partner-specific Rokt Calendar account will be set up by an account manager.
Calendar setupRokt CalendarRokt Calendar account managerA calendar will be set up to reflect business context and settings:

- Merge flag
- subscriberId fallback flag
- Email capture, if needed
Webhook setupRokt CalendarRokt Calendar account managerAdd the Braze webhook type to the management center using:

- Braze endpoint—https://rest.iad-01.braze.com
- REST API key
External subscriberIdPartnerPartnerThis is the identifier used by the Rokt Calendar subscription process to match the calendar subscriber with the Braze user. This is something that is passed through by the partner to Rokt Calendar. Email address can also be used.
Rest API key and permissionsBrazePartnerCreate a new API Key in Braze and provide this to your account manager. To create a new API key in Braze, go to:

Developer Console > API Settings > Create New API Key and set permissions for users.track, users.alias.new and users.identify under the User Data heading.

Integration#

You use both your Rokt Calendar and Braze accounts to set up the Rokt Calendar integration. You need to set up two types of templates:

  • Send new personalized event—allows new events to be added to a segment of subscribers’ calendars
  • Update personalized event—allows for an update to be made to an event that has already been added to subscribers’ calendars

Template setup: send new personalized event#

  1. Create a webhook template in Braze. You can create this from the Templates & Media section, or create a new webhook campaign in Braze. Select Blank Template.

Webhook Template

  1. Fill out your template. To complete the template setup, configure the following:
  • Settings
  • Compose
Webhook settings#

Configure the Request Headers and HTTP Method.

Webhook Settings

Request Headers#

For Authorization, enter:

Bearer {% connected_content https://api.roktcalendar.com/oauth2/token :method post :basic_auth Rokt-Calendar-API :body grant_type=client_credentials :save token :retry %}{{token.access_token}}

This is the credential name in Manage App Group > Connected Content > Credential.

Request Headers

For Content-Type, enter "application/json".

HTTP Method#

For HTTP Method, select Post.

Webhook compose#

Complete the setup by defining the Webhook URL and the content of the Request Body in the Compose tab.

Webhook Compose

Webhook URL#

For Webhook URL, enter:

{% assign accountCode = {{custom_attribute.${rokt:account_code}}}[0] | split: '/' | first %}https://api.roktcalendar.com/v1/subscriptionevent/{{accountCode}}
Request Body#

From the Request Body dropdown, select Raw Text.

In the Request Body text box enter:

{% capture eventId %}Event_0001{% endcapture %}{% capture eventTitle %}Event Title{% endcapture %}{% capture eventDescr %}Event Description{% endcapture %}{% capture eventLocation %}Event Location{% endcapture %}{% capture eventStart %}2019-02-21T15:00:00{% endcapture %}{% capture eventEnd %}2019-02-21T15:00:00{% endcapture %}{% capture notifyBefore %}15{% endcapture %}{% capture eventTZ %}Eastern Standard Time{% endcapture %}{% comment %} For a list of valid timezones see: https://roktcalendar-api.readme.io/docs/timezones {% endcomment %}{  "event": {    "eventId": "{{eventId}}_{{${user_id}}}",    "title": "{{eventTitle}}",    "description": "{{eventDescr}}",    "location": "{{eventLocation}}",    "start": "{{eventStart}}",    "end": "{{eventEnd}}",    "timezone": "{{eventTZ}}",    "notifyBefore": "{{notifyBefore}}"  },  "subscriptionIds": ["{{custom_attribute.${rokt:subscription_id}| join: '","'  }}"]}

Template setup: update personalized event#

  1. Create a webhook template in Braze. You can create this from the Templates & Media section, or create a new webhook campaign in Braze. Select Blank Template.

Template Personalized Event

  1. Fill out your template. To complete the template setup, configure the following:
  • Settings
  • Compose
Webhook settings#

Configure the Request Headers and HTTP Method.

Webhook Settings

Request Headers#

For Authorization, enter:

Bearer {% connected_content https://api.roktcalendar.com/oauth2/token :method post :basic_auth Rokt-Calendar-API :body grant_type=client_credentials :save token :retry %}{{token.access_token}}

This is the credential name in Manage App Group > Connected Content > Credential.

Webhook Settings

For Content-Type, enter "application/json".

HTTP Method#

For HTTP Method, select Post.

Webhook compose#

Complete the setup by defining the Webhook URL and the content of the Request Body in the Compose tab.

Webhook Settings

Webhook URL#

For Webhook URL, enter:

{% assign accountCode = {{custom_attribute.${rokt:account_code}}}[0] | split: '/' | first %}https://api.roktcalendar.com/v1/subscriptionevent/{{accountCode}}/update
Request Body#

From the Request Body dropdown, select Raw Text.

In the Request Body text box enter:

{% capture eventId %}Event_0001{% endcapture %}{% capture eventTitle %}Event Title{% endcapture %}{% capture eventDescr %}Event Description{% endcapture %}{% capture eventLocation %}Event Location{% endcapture %}{% capture eventStart %}2019-02-21T15:00:00{% endcapture %}{% capture eventEnd %}2019-02-21T15:00:00{% endcapture %}{% capture notifyBefore %}15{% endcapture %}{% capture eventTZ %}Eastern Standard Time{% endcapture %}{% comment %} For a list of valid timezones see: https://roktcalendar-api.readme.io/docs/timezones {% endcomment %}{  "event": {    "eventId": "{{eventId}}_{{${user_id}}}",    "title": "{{eventTitle}}",    "description": "{{eventDescr}}",    "location": "{{eventLocation}}",    "start": "{{eventStart}}",    "end": "{{eventEnd}}",    "timezone": "{{eventTZ}}",    "notifyBefore": "{{notifyBefore}}"  }

Using webhooks#

Creating an event from a webhook template#

Once you have created the webhook template, you’re nearly ready to start sending out calendar events and messaging. The fields below detail what can be customized at the event level.

FieldDefinitionExample value
eventId
(required)
A unique identifier for the event to be added or updatedEvent_00001
eventTitle
(required)
The title of the event as it would appear in the calendarSummer Sale 2020
eventDescrThe description of the event as it would appear in the calendarThe sale is on for 3 days, click this link www.mybusiness.com/sale to see the offers.
eventLocationThe location of the event as it would appear in the calendar; note that this is often used as a second call to action which is complementary to the eventTitleOpen the event to get 50% off
eventStart
(required)
The start date and time of the event as it would appear in the calendar2020-02-21T15:00:00
eventEnd
(required)
The end date and time of the event as it would appear in the calendar2020-02-21T16:00:00
eventTz
(required)
The time zone of the event as it would appear in the calendar; the list of applicable time zones can be found hereEastern Standard Time
notifyBefore
(required)
The reminder time of the event as it would appear in the calendar, expressed in minutes15

Using subscription-related custom attributes for segmentation#

You can only send calendar events to Braze users that have a Rokt Calendar subscription record stored against them in the custom attributes. These are noted in the table below and can be used to segment the audience.

Custom AttributeDefinitionExample Value
rokt:account_codeCode of the Rokt Calendar accountbrazetest/f5733866ade2 and brazetest/ff10919f1078
rokt:account_idID of the Rokt Calendar accountd0ce4299-7d6c-4888-bfd8- c7e867a0fa6c/f5733866ade2
rokt:account_nameName of the Rokt Calendar accountBraze Test/f5733866ade2
rokt:calendar_codeCode of the Rokt Calendar calendartest-calendar-1/f5733866ade2
rokt:calendar_idID of the Rokt Calendar calendar9a9007c7-f5a4-e811-b13c- 06424c4f2724/f5733866ade2
rokt:calendar_titleTitle of the Rokt Calendar calendarTest Calendar 1/f5733866ade2
rokt:country_codeCountry code related to the created subscriptionAU/f5733866ade2
rokt:device_nameDevice type related to the created subscriptionDesktop/f5733866ade2
rokt:geo_countryCountry of origin related to the created subscriptionAustralia/f5733866ade2
rokt:optIn1If the user has opted in to the first of two opt-ins related to the created subscriptionTrue/f5733866ade2
rokt:optIn2If the user has opted in to the second of two opt-ins related to the created subscriptionTrue/f5733866ade2
rokt:sourceThe source of the created subscriptionbrazetest.Rokt Calendarapp.com/f5733866ade2
rokt:subscriber_emailThe email address entered by the user during the subscription processtest@email.com/f5733866ade2
rokt:subscription_idThe subscription ID—which serves as a unique identifier—related to the created subscription06423672-b6ba-4536-aa36- 70788a7a0a36
rokt:subscription_methodSubscription method (e.g., webcal or Google) related to the created subscriptionWebCal/f5733866ade2
rokt:tagsCalendar tags used related to the created subscriptionTest Calendar 1/All Teams/f5733866ade2 and Test Calendar 1/TeamI//f5733866ade2

Using calendar subscriptions#

Using Rokt Calendar to build an audience of calendar subscribers#

To send calendar events from the Braze Canvas using the Rokt Calendar integration, you must set up a calendar and have users subscribed to the calendar. To do this you need to inform your users where and how to subscribe to the calendar.

RequirementOriginWhoDescription
Rokt Calendar account setupRokt CalendarRokt Calendar account managerA client specific Rokt Calendar account needs to be setup. Contact sales-calendar@rokt.com to speak with an account manager.
Calendar setupRokt CalendarRokt Calendar account managerWork with a Rokt account manager to set up a calendar that meets the needs of your business.
Provide subscription integration pointsClientClientTo build an audience of calendar subscribers, you need to offer a destination that the user can navigate to and from where they can subscribe to the calendar.

Examples of common subscription integration points include:
- Add to calendar button on your website
- Add to calendar button on your app
- Add to calendar link in an email or SMS
- Add to calendar link on social media

Learn more here.
Promote the calendarClientClientYou should consider promoting the calendar to your audience so that they know how to subscribe.

Calendar promotion examples:
- Posts on social media
- Email newsletters and updates
- Blog posts
- In-app notifications

Learn more here.

Rokt Calendar and Braze implementation guide#

This document sets out to explain the interaction between Rokt Calendar and Braze with specific focus on the data flow from Rokt to Braze.

Rokt-to-Braze Flow Diagram

1. Generate and onboard calendar subscribers#

Generating/Onboarding Calendar Subscribers

To use the calendar as a communication channel within Braze, you must have an existing calendar subscriber audience. A Braze campaign can be used to generate calendar subscribers from your existing audience through email, SMS, push notification, or another channel. Make sure your message includes the benefits of the calendar and how to subscribe.

Listed in the table below are the available campaign communication methods:

MethodOriginDescription
EmailBrazeSend an email that explains the calendar subscription with a link directing the user to where they can subscribe to the calendar.
SMSBrazeSend an SMS that explains the calendar subscription with a link directing the user to where they can subscribe to the calendar.
Push notificationBrazeSend a push notification that explains the calendar subscription with a link directing the user to where they can subscribe to the calendar.

Then, once the audience exists, you can start using the calendar as a communication channel.

Calendar Communication Channel

Where and how to subscribe#

Your existing audience member needs to be directed to where they can subscribe to the relevant calendar. Your Braze and Rokt Calendar account managers can work together to assess the context of your business and determine the most appropriate subscription integration method.

Subscription integration methods#

Listed in the table below are the various ways for an audience member to subscribe to a calendar.

Integration methodSystemContactDescription
Rokt Calendar SmartCal pageRokt CalendarRokt Calendar account manager- Hosted by Rokt—no setup required
- Embedded into a page on your website—minimal setup required
Rokt placement
Coming soon
RoktRokt account managerThe placement offers add to calendar functionality, enabling the user to subscribe to the relevant calendar. The Rokt placement can be presented:

- Pre-transaction
- Post-transaction
- Independently of a transaction as a standalone option (i.e., on a product page)

This requires adding the Rokt tag to your website and ensuring the relevant data is passed.
Rokt Calendar APIBrazeBraze account managerThis requires integration work from your development team.

Matching calendar subscribers to Braze users#

When a new calendar subscriber is generated through your chosen integration, the subscription data is sent to Braze. A critical piece of the Rokt Calendar and Braze integration is the ability to assign subscription data to a Braze user, if the user exists. Matching is done based on a unique identifier common to a calendar subscription, which is added during the subscription process. This identifier is determined by you, based on how you identify users in Braze. If there is no match between the calendar subscriber and the Braze user, a new user is created in Braze.

Calendar-to-Braze User Matching

Integration scenarios#

The possible scenarios are discussed below.

ContextSubscriber vs. userRequirements
You are an existing Rokt Calendar and Braze client. Specifically, your calendar has subscribers and your Braze account has users that pre-date the use of the Braze integration (i.e., client has independent existing relationships with both Rokt Calendar and Braze).- Calendar subscribers exist
- Braze users exist
- Matching an identifier at the subscription level to Braze user identifier (e.g., email).
- A data transfer of subscription data from Rokt Calendar to Braze user profile before go-live.
You are an existing Braze customer. Specifically, you do not use Rokt Calendar and your Braze account has existing users (i.e., client has an existing relationship with Braze only).- No calendar subscribers
- Braze users exist
As the subscribers are new, an agreed identifier—common to Braze users—is used.
You are not a Rokt Calendar or Braze client. Specifically, the calendar has no subscribers and the Braze account has no users that pre-date the use of the Braze integration (i.e., client has no existing relationship with Braze or Rokt Calendar).- No calendar subscribers
- No Braze users
As both calendar subscribers and Braze users are net new, an agreed identifier is assigned to the calendar subscription and Braze user.

Choosing a unique subscriber identifier#

A subscriber ID is used to uniquely identify the subscriber when they are created and subsequently flow through to other systems like Braze. The subscriber ID can be passed through during the subscription process by appending the subscriber ID to the calendar URL, for example mycal.calreplyapp.com/calendar1?subscriberid=1938d736.

Note that the subscriber ID is easily appended to the calendar URL if the client is launching the calendar page on their own asset where the user is known, usually through a logged-in or known user experience. If the user is not logged in—i.e., not known—then you can use the email capture functionality for the calendar, which allows the subscriber to enter an email as part of the subscription process. This then becomes the subscriber ID and is used to match a subscriber to a record in another system.

Data matching results#

ResultsDetails
Match existsA match exists between calendar subscriber and Braze user profile. The subscription data is added to the Braze user profile.
No match existsNo match exists between calendar subscriber and Braze contact. A new Braze user profile is created and the subscription data is added.

2. Audience segmentation in Braze#

Use the filter tool to segment your audience when configuring a Braze campaign. Segmentations can include standard profile attributes or custom attributes for subscription-related data.

Audience Segmentation in Braze

3. Sending a calendar event as a communication method#

Sending Calendar event as Communication Method

Creating a new event#

You can send a calendar event as a communication method in Braze by following these steps:

  1. Create a new Canvas.
  2. Define the steps in the journey.
  3. Set the message channel as Webhook.
  4. Choose the Rokt Calendar webhook template for creating new events.
  5. Edit the webhook to define the following:
    1. Event ID (must be unique for each event)
    2. Event title
    3. Event location
    4. Event description
    5. Event start/end date and time
    6. Event reminder minutes
  6. Start the Canvas.

Once Braze reaches the step in the journey where the calendar event is sent out, the Braze webhook communicates with Rokt Calendar to add an event to the calendars of the users' who are part of the audience.

Updating a calendar event#

You may want to update an existing calendar event that has already been sent out to subscribers.

  1. Create a new Canvas.
  2. Define the steps in the journey.
  3. Set the message channel as Webhook.
  4. Choose the Rokt Calendar webhook template for updating events.
  5. Edit the webhook to define the following:
    1. Event ID (ID of the event that you want to update)
    2. Event title
    3. Event location
    4. Event description
    5. Event start / end date and time
    6. Event reminder minutes
  6. Launch the Canvas.

Once Braze reaches the step in the journey where the calendar event is sent out, the Braze webhook communicates with Rokt Calendar to update the calendars of the users' who are part of the audience as defined by the segmentation.

4. Calendar reminders and optimizing the lock screen#

Rokt Calendar technology is built on top of calendaring products that already exist (Google and Apple)—providing full access into a user's calendar at the point of subscription. As opposed to a push notification—which can be turned off at the point of site visit or app download—calendar reminders are on by default across device, granting 100% visibility on the lock screen at all times.

The purpose of the reminder is to alert a user than an event is beginning as well as to prompt the user to take some type of follow-up action. The styling of the reminder is device specific. The content of the reminder, which is a combination of the event title and location, determines how effective the user engagement is. Below is an example of the user experience:

Calendar Reminder & Lock Screen Optimization

5. Performance measurement#

You can gain an understanding of how well your calendar communications are doing through performance measurement. Performance measurement takes into account two types of data: subscription data—which lives in Rokt Calendar—and engagement data—which lives in a variety of places. You can reach out to your account manager to further define reporting requirements and schedules.

Data typeSourceDetails
Subscription dataRokt Calendar- Subscription created
- Individual events added (coming soon)
- Individual events removed (coming soon)
- Individual events updated (coming soon)
- Unsubscribe (whole calendar)
Engagement dataRokt Calendar, client’s analytics- Rokt Calendar engagement calculation
- Trackable links (client defined)
Journey performanceBrazeBraze journey analytics

Support#

If you have any questions, reach out to:

Was this article helpful?