Overview

Use the Regal Voice API to send contact and event data to Regal Voice

This guide describes how to call the Regal Voice API directly. This is typically the best integration option if a home grown CRM is going to be the main source of data for Regal Voice or any other source for which Regal Voice doesn't have a native integration.

The below documentation describes the required event format and endpoint.

Authentication

Regal Voice uses API keys to authenticate requests. An API key must be included in the Authorization header for all requests unless otherwise noted.

For an API key please, reach out to [email protected]

Rate Limits

API requests are rate limited to 1,000 requests per second. Reach out to [email protected] if you require higher rate limits.

Custom Events Endpoint

The Regal Voice API is designed as a single Custom Events endpoint (https://events.regalvoice.com/events) that lets you creates a contact, update a contact or add a custom event to a contact’s profile.

Create or Update a Contact

To create a contact in your Audience, you must include phone in your API call.

To update a contact, you must include at least one of the following identifiers in your call:

  • userId
  • phone
  • email

However, you must ensure you've sent at least one event in the past tying these identifiers today. For example, if you first send an event that includes phone and userId, you can subsequently send events with just userId and they will tie to the correct contact. Same with email; if you first send an event with phone and email, you can subsequently send events with just email, and they will tie to the correct contact.

The value you pass through userId is usually the unique identifier that you recognize a user by in your own database or CRM. userId should be consistent across a customer’s lifetime and identify calls should include a userId as often as possible.

The userId will appear as External ID in the Regal app, and should not be shared across users.

We recommend using database IDs instead of simple email addresses or usernames, because database IDs never change and don't include PII. Instead email address or a username can be sent along along as traits.

📘

Phone is the Unique Identifier for a Contact in Regal

The contact phone is the unique identifier of a contact in Regal. If a user updates their phone number in your CRM, send an event that contains the same userId and a new phone. That will create a new contact in Regal with the new phone number.

Traits in your events get added to the contact's profile in Regal Voice as contact attributes. There are a standard set of supported traits including:

  • firstName
  • lastName
  • phone
  • email
  • age
  • gender
  • address
  • optIn
  • Any other traits you add become custom properties on a contact's profile in Regal Voice.

You can include also include originalTimestamp to indicate when the event originally happened and eventSource to indicate the source of the data.

Here's an example payload that will create a contact with the custom properties: salaryBracket, employmentStatus, and savingsGoal. (This will not yet subscribe the contact to sms or calls. For that, you need to include optIn in the payload).

{
 "userId": "123",
 "traits": {
    "firstName": "Rebecca",
    "lastName": "Greene",
    "phone": "+19545552399",
    "salaryBracket": "$100k-$500k",
    "employmentStatus": "Employed",
    "savingsGoal": "New Home"
},
"eventSource": "crm"
}

Include OptIn Information

In order to trigger outbound calls or sms messages from Regal Voice, you must collect the user’s explicit opt-in for those channels along with the user’s phone number.

Anytime you collect opt-in information for sms or phone calls, you should pass that information to Regal Voice in the optIn array within the traits.

Subscription Scenarios:

  • No opt in option is presented to a user, optIn array should be null. (In the Regal Voice app, contact's subscription status will appear as "No Status")
  • If a contact opts in, optIn array should contain subscribed set to true (In the Regal Voice app, user's subscription status will appear as "Subscribed")
  • If a user opts out, optIn array should contain subscribed set to false (In the Regal Voice app, user's subscription status will appear as "Unsubscribed")

Below is an example payload that will opt a contact in to both voice and sms. Opt in is by channel. Supported channels include voice and sms.

📘

Required fields for OptIn

Only the channel and subscribed properties are required; timestamp, ip and text are optional, but useful for maintaining an audit trail.

{
  "traits": {
    "phone": "+19545552399",
    "optIn": [
      {
        "channel": "sms",
        "subscribed": true,
        "timestamp": "2020-08-25T21:23:43Z",
        "ip": "172.16.254.1",
        "text": "By clicking the 'Submit' button below, I agree to receive automated marketing SMS and calls."
      }, 
      {
        "channel": "voice",
        "subscribed": true,
        "timestamp": "2020-08-25T21:23:43Z",
        "ip": "172.16.254.1",
        "text": "By clicking the 'Submit' button below, I agree to receive automated marketing SMS and calls."
      }
    ]
  },
    "originalTimestamp": "2000-03-06 11:12:28 -04:00",
    "eventSource": "kustomer"
  }

Add an Event

To create an event, send through a name of the event. And if there any properties for that event, include those in the properties object.

In order for an event to be associated with a contact, you must include at least one of the following in the payload:

  • userId
  • traits.phone
  • traits.email

Here is an example payload:

{
"userId": "123",
"name": "Student Enrolled",
"properties": {
  "course_title": "Introduction to Python",
  "course_amount": "$500",
  "course_start": "2021-11-21"
},
"originalTimestamp": "2000-03-06 11:12:28 -04:00",
"eventSource": "zapier"
}

Contact and Event Information in a Single Call

📘

Contact and event information in a single call

You can include both contact traits and event information in a single call. For example, if there's an event on your app called 'Sign Up Completed' - you can both create a 'Sign Up Completed' event and create or update the contact with whatever traits you collected in the Sign up form in a single call to the Regal Voice API. See example below.

{
  "userId": "123",
  "traits": {
      "phone": "+19545552399",
      "email": "[email protected]",
      "optIn": [
        {
          "channel": "sms",
          "subscribed": true,
          "timestamp": "2020-08-25T21:23:43Z",
          "source": "Signup flow",
          "ip": "172.16.254.1",
          "text": "By clicking the 'Submit' button below, I agree to receive automated marketing SMS and calls."
        }, 
        {
          "channel": "voice",
          "subscribed": true,
          "timestamp": "2020-08-25T21:23:43Z",
          "source": "Signup flow",
          "ip": "172.16.254.1",
          "text": "By clicking the 'Submit' button below, I agree to receive automated marketing SMS and calls."
        }
      ]
  },
    "originalTimestamp": "2000-03-06 11:12:28 -04:00",
    "eventSource": "hubspot",
    "name": "Sign Up Completed",
    "properties":
    {
     "signup_variant": "variant_a"
    }
}

Event Property Names

🚧

Event property names

Your Regal Voice account can contain up to 8,000 unique event property names. If the same field name is used on various events, each with a different event name, it counts multiple times against this limit. Mapping events to a single event name, and using properties and categories to capture specific information, cuts down on the number of field names in use. We will be removing this restriction by end of 2022. See more details here.

Data Types

❗️

Contact attribute & event property data types

Each contact attribute or event property has an associated data type. Once a property is cast, the data type cannot be overwritten, and API calls attempting to set or update an existing property with a value that cannot be coerced into the appropriate type will fail in journey conditional nodes. See more details here.

Testing your integration

To test your integration:

  • Start by using the API docs to send a sample request. You'll need your API key first. Email [email protected] to get one, if you don't already have it.
  • Go to the Recent Activity page in the Regal Voice app to view incoming track and page events
  • Go to the Audience page in the Regal Voice app to view your contacts (created from identify events) - remember in order for a user to appear in your audience they must have a phone. You can also view their optIn status from the Audience page