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
- Client Side API Specifications
- Using JavaScript
- Performance Statistics
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]:
Select Modal [1], give your campaign a name [2], and click Next [3]:
On the next screen select Desktop [1] before clicking Next [2]:
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]:
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]:
Under the Design tab [1], choose Edit Source Code [2]:
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:
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"
}
}
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>
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.
Statistics: keyed entry modal versus dual tap method. CTR is 20x higher for dual-tap method.
If you have any additional questions please contact us at service@voyagesms.com.