Custom Keyed Entry

We highly recommend that you use Custom Keyed Entry for desktop modal and landing pages only. The dual-tap button method performs significantly better on mobile than keyed entry.

 


Obtain a List Building Campaign ID

You'll need a List Building campaign ID to follow along with the rest of the API instructions. To get a campaign ID, click on List Building [1], then click on New List Building Campaign [2]:

Custom-Keyed-Entry-Get-Campaign-ID-Create

 

Select Modal [1], give your campaign a name [2], and click Next [3]:

Select-Modal-Continue

 

On the next screen select Desktop [1] before clicking Next [2]:

Modal-Type

 

Now we want to modify your blocklist, so select the Settings tab [1]. You can change whatever other flow settings you need, then expand the Allowlist / Blocklist [2]:

Expand-Blocklist

 

You need to enter this pattern in your Allowlist / Blocklist:

!/**

 

We still don't have the List Building campaign ID yet at this point. To generate one you'll need to save your current List Building campaign as a draft. After saving it as a draft, you'll be taken back to the List Building campaign list. Click on the three dots under Options [1] and select Edit Modal [2]:

Select-Edit-Modal

 

Under the Design tab [1], choose Edit Source Code [2]:Edit-Design-Edit-Source-Code

 

There you will see your campaign ID [1] along with a one-click button to copy it to your clipboard [2]. Save this number for the next steps:

Copy-Campaign-ID

Back to Top

 


API Specifications

Technical details associated with making the API request are as follows. You can also see an example in the section Using JavaScript below.

POST: https://vyg.mobi/api/v2/subscriber

Payload: Replace the campaignId value in this code with your Campaign ID, and ensure phone numbers are properly formatted with a + and the country code according to E.164 format:

{   
"phoneNumber": "<phone starting with +1>" (e.g., +13108293002),
"campaignId": <campaignId> (e.g., 1234),
}

 

Expected Responses

200 Already Subscribed

201 Subscribed Successful

 

Example Payload with Optional Attributes

{ 
"phoneNumber": "+15555555555",
"campaignId": 1234,
"attributes": {
"email": "my@domain.com"
}
}

Back to Top

 

 


Using JavaScript

This is an example that you can use to send the phone number to Voyage from the client-side of your application. The Voyage Global Tag must be included within your <head> element.

You will then need to pass the Campaign ID and Phone Number below to our system when a user submits their phone number.

Method

voyage.subscribe(<PHONE_NUMBER>, { campaignId: <CAMPAIGN_ID> });

 

Options
campaignId: (Required) The identifier for the List Building campaign to submit to.
attributes: An object containing key-value pairs of attributes to store for the subscriber.

Example Attributes Submission

voyage.subscribe('15555555555', { 
campaignId: 1234,
attributes: {
crmId: 5678,
email: "my@domain.com",
birthDate: "01/01/0001",
color: "blue"
}
});

 

Example HTML Form Submission

<script type="text/javascript">
// Set the Campaign ID for the submission
var campaignId = 1234;

// Retrieve the form element by the id attribute
var form = document.getElementById('my-form');

if (form) {
form.addEventListener('submit', function (event) {
// Retrieve the phone number from the field containing "phone" in name attribute
var phoneField = form.querySelector('input[name~="phone"]);
var phoneNumber = phoneField ? phoneField.value : '';

// Optional: Prevents reloading the page if using a standard form submit.
// event.preventDefault()

// Optional: Validate form has all correct details
// validate();

// Submit the phone number to Voyage
voyage.subscribe(phoneNumber, { campaignId })
});
}
</script>

Back to Top

 

 


Performance Statistics

When comparing performance of keyed entry versus dual-tap on mobile, the dual-tap method consistently, drastically outperforms keyed entry on mobile. Below are statistics detailing this performance gap. Keyed entry should be reserved for specific use cases where dual-tap is not possible including for desktop SMS opt-in.

s2-cke

Statistics: keyed entry modal versus dual tap method. CTR is 20x higher for dual-tap method.

Back to Top

 

 

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