Braze

Receive Regal events into Braze in real-time

Suggest Edits

This guide describes how to get Regal reporting events like sms.sent and call.completed into Braze so they can appear on your Braze profiles and be available for use in the Braze segmentation tool, Canvas and Campaigns. This integration uses Regal Reporting Webhooks and Braze Data Transformation to automate data flow.

Create a Data Transformation in Braze

📘

Data transformation is currently in early access. Contact your Braze customer success manager if you are interested in participating in the early access.

Braze recommends creating a transformation per Regal webhook you plan to send to Braze.

To create a Data Transformation:

  • Navigate to the Transformations page in your Braze dashboard
  • Give your transformation a name and click ‘Create transformation’
  • Use the vertical menu icon to Copy webhook URL

Enable Reporting Webhooks in Regal

To set up Reporting Webhooks,

  • Go to the Regal app > Settings page.
  • In the section labeled "Reporting Webhooks", click "Create Webhook."
  • In the Webhook endpoint input, add the Braze Data Transformation Webhook URL for the associated Data Transformation.

📘

Updating an Endpoint

When you edit an endpoint, it can take up to 5 minutes for the cache to refresh and start sending events to your new endpoint instead.

🚧

Retries

Currently there are no retries on these events. If a response is not received within 5 seconds, the event is dropped and not retried. We will be adding retries in a future release.

Events

Regal's Reporting Webhooks guide includes the complete list of Reporting events that we publish. There you can see definitions of properties and sample payloads as well.

Transform Regal Events into Braze Events

Braze's Data Transformation feature allows you to map incoming Regal events into the format necessary to be added as attributes, events, or purchases in Braze.

To set up your data transformations in Braze, follow this documentation: https://www.braze.com/docs/data_transformation.

  1. Name your Data Transformation. It is recommended to set up a Data Transformation per event webhook.
  2. To test the connection, create an outbound call from the Regal Agent Desktop to your cell phone and submit the Conversation Summary form to create a call.completed event.
  3. Determine what identifiers you will use to map your contacts in Regal to your profiles in Braze. The available identifiers in Regal events include:
    1. userId - only set on events if you've previously sent this identifier for a contact
    2. traits.phone
    3. traits.email - only set on events if you've previously sent this identifier for a contact

🚧

Braze Supported Identifiers

Braze does not support phone numbers as an identifier. To use this as an identifier the phone number can be set as a User Alias. To learn more about Braze User Aliases, please refer to this documentation.

When using Braze Data Transformation email address can be used as an identifier. If the email address already exists as a profile within Braze, the existing profile will be updated. If the email address does not yet exist within Braze an email-only profile will be created.

Let's walk through a couple of example use cases:

Trigger an email from Braze based on a call disposition in Regal

Below is a sample payload for a call.completed event in Regal. 

{
  "userId": "123",
  "traits": {
    "phone": "+17625551796",
    "email": "[email protected]"
  },
  "name": "call.completed",
  "properties": {
    "agent_firstname": "Rebecca",
    "agent_fullname": "Rebecca Greene",
    "agent_id": "[email protected]",
    "direction": "OUTBOUND",
    "regal_voice_phone": "+19545558563",
    "regal_voice_phone_internal_name": "Sales Line",
    "contact_phone": "+176255517965",
    "call_id": "WTxxxxx9",
    "type": "Outbound Call",
    "disposition": "Converted During Convo",
    "notes": null,
    "objections": null,
    "campaign_name": "Life Insurance Quote Follow Up",
    "campaign_friendly_id": "445",
    "started_at": 1657855046,
    "ended_at": 1657855053,
    "completed_at": 1657855059,
    "talk_time": 7,
    "wrapup_time": 6,
    "handle_time": 13,
    "journey_uuid": null,
    "journey_name": null,
    "journey_friendly_id": null
  },
  "originalTimestamp": "1657855059",
  "eventSource": "Regal Voice"
}

Below is a sample Data Transformation to map this to a custom event in Braze.

// Braze’s /users/track endpoint expects timestamps in an ISO 8601 format. To use the Unix timestamp within Regal’s call.completed event payload as the event timestamp in Braze it must first be converted to ISO 8601. This can be done with the following code:
let unixTimestamp = payload.originalTimestamp;
let dateObj = new Date(unixTimestamp * 1000);
let isoString = dateObj.toISOString();


// This is a default template that you can use as a starting point. Feel free to delete this entirely to start from scratch, or to delete specific components as you see fit.


// First, this code defines a variable, "brazecall", to build up a /users/track request
// Everything from the incoming webhook is accessible via the special variable "payload". As such, you can template in desired values in your /users/track request with JS dot notation, such as payload.x.y.z


let brazecall = {
 "events": [
   {
     "external_id": payload.userId,
     "name": "Call Completed",
     "time": isoString,
     "_update_existing_only": false,
     "properties": {
       "agent_firstname": payload.properties.agent_firstname,
       "agent_fullname": payload.properties.agent_fullname,
       "agent_id": payload.properties.agent_id,
       "direction": payload.properties.direction,
       "regal_voice_phone": payload.properties.regal_voice_phone,
       "regal_voice_phone_internal_name": payload.properties.regal_voice_phone_internal_name,
       "contact_phone": payload.properties.contact_phone,
       "call_id": payload.properties.call_id,
       "type": payload.properties.type,
       "disposition": payload.properties.disposition,
       "notes": payload.properties.notes,
       "objections": payload.properties.objections,
       "campaign_name": payload.properties.campaign_name,
       "campaign_friendly_id": payload.properties.campaign_friendly_id,
       "started_at": payload.properties.started_at,
       "ended_at": payload.properties.ended_at,
       "completed_at": payload.properties.completed_at,
       "talk_time": payload.properties.talk_time,
       "wrapup_time": payload.properties.wrapup_time,
       "handle_time": payload.properties.handle_time,
       "journey_uuid": payload.properties.journey_uuid,
       "journey_name": payload.properties.journey_name,
       "journey_friendly_id": payload.properties.journey_friendly_id
     }
   }
 ]
};


// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;

Update profile attributes in Braze based on contact.attribute.edited events from Regal

Below is a sample payload for a contact.attribute.edited event in Regal. This event is fired each time one of your agents learns something new in a conversation and updates an attribute on the contact's profile.

{
  "userId": "123",
  "traits": {
    "phone": "+17625551796",
    "email": "[email protected]",
  },
  "name": "contact.attribute.edited",
  "properties": {
    "agent_email": "[email protected]",
    "contact_phone": "+17625551796",
    "changes": {
      "custom_properties": {
        "annual_income": {
          "old_value": "150,000",
          "new_value": "300,000"
        }
      }
    },
    "created_at": "1657855462"
  },
  "originalTimestamp": "1657855462",
  "eventSource": "Regal Voice"
}

Below is a sample Data Transformation to map the new custom property values to the relevant attributes on your Braze profiles:

// This is an example template that you can use as a starting point. Feel free to delete this entirely to start from scratch, or to delete specific components as you see fit


// Capture the key’s updated property value within the ‘changes’ object and store this in an attributes variable that can be used in the /users/track request


const changes = payload.properties.changes.custom_properties;


const attributes = {};
for (const key in changes) {
 attributes[key] = changes[key].new_value;
}


// First, this code defines a variable, "brazecall", to build up a /users/track request
// Everything from the incoming webhook is accessible via the special variable "payload". As such, you can template in desired values in your /users/track request with JS dot notation, such as payload.x.y.z




const brazecall = {
 "attributes": [
   {
     "external_id": payload.userId,
     "_update_existing_only": false,
     ...attributes
   }
 ]
};


// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;

Keep your experiments in Braze and Regal in sync using contact.experiment.assigned events

Below is a sample payload for a contact.experiment.assigned event in Regal.

{
  "userId": "123",
  "traits": {
    "phone": "+17625551796",
    "email": "[email protected]",
  },
  "name": "contact.experiment.assigned",
  "properties": {
    "experiment_name": "Post Call Offer Test",
    "experiment_id": "xxxx-xxxx-xxxx-xxxx",
    "experiment_variant": "Aggressive Offer - 50%",
    "journey_uuid": "xxxx-xxxx-xxxx-xxxx",
    "journey_friendly_id": 220,
    "journey_name": "Post Call Follow Up"
  },
  "originalTimestamp": "1657855118",
  "eventSource": "Regal Voice"
}

Below is a sample Data Transformation to map this to a custom event in Braze.

// Braze’s /users/track endpoint expects timestamps in an ISO 8601 format. To use the Unix timestamp within Regal’s call.completed event payload as the event timestamp in Braze it must first be converted to ISO 8601. This can be done with the following code:
let unixTimestamp = payload.originalTimestamp;
let dateObj = new Date(unixTimestamp * 1000);
let isoString = dateObj.toISOString();


// This is an example template that you can use as a starting point. Feel free to delete this entirely to start from scratch, or to delete specific components as you see fit


// First, this code defines a variable, "brazecall", to build up a /users/track request
// Everything from the incoming webhook is accessible via the special variable "payload". As such, you can template in desired values in your /users/track request with JS dot notation, such as payload.x.y.z
let brazecall = {
 "events": [
   {
     "external_id": payload.userId,
     "_update_existing_only": false,
     "name": "Contact Experiment Assigned",
     "time": isoString,
     "properties": {
       "experiment_name": payload.properties.experiment_name,
       "experiment_id": payload.properties.experiment_id,
       "experiment_variant": payload.properties.experiment_variant,
       "journey_uuid": payload.properties.journey_uuid,
       "journey_friendly_id": payload.properties.journey_friendly_id,
       "journey_name": payload.properties.journey_name
     }
   }
 ]
};


// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;

Unsubscribe a contact in Braze based on a contact.unsubscribed from Regal

Below is a sample payload for a contact.unsubscribed event in Regal.

{
  "userId": "123",
  "traits": {
    "phone": "+17625551796",
    "email": "[email protected]",
    "ip": "78.97.213.166"
  },
  "name": "contact.unsubscribed",
  "properties": {
    "new_subscription": true,
    "channel": "voice",
    "text": null,
    "ip": "207.38.149.143",
    "source": "regalvoice.agent_desktop",
    "timestamp": "1657855229"
  },
  "originalTimestamp": "1657855230",
  "eventSource": "Regal Voice"
}

Below is a sample Data Transformation to unsubscribe the contact in Braze.

// This is an example template that you can use as a starting point. Feel free to delete this entirely to start from scratch, or to delete specific components as you see fit


// First, this code defines a variable, "brazecall", to build up a /users/track request
// Everything from the incoming webhook is accessible via the special variable "payload". As such, you can template in desired values in your /users/track request with JS dot notation, such as payload.x.y.z


let brazecall = {
 "attributes": [
   {
     "external_id": payload.userId,
     "_update_existing_only": true,
     "subscription_groups" : [{
       "subscription_group_id": "YOUR SUBSCRIPTION GROUP ID",
       "subscription_state": "unsubscribed"
     }]
   }
 ]
};


// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;

Updated 11 months ago