Tracking with Custom Events

Custom events are those which you define and implement to extend default Drips triggers. They help you follow subscriber actions beyond standard Voyage events. Here we'll show you how to set up custom events, and the many different ways you can use them to customize your subscribers' experience.

Refer to our sister article for more common examples of custom events.

 


Navigation and Creating Custom Events

To see existing Custom Events or to create a new one, you'll need to navigate to Settings [1] on the Voyage main menu, then select Events [2] near the bottom. Here is where you'll be able to browse, edit, and delete any existing custom events [3]. Click on + New Event [4] to follow along with our guide:

Navigation-to-Custom-Events

 

Give your Event a name [1], and click on Add Attribute [2] as many times as needed to incorporate attributes you anticipate. Each attribute requires a name [3], description [4], and a data type [5]. As you can see there are six possible data types. You'll notice your event tracking code is updating in real time [6] as you add and modify attributes. This code can be easily copied in JS or cURL format. When done, click Create [7]:

Add-Attributes-and-Create-Event

Back to Top

 

 


Implement Custom Events

Trigger custom events from any page of your site by copying the script shown below your event when creating or editing the event. Select your desired format [1], then click Copy Script [2]. Place the code into your page with relevant dynamic value(s):

Select-Code-Format-and-Copy-Script

Note: Requires the Voyage Global Tag to be installed.

See this article for a list of common examples to utilize Custom Events to trigger Drips from a variety of platforms.

Back to Top

 

 


Custom Events in Drips

We have a full article on creating Drips here, so refer to that if this is your first time creating a Drip. Very early on in the creation process, you'll be presented with an option to select a Trigger [1]. You'll want to select the Custom menu option [2], and look through all your custom triggers to find the one you are looking for. In our case, product review tracking test [3]:

Select-Custom-Event-Trigger

 

Then, when you are composing the message for that Drip [1], you'll be able to select Dynamic Variables [2], choose Event [3], and insert any of the variables you've defined for your custom event [4]:

Using-Event-Variables-in-Message

Back to Top

 

 


Building Segments with Custom Events

Additionally, it is possible to segment your subscriber base using custom events. First, go to the main Segments section [1], and click on New Segment [2]:

Segments-from-Custom-Events

 

Click on Add Filter [1] to see the option that let's you chose a filter group. In this case, you'll select Voyage, then Custom Event [2]. From there you can click on select values [3] that will expand a list of all the custom events you've created [4]. Note: Currently it's not possible to build segments from custom event metadata values:

Custom-Event-Segmentation-Selection

Back to Top

 

 


Integration with Custom Events

You can integrate with third-part applications using custom events. Application-to-Application (A2A) usage is supported for this purpose.

To create your own API Keys, navigate to Settings [1], then Advanced [2], and scroll down to API Keys [3]. Clicking on Add API Key [4] will generate a new key that you can activate or deactivate as needed [5]. Click on the copy icon [6] to send the API key to your clipboard. A valid API key must be included in the header of requests:

Navigate-to-and-Generate-API-Keys

 

API Details

With this method, events can be published with either Phone Number or Voyage Subscriber ID.

Request

phone: [string] Phone Number for the subscriber (e.g. "+15555555555")

subscriberId: [string] Voyage-specific identifier for the subscriber

POST /api/v1/customEvent HTTP/1.1
Host: api.voyagetext.com
Accept: application/json
Content-Type: application/json
x-api-key: <API_KEY>

{
"eventTypeId": <EVENT_ID>,
"phone": "<PHONE_NUMBER>",
"eventMeta": {
"productName": "Name",
"customerName": "Name",
"rating": 199
}
}
{
"eventTypeId": <EVENT_ID>,
"subscriberId": "<VOYAGE_SUBSCRIBER_ID>",
"eventMeta": {
"productName": "Name",
"customerName": "Name",
"rating": 199
}
}

 

 

API Examples

cURL

curl -d '{
"eventTypeId": <EVENT_ID>,
"phone": "<PHONE_NUMBER>",
"eventMeta": {
"productName": "Name",
"customerName": "Name",
"rating": 199
}
}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: <API_KEY>' \
https://api.voyagetext.com/api/v1/customEvent

Back to Top

 

 


Custom Event Schema

Custom events are defined with standard JSON schemes, which are well documented at json-schema.org. Configuring a custom event in the Voyage API ultimately generates a schema that looks very much like the included examples. This schema will later be used by the system to validate incoming event data.
If there are more complex data structures, such as embedded lists, nullables or objects, you will need to develop a custom schema as our tool currently only supports single dimensional objects. Please contact service@voyagesms.com if you would like to implement a more complex custom event.

Embedded objects and lists cannot be used to personalize messages at this time

 
Here is an example of a more complex Custom Event schema: 
{
 "$id": "https://voyagesms.com/custom.event.schema.json",
 "type": "object",
 "$schema": "http://json-schema.org/draft-04/schema#",
 "required": ["name", "age", "img"],
 "properties": {
   "age": {
     "use": "number",
     "type": "number",
     "title": "age",
     "description": "Age"
   },
   "img": {
     "use": "image",
     "type": [ "string", "null"]
     "title": "img",
     "format": "uri",
     "description": "Picture"
   },
   "name": {
     "use": "text",
     "type": "string",
     "title": "name",
     "description": "Name"
   }
 },
 "description": "Customevent"
}

 

 

Integration Partners

For our integration partners, standardized events can be created to apply across multiple clients. Please contact service@voyagesms.com for more information on how to get started.

Back to Top

 

 

If you have any additional questions please contact us at service@voyagesms.com.