Documentation

---

Using the phone verification widget

You can add phone verification to any webpage easily by copying and pasting the embed code for a widget from your account. The widget will appear wherever you paste the code within your HTML.

---

Receiving verification results from the widget

JavaScript integration

The DialShield widget can trigger JavaScript functions in your webpage when verification succeeds or fails. You can use this feature to enable form fields, change text on the page, etc.

Upon successfully verifying a phone number, the widget will execute your function dialshield_success. Upon failing to verify a phone number due to entry of an incorrect code, the widget will execute your function dialshield_failure.

Example usage:

function dialshield_success() {
    document.getElementById('submit_button').disabled = false;
}

function dialshield_failure() {
    alert("Phone verification failed.");
}

Since JavaScript code runs in the user's browser, you should not consider this a secure method of confirming phone verification. To ensure a user's phone number has been verified, set up a web hook.

Web Hook Integration

We can POST data to a URL on your server to notify you whenever someone uses your verification widgets, and whenever a phone number is verified through the widget. You specify the URL we should POST to, if any, by clicking "Edit Widget" on the widget in your account.

When someone enters their phone number and clicks the "Call Me" or "Text Me" numbers, a POST is made to your URL with the following fields:

Field	Value
notification_type	call_started
widget_id	The ID of the widget used to initiate the call or text message. This corresponds to the widget ID shown on the widgets page of your account.
call_type	"voice" when a voice call has been placed, or "sms" when a text message has been sent
status	"success" if the call was successfully initiated, or "failure" if the call could not be initiated, for example, when an invalid phone number is supplied
call_id	A unique identifier assigned to this call or text
number	The phone number supplied by the user
code	The 4 digit verification code provided to the user by voice or text message
reference_id	A reference ID you supplied in your webpage; see explanation below for more information

You will receive a second POST when the user enters the verification code in the widget after receiving the call or text message. It will contain the following fields:

Field	Value
notification_type	verify
widget_id	The ID of the widget used to initiate the call or text message. This corresponds to the widget ID shown on the widgets page of your account.
status	"success" if the code entered was the same as the code provided and the phone has been verified, "failure" if the code entered was not the same as the code provided and the phone has not been verified
call_id	A unique identifier assigned to this call or text
number	The phone number supplied by the user
code	The 4 digit verification code provided to the user by voice or text message
entered	The verification code the user entered into the widget
reference_id	A reference ID you supplied in your webpage; see explanation below for more information

Reference ID

You often want to tie the user of a phone verification widget on your webpage to some other information, such as a user ID or e-mail address. You can do this by providing a reference ID in addition to the widget's embed code on your webpage. This reference ID will be sent with all web hook POSTs to your postback URL.

Provide the reference ID by defining a JavaScript variable ds_reference_id. Example (line 2):

<script type="text/javascript">
    ds_reference_id = '<?php echo $user_id; ?>';
    (function(){
    var ds = document.createElement('script');
    ds.type = 'text/javascript';
    ds.async = true;
    ds.src = 'http://app.dialshield.com/widget.js?id=999';
    (document.getElementsByTagName('head')[0]||document.getElementsByTagName('body')[0]).appendChild(ds);
    })();
</script>
<div id="dialshield_999"></div> 

Be sure to add the ds_reference_id to the embed code provided in your account, not the example code above.

Rate Limiting

To protect your widget from abuse, no number will be called or messaged more than 5 times in any 10 minute window. Attempts to call or message a number more than 5 times will be ignored; they will not generate postbacks or debit your account.