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 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 or update a user, you must include one of the following identifiers in your call:

  • userId
  • phone
  • email

When Regal Voice receives an event, we will first look to match the event to an existing user's profile based on userId. If there is no matching userId, we will then look to match on phone. If there's no existing profile with that phone, we will then look to match on email. If there are no existing profiles with any of those identifiers we will create a new user.

The value you pass through userId displayed as External ID in the Regal Voice app.

Users for whom you add a phone become contacts in your Regal Voice audience. If a user does not include a phone number they will not appear in your Regal Voice audience (though we are still stitching events to their profile).

Traits in your events get added to the contact's profile in Regal Voice as contact properties. 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

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. See more details here.

❗️

Contact & event property data types

Each property on a contact or event 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 to be considered in journeys. 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