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
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]:

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

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:

Copy-Campaign-ID

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.

s2-cke

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.