v2.0¶
Version: 2.1.1 Updated: 2020-06-08
Table of Contents¶
- Introduction
- Requirement
- Data Collection
- JS Snippet
- API Config
- On Demand Number Request
- Rotating Numbers
- Debug Mode
- Appendix
Introduction¶
The iovox JavaScript (JS) API is designed for both normal development environments and tag management solutions for updating your web site contact number(s) with your iovox phone number(s). We use pure javascript in order to eliminate the chance of library collisions. It supports Referring Domain Attribution, AdWords, and unique session tracking in a 30 day look-back window.
Requirement¶
Your iovox Enterprise account needs to be set up with proper node and link structure to capitalize on full functionality of the JS API. If you have any questions regarding your iovox Enterprise account status, please contact your iovox representative.
API Data Collection and Number Replacement¶
There are multiple ways the JS API collects Link IDs and replaces numbers on your page. They can be specified by data attribute, request link object, and option targeting. The JS API will scrape the requested target location and intelligently preserve numbers containing anchor tags and international dialing indicator "+".
** We Recommend that you wrap your phone number in an html tag by itself as the API does a full html replacement of the targeted element; a span tag enclosing the phone number will minimize impact to the current css markup on your page. If your number is already wrapped in an anchor tag, you need not add an additional tag. Back to Table of Contents
Data Attribute¶
The JS API is designed to look for a data attribute "*data-iovoxlinkid*" attached to an html element enclosing the contact number. Below is a code example of a properly added data attribute with valid iovox Enterprise Account LinkId
<!-- number with span tag -->
<div class="contact-phone-number">
Contact Us At: <span data-iovoxlinkid="us-main-office">+1 888 408 4128</span>
</div>
<!-- number with anchor tag -->
<a class="contact-phone-number" href="tel:+18884084128" data-iovoxlinkid="us-main-office">+1 888 408 4128</a>
Request Links¶
This method is outlined in Optional Config Data
AdWords Target¶
This method is outlined in Optional Config Data
JS Snippet¶
The iovox JS API is added to the page using a small script snippet. This will download the iovox JS API library to the current window and run upon successful include. The snippet should be placed at the bottom of all of your pages in order to ensure all targets and data objects are available prior to the library initialization. testing domain: "https://sandbox-js.iovox.com"
<script>
window.iovoxApi = document.createElement('script');
iovoxApi.src = "https://js.iovox.com/js/v2/api.js";
// INSERT_YOUR_API_CONFIG_HERE
document.getElementsByTagName('head')[0].appendChild(iovoxApi);
</script>
API Config¶
The API Config is a javascript object that contains all of the settings and options available to your sites iovox JS API include.
Required Config Data¶
There are 2 points of data required for the JS API to be used.
- Access Key - this is your iovox issued JS Access Token
- Action Key - this is your iovox issued JS Action Token
The structure of the config object is demonstrated below:
window.iovoxApiConfig = {
accessKey:"REPLACE_WITH_YOUR_IOVOX_ACCESS_KEY",
actionKey:"REPLACE_WITH_YOUR_IOVOX_ACTION_KEY"
}
Optional Config Data¶
These config data points activate available options for the JS API, and must be included after the required config data has been added.
Request Links Data¶
The JS API supports an optional data collection object, which allows you to pass in a list of Link IDs and replacement target selectors. Selectors *must* be valid JS selectors. Below is a properly formatted request links object. About data collection and number replacement
iovoxApiConfig.requestLinks = {
items:[
{ linkId:"us-main-office", selector:".usMainContact" },
{ linkId:"us-support", selector:"#usSupport" },
{ linkId:"uk-main-office", selector:".ukmainContact" },
{ linkId:"uk-support", selector:"#ukSupport" }
]
}
Number Format Data¶
The JS API is designed to support pages with multiple country listings and as such can handle multiple number formats on a single page automatically. By collecting the number from the target selector and processing the value to generate a mask, the returned phone number will be formatted to match the original listed number for a supported number format. Should you wish to set a global number format for all numbers, you can specify a global number format that will be applied to all numbers by using the following config option.
AdWords Target Data¶
The JS API has intelligent AdWords referral detection. Using iovox AdWords integration the JS API checks the landing URL for our custom parameter (iogid=number_linked_to_adwords_impression). If the JS API detects an AdWords referral, the number associated with the ad impression will be placed in all requested Link ID Selectors as well as a custom target location that you can specify.The AdWords Target can be a single or comma separated list of valid JS selector(s). About data collection and number replacement
//single selector example
iovoxApiConfig.adWordsTarget = "#header-contact-number";
//multiple selector example
iovoxApiConfig.adWordsTarget = "#header-contact-number,#modal-contact-form-number,.footerContactNumber";
Referring Domain Data¶
The JS API supports dynamic domain referral Link ID lookup. The JS API appends _source to the requested Link ID will look up LinkId_source for the requested links.
First you must Activate Domain Referral Checks
There are 4 customized options for this feature.
- Referring Domains List Custom Domain Referral List
- Current URI Matching Current URI Matching
- Link ID replacement Lookup Link ID Replacement
-
Fallback Referrer Link ID Lookup Fallback Referrer
Activate Domain Referral Checks¶
Include the following config option, this will activate the default referral list
Custom Domain Referral List¶
You can choose to create your own referral list. Using this option will bypass the default list and allow you to set the source for any referring domain, path, or url parameter. Referral matching evaluates the list from top to bottom so url parameters should list towards the top, and same domain paths should list most complex last, so that a more broad match is made when a complex match is not available. Below is an example of a custom domain referral list.
iovoxApiConfig.referringDomains = [ {domain:"google",source:"organic"}, {domain:"bing",source:"organic"}, {domain:"yahoo",source:"organic"}, {domain:"facebook",source:"facebook"}, {domain:"linkedin",source:"linkedin"}, {domain:"twitter",source:"social"}, {domain:"emailid=campaign_name",source:"email-campaign-name"}, {domain:"domain.com/dailynews",source:"news-page"}, {domain:"",source:"direct"}, {domain:"domain.com/dailynews/tech",source:"news-tech-page"}, {domain:"no_match_default",source:"other"} ];Activate Current URI Matching¶
Including the following config option will consume the domain referral list for terms or paths in the current page URI. ** note that current URI match will supersede any document.referral match made **
Link ID Replacement¶
This option allows you to look up Link IDs that match the source value instead for he requested Link ID. Ex: requested Link ID: main-contact will retrieve the number associated with the matched source value instead. To activate this option add the following to your config **
Fallback Referrer¶
This option allows you to do a cascaded look up of Link IDs. The JS API will first attempt to retrieve the number for matched linkId_source, if no number is located in your iovox account, the api will then retrieve Link ID that matches the source value. To activate this option add the following to your config **
** !Link ID Replacement and Fallback Referrer options do not work together Back to Table of Contents
Manual Number Updating¶
The JS API will automatically replace numbers on the page for you by default. However, you may choose to handle returned number data on your own. The returned data will be loaded to the window variable *iovoxApiData* with the number information as an array of *items* To activate this option add the following to your config
We recommend that if you select this option, to use our custom event listener. This will ensure that your data will update properly upon return from the server request. Our custom event name is "iovox-js-api-loaded". An example event listener:
window.addEventListener('iovox-js-api-loaded', (event) => {
yourCustoMethodToHandleTheReturnData();
});
Session Code Identifier¶
The JS API supports Session Identification for call conversion. Unique Session Codes are generated by the JS API for any guest that enters your site. The Session Code is tracked for 30 days from first bite. The Session page information is lifted from the page and stored as part of your analytics and can be retrieved at time of call placed by the guest. This is a very powerful tool for Marketing attribution, site support, and customer retention.
! This option requires additional setup with your iovox Account Manager in order to go to production.
Activate Session Code Identifier¶
Add the following to your your config
Session Code Display Targeting¶
The session code can be displayed any where you choose on your web page. To set the target pass a valid JS selector.
//single location
iovoxApiConfig.sessionCodeTarget = '#session-code';
//multiple loactions
iovoxApiConfig.sessionCodeTarget = '#header-session-code, #footer-session-code';
Session Data Layer¶
The Data Layer is how we store your guests interaction with your site. Each page load is logged to our session service and tied to your analytics. You can create any custom set of key:value paired JS objects to add to the dataLayer on each page load. This can include e-commerce information, non sensitive user information, etc. Our bas line dataLayer includes: browser information, user preferred language, domain, and page viewed. To add the dataLayer to your page you can add a window object, or add it to your config.
//dataLayer added to page as window object
window.iovoxDataLayer = {
cartTotal: '150',
cartItemCount: '4',
language: ( navigator.language || navigator.userLanguage ),
domain: document.location.origin,
page: document.location.pathname
}
//dataLayer added to config
iovoxApiConfig.dataLayer = {
cartTotal: '150',
cartItemCount: '4',
language: ( navigator.language || navigator.userLanguage ),
domain: document.location.origin,
page: document.location.pathname
}
On Demand Number Request¶
The JS API will also handle number On Demand Number Request. This option is great for modal pages and pages that load in a frame triggered by an event. Link Ids will need to be present on the page, or you can specify LinkIds and Selectors on request. To use On Demand Number request include the following to a modal, or on click event.
<script>
//script added to window with Link Ids on page
iovoxJsApi.initialize();
//with link id, selector passed
iovoxJsApi.initialize('linkId', 'selector');
</script>
//onclick request with link id, selector passed
onclick=iovoxJsApi.initialize('linkId', 'selector');
Rotating Numbers¶
Dynamic Rotating Numbers enable you to allocate numbers on demand, and dynamically forward them to a destination phone provided in real-time. Numbers are pulled from a pool, and you may configure multiple number pools for different scenarios such areas, lead type, web-pages, etc. Back to Table of Contents
Number Pools¶
Number pools will consist of configured numbers ready to be displayed on a page. When a number is displayed, tracking data is attached to the number and will be made available when a call arrives. This tracking data is customisable, and you can include any string value which is available on the page where the number is allocated. This data can then be pushed to you at the time of the call, or used to create dynamic call behaviour by altering parameters on call rules.
Call templates are configured on a pool-by-pool basis, so you may have a single template configured for all pools (i.e. Forward Call), or have customised behaviour(i.e. Play a whisper to the recipient to tell them where the call came from).
Numbers are allocated by the date they were last used, and will not be re-used until the entire remainder of the pool has been exhausted. You may also set a custom lifespan to ensure a number is never re-allocated before the allotted time.
Number pools are required be pre-configured, with the help of your account manager. You may always email support@iovox.com for assistance in getting your pools configured with the templates you choose. Back to Table of Contents
Including JavaScript for Dynamic Numbers¶
For dynamic number rotation include this javascript on your webpage:
<script>
window.iovoxApi = document.createElement('script');
iovoxApi.src = "https://cdn.iovox.com/rest/v1/dni.js";
// INSERT_YOUR_API_CONFIG_HERE
document.getElementsByTagName('head')[0].appendChild(iovoxApi);
</script>
You will then set up your configuration to allocate and replace numbers on the page. To specify numbers as dynamically rotating from a pool, we will include a similar JS snippet to link replacement but with "__ROTATING__" as the linkId.*You must include a forwarding number for each item in the `requestLinks` object in the `dialString` parameter*.
window.iovoxApiConfig = {
accessKey:"[your_access_key]", // Your API Access Key
actionKey: "[your_js_action_key]", // Your JavaScript Action Key
globalNumberFormat: '(xxx) xxx xxxx',
requestLinks: { items: [{ linkId: "__ROTATING__", selector: '.contact-phone-number, #sidebar-number', poolId: 'main_pool', dialString: '442081153158' }] },
siteData: { price: price, propertyAddress: address, visitedTimestamp: new Date(), myWebhookUrl: 'https://mywebhook-site.com' }
};
Each item in the `requestLinks` object is a new number set to be allocated and inserted. In the example above there is only one number being allocated and inserted, but it still may be inserted into multiple places on the webpage.
When the number is called- it will forward to the destination provided in the `dialString`, while running any custom template that is configured. Back to Table of Contents
Configuration Parameter Details for Dynamic Numbers¶
accessKey - Your API Access Key. This will be provided by iovox but is also available in the iovox portal under "API Settings".
actionKey - Your JavaScript Action Key. This allows some users to allocate numbers, but not every user with API access needs to have access to dynamic number allocation.
globalNumberFormat (optional) - The number format to use for all places number is inserted on the page. You can view more information about additional configuration in the Optional Data section.
requestLinks = A list of items describing each number which needs to be allocated.
linkId - Always set to "__ROTATING__" when using dynamic numbers.
selector - JavaScript selector(s) for DOM elements for number replacement. Each selector should point to a DOM Node which will only contain the phone number. If you select a DOM Node with children you may have information removed from page when innerHTML is overwritten. Multiple selectors should be comma separated.
poolId (optional*) - Your identifier for pool you wish to pull from. While technically this is optional, if you have more than a single pool it is recommended you set up your number pools with poolId and use them in your requests to prevent getting any numbers allocated from a different pool than you were expecting.
dialString - The phone number in E164 format of the destination that the allocated number will forward to. This will always be accessible as the variable `\(destinationNumber\` in your call templates, and therefore any forwarding template should use \`\)destinationNumber` as the forwarding destination.
siteData - A javascript object containing any custom tracking information you wish to include from the page. You may include any string data which is available on the page. Data with null or false values will be ignored.
sea - if present and set to true, it will grab automatically all parameters to enable per session tracking, like utm_source, utm_medium, gclid/msclkid/adobeid, ga, ...
source - if present, must be an array of parameters you want to track to have an unique number per this ressources
Per Source vs Per Session¶
To track each user session individually, set the value of "sea" to true, this needs to be a boolean value.
window.iovoxApiConfig = {
accessKey:"[your_access_key]", // Your API Access Key
actionKey: "[your_js_action_key]", // Your JavaScript Action Key
globalNumberFormat: '(xxx) xxx xxxx',
requestLinks: { items: [{ linkId: "__ROTATING__", selector: '.contact-phone-number, #sidebar-number', poolId: 'main_pool', dialString: '442081153158' }] },
siteData: { price: price, propertyAddress: address, visitedTimestamp: new Date(), myWebhookUrl: 'https://mywebhook-site.com' },
sea: true
};
If you would like to only track referral sources, i.e. Google, you must set "sea" true, but also define the combination of sources you want to track.
A special value of "_referer" will track the referer's host and allow to auto fulfil utm_source and utm_medium
window.iovoxApiConfig = {
accessKey:"[your_access_key]", // Your API Access Key
actionKey: "[your_js_action_key]", // Your JavaScript Action Key
globalNumberFormat: '(xxx) xxx xxxx',
requestLinks: { items: [{ linkId: "__ROTATING__", selector: '.contact-phone-number, #sidebar-number', poolId: 'main_pool', dialString: '442081153158' }] },
siteData: { price: price, propertyAddress: address, visitedTimestamp: new Date(), myWebhookUrl: 'https://mywebhook-site.com' },
sea: true,
source: [ "affId"], // affilated id
// source: [ "ref_partner", "medium" ], // a distinct number for each couple ref_partner + medium
// source: [ "utm_source", "utm_campaign" ],
// source: [ "_referer" ] // will use hostname of referer to provide utm_source, utm_medium
};
Setting Node/Link Name & Analytics Fields¶
Since rotating numbers are allocated to a pool instead of a Node/Link grouping like a static number would be, the Node/Link information on the dashboard will be set to default values to start. You may wish to set these values yourself, so you can view and filter analytics more easily. The following values in the `siteData` object will be displayed instead of the defaults if provided:
nodeName - Calls will be attributed to the provided "Node Name". nodeId - Calls will be attributed to the provided "Node ID". nodeType Calls will be attributed with the provided "Node Type". linkName - Calls will be attributed to the provided "Link Name". linkId - Calls will be attributed to the provided "Link ID". linkType - Calls will be attributed with the provided "Link Type".
All values are optional and limited to 100 characters. Any value not provided or empty will receive a default value.
You may also include variables prefixed with '$' in the above six fields, referencing a source or session tracking value, or any other value in the "siteData" object.
Example:
siteData: {
id: "MyID-1000",
nodeName: "$utm_medium",
linkName: "$utm_source",
nodeType: "$utm_campaign"
linkType: "Static value",
nodeId: "$id",
linkId: "$id - $utm_source"
}
Allocating Number With Server Request¶
You may allocate a rotating number directly via HTTP-Request if desired. This is the same request used by the iovox dynamic numbers javascript, therefore you may leverage any of the features outlined in the other rotating number sections.
Request¶
POST rest.iovox.com/rest/v1/numbers/dynamicnumber/allocate
{
accessKey: "{accessKey}",
actionKey: "{actionKey}",
numberPool: "{poolId}", // The Pool ID of the rotating number pool
dialString: "44XXXXXXXXXX", // Internationalised number to set as destination
hostname: "www.example.com", // Host configured on rotating number pool
// Parameters below are all optional
siteData: {
nodeName: "{Node Name to Attribute}",
linkName: "{Link Name to Attribute}",
nodeType: "{Node Type to Attribute}",
linkType: "{Link Type to Attribute}",
nodeId: "{Node ID to Attribute}",
linkId: "{Link ID to Attribute}"
// Additional fields will be made available for use in call flow
},
sessionKey: "{sessionKey}" // Unique session identifier to preserve and re-use number allocated.
}
The "hostname" parameter needs to match the site_url on the number pool that the number is to be pulled from, this is part of the verification process.
For more information on leveraging custom fields in 'siteData' visit: Set Access Tracking Data In Call Flow
Responses¶
Monitoring¶
This endpoint accepts an OPTIONS request for monitoring.
Accessing Tracking Data in Call Flows¶
In addition to `destinationNumber` you will have all the siteData you provided available in the call template. Each variable name will be the javascript key provided, and the value as it was provided.
Therefore if you provide specific listing information from when the number was allocated and seen, you can incorporate that into your call rules.
siteData: { leadSource: leadSource, propertyAddress: address, visitedTimestamp: new Date(), myWebhookUrl: 'https://mywebhook-site.com' }
This call example will read out the information to the called party prior to bridging the call:
<call id="callAndWhisper" label="Call And Whisper Source Listing" destinationPhoneNumber="$destinationNumber">
<calledMessage>
<textToSpeech textToSpeak="This is a lead from $leadSource about property at $address. The caller visited the page at $visitedTimestamp" voice="tts_uk_eng_male" />
</calledMessage>
<eventHandlers/>
</call>
Call templates can be configured to push data to an endpoint, as well as enact custom actions based on the information provided from the site. The `siteData` provided in your javascript configuration will always be available in the template as a custom variable. You can access custom variables in a template by using `$variableName` in the XML, or have us assist you in getting the template configured. You may also include any iovox internal variables which are always available as well.
Here is an example of a rule which makes an HTTP POST request to an endpoint which was sent at the time of number allocation in the example above.
<restApiClient id="Call-Start"
label="HTTP Request Start"
url="$myWebhookUrl/call-start"
method="POST"
headers="Content-Type: application/json,Accept: application/json"
body='{"price":"$price", "propertyAddress":"$propertyAddress", "visitedTimestamp":"$visitedTimestmp", "trackedNumber":"$_voxnumber" }'/>
There are many possibilities for how to leverage these extra insights. If you have specific questions on how to create some dynamic behaviour by leveraging iovox dynamic numbers, please don't hesitate to reach out to support@iovox.com. Back to Table of Contents
Multi-Selector Replacement¶
You may provide comma separated selectors in order to replace multiple instances of a phone number on your page:
selector: '.contact-phone-number, #contact-us', // This will replace both selected elements with the same new number
Note that the selector expects a DOM node to be chosen which contains only the phone number targeted for replacement. If you require special replacement within nested DOM nodes or images, you may want to consider using customized JavaScript and manual number updating in order to avoid removing any page data stored under the provided selector. This will allow you to bind on the "iovox-js-api-loaded" event and handle replacement in a custom fashion. Back to Table of Contents
Static Rotating Numbers¶
For accounts configured to do so, numbers may be dynamically allocated and linked to page data in the form of categories. *This is only for accounts which utilise static forwarding and do not alter forwarding destination.* These categories and their values will be attached, meaning any calls to the number will feature the data until the time that the number is reassigned. Back to Table of Contents
Additional Config Values (Static Rotation Using Categories)¶
The `requestLinks` config value is required for rotating numbers, as is the additional value for `rotatingCategories`.
- Request Links (Rotating) - Like the standard list of links to replace on the page, each linkId specified as __ROTATING__ will replace the given selector with a dynamic number. `
- Rotating Categories - This is the list of values that will be included from the page at the time of allocation. The list is a set of key/value pairs, where the key is a valid Category ID from your account, and the value is a reference to a string parseable value. The Category ID must be pre-configured on the account, or the data will be ignored.
Here is an example of what a rotating numbers config using categories looks like:
window.iovoxApiConfig = {
accessKey:"REPLACE_WITH_YOUR_IOVOX_ACCESS_KEY",
actionKey:"REPLACE_WITH_YOUR_IOVOX_ACTION_KEY",
requestLinks: { items: [{ linkId: "__ROTATING__", selector: '.contact-phone-number' }] },
rotatingCategories: { referer_url: window.location.href, visit_date: new Date() }
}
Country & Area Code Matching (Static Rotation Only)¶
The country and area for the dynamic number is determined by the existing number on the webpage when the javascript is run. If there is no valid phone number in any of the selectors provided, or there are no voxnumbers in your account matching the given geographic, than any number will be used. Area code is matched first, then country if area cannot be matched.
There is another optional configuration value, which you may want to use if numbers are displayed in a localised format on the site. The key `countryCode` may be added to a requestLinks item, to aid in the recognition of the country. This will allow local numbers to still be fetched dynamically by country. If the page number is already in E164, no countryCode is required.
Examples: Displayed Number: (415) XXX XXX XXX - `countryCode: 1` - Fetch United States Number in Area Displayed Number: 020 819X XXXX - `countryCode : 44` - Fetch United Kingdom Number in Area Displayed Number: +447XXXXXXXXX - `No Country Code Required` - Fetch United Kingdom Number in Area
Therefore the `requestLinks` configuration, with a countryCode value will look as follows:
requestLinks: { items: [{ linkId: "__ROTATING__", selector: '.contact-phone-number', countryCode: 1 }] },
Debug Mode¶
The JS API also has a Debug Mode. This is great for troubleshooting and setup purposes. To interact with debug mode, open your browser console and run the following commands
//activate debug mode
iovoxJsApi.setDebug(true);
//deactivate debug mode
iovoxJsApi.setDebug(false);
APPENDIX¶
Number Format¶
The IOVOX JS API supports he following number masks
US Number Formats¶
x xxx xxx xxxx, x (xxx) xxx xxxx, x (xxx) xxx-xxxx, xxx xxx xxxx, xxx xxx.xxxx, xxx.xxx.xxxx, (xxx) xxx xxxx, (xxx) xxx.xxxx, (xxx).xxx.xxxx, xxx xxx-xxxx, (xxx) xxx-xxxx, (xxx)-xxx-xxxx, (xxx)xxx-xxxx, xxx-xxx-xxxx
NON-US Number Formats¶
xx xxx xx xx, xxx xx xx xx, xxx xxx xxxxx, xx xxx xxx xxxx, xx (x)xxx xxx xxxx, xx xxxx xxx xxxx, xx (x)xx xxxx xxxx, xx xxx xxxx xxxx, xx xx xxxxxxxx, xx (x)xxx xxxxxx, xx xx xxx xxxx
** custom number format masking available upon request. Back to Table of Contents
Default Referral Domains List¶
| Domain | Source |
|---|---|
| organic | |
| bing | organic |
| yahoo | organic |
| social | |
| social | |
| social | |
| no referring domain | direct |
| no matched domain | other |