Start enriching your app

Docs

JavaScript

Introduction

The Sinch SDK is a product that makes adding voice calling, instant messaging or phone verification to web apps easy. It handles the complexity of signaling and audio management while providing you the freedom to create a stunning user interface. The current release supports instant messaging, web/phone (PSTN) calling as well as verification.

This document provides an overview for developers integrating with the Sinch SDK for the first time. It outlines the prerequisites and guides you through the process of verifying phone numbers in a Javascript environment, such as in a website.

Please see the Reference Documentation for a comprehensive description of all the classes.

Please note: Should you encounter any bugs, glitches, lack of functionality or other problems using our SDK, please send us an email to dev@sinch.com. Your help in this regard is greatly appreciated.

First time setup

This is a step-by-step guide about setting up the Sinch SDK for the first time.

Register an Application

  1. Register a Sinch Developer account at http://www.sinch.com/signup.
  2. Setup a new Application using the Dashboard where you can then obtain an Application Key and Application Secret.

Download

The Sinch SDK can be downloaded at www.sinch.com/downloads/. It contains: the Sinch JS SDK, this user guide, reference documentation, and sample apps.

Running sample apps

Make sure you configure your application key in the sample apps by replacing the placeholder text “MY_APPLICATION_KEY” with your key. Samples can be run in the browser as files by double-clicking the index.html file. Make sure you open the developer console in your browser to catch possible error messages.

Note: Currently, calling only works in the Chrome or Firefox browsers. Chrome additionally requires the web page to be loaded using http or https and is not compatible with local storage (i.e., file://).

Development

There are many ways to include Sinch in your project, enabling you to select a suitable method depending on how your project is set up.

Hosted with your webapp

You can host the library co-located with your website and include Sinch using

<script src="sinch.min.js"></script>

Load from Sinch CDN

If you prefer to always load the latest version from our CDN, use

<script src="//cdn.sinch.com/latest/sinch.min.js"></script>

To control which version you load from our CDN, use

<script src="//cdn.sinch.com/0.0.1/sinch.min.js"></script>

Sinch is available as a npm package

If you are using NodeJS, add a dependency to Sinch by running:

npm install sinch-rtc --save

Note: The –save flag is optional for saving the dependency in package.json

Import Sinch SDK in your project using

var SinchClient = require('sinch-rtc');

Sinch is available as a Bower module

If you are using Bower, add a dependency to Sinch by running:

bower install sinch-rtc --save

Import the Sinch SDK in your website using

<script src="PATH_TO_BOWER_MODULES/sinch-rtc/sinch.min.js"></script>

Note: The –save flag is optional for saving the dependency in bower.json

Sinch client

The SinchClient class is the SDK entry point. It is used to configure the user’s and device’s capabilities, as well as providing access to feature classes such as the MessageClient, CallClient, and VerificationClient.

Instantiating the SinchClient

To use Sinch you first need to create a “sinchClient” object using the application key and you can specify some other options.

var sinchClient = new SinchClient({
    applicationKey: '<application_key>'
});

The <application_key> is obtained from the Sinch Developer Dashboard. In this example, the SinchClient is set up for Verification.

Asynchronous Sinch Calls

The Sinch SDK contains many asynchronous methods. Several network requests are made in the background when making certain method calls and, while this happens, your code continues to execute.

When using asynchronous methods in Sinch, there are two ways of acting on the result. All asynchronous methods accept two callbacks as additional parameters, first the success callback, then the fail callback.

Additionally, all asynchronous methods in Sinch also return a promise, which will either be resolved or rejected. If it’s resolved the next method in the chain, which is specified using .then(), is called. If there is a failure, the method specified in .fail() is called.

Sinch with callbacks

var handleSuccess = function() {...};
var handleFail = function() {...};

sinchClient.start(loginObj, handleSuccess, handleFail);

Sinch with promises

var handleSuccess = function() {...};
var handleFail = function() {...};

sinchClient.start(loginObj)
    .then(handleSuccess)
    .fail(handleFail);

The benefit of using promises is that it’s easy to make a chain of method calls and the code is clearer, but either method works.

Note: If both callbacks and promises are used, the execution order is for callbacks to be executed first followed by the methods in the promise-chain, specified using .then()

Verification

The Sinch JavaScript SDK supports verification of phone numbers via SMS and Callout. Flash calling verification will be supported in a later release.

SMS Verification

Verification of a phone number is performed in two steps, a verification SMS is requested and a verification code for that particular verification session is sent to the recipient. It’s the responsibility of the developer to ask the end-user to provide the verification code from the SMS.

When the verification code is known, the verify(code, success, fail) method is used to verify the number.

When the supplied code is correct, the phone number is considered verified and you will receive this information in the response. If you have configured a callback URL for verification you will also receive confirmation through a callback to your backend.

Request SMS verification

To initiate a SMS verification, start by creating a SMS verification session. This is done by calling the createSmsVerification(phoneNumber) method on your sinchClient. This method returns a verification object which can be used to send the verification SMS, and re-send the SMS, per the example below.

var sinchClient = new SinchClient({applicationKey: YOUR_APPLICATION_KEY})

var verification = sinchClient.createSmsVerification(PHONE_NUMBER)

verification.initiate(success, fail);

The call to initiate(success, fail) triggers sending a verification SMS. This method can be called multiple times, in the case another SMS should be sent. Callbacks for success and failure should be supplied to inform the user whether the action succeeded. However, delivery is not guaranteed even if success is called, which is why it is recommended to provide the end-user a user interface to re-send the verification SMS.

Verify SMS code

To verify the phone number, the resulting code from the SMS should be verified using the verify() method. This can be done in the following way:

var code = codeFromUser;

verification.verify(code, success, fail);

The verify method takes two callbacks (beyond the pin-code), which can be used to inform the user of any issues or of success in verifying the phone number. However, important actions should be performed server-side using the callback on successful verification of a phone number.

Act on SMS callbacks

As shown earlier, both initiate and verify take two callbacks as arguments for successful result or failure. These callbacks should be used to progress correctly through the flow:

  • UI to enter phone number
    • Success: Progress to enter verification code
    • Fail: UI to inform user of a problem and/or ask the user to try again
  • UI to enter verification code (or re-send SMS)
    • Success: Confirmation of successful verification
    • Fail: UI to inform user of verification problem

SMS Template

By default, the SMS template used for Sinch verification SMS has a fixed format. Contact us at dev@sinch.com to update its content when your app is ready for Production.

Callout Verification

Verification of a phone number is performed in one step: a PSTN call to the end-user phone is placed and a text-to-speech or recorded voice will instruct the end-user to press a digit.

To initiate a callout verification, start by creating a callout verification session. This is done by calling the createCalloutVerification(phoneNumber) method on your sinchClient. This method returns a verification object which can be used to initiate the call and act on outcome using callbacks, per the example below.

var sinchClient = new SinchClient({applicationKey: YOUR_APPLICATION_KEY})

var verification = sinchClient.createCalloutVerification(PHONE_NUMBER)

verification.initiate(success, fail);

The call to initiate(success, fail) triggers a PSTN call. This method can be called multiple times. Callbacks for success and failure should be supplied to inform the user whether the verification succeeded.

Pass data to your backend

For each call to verification.initiate(), the Sinch backend can perform a callback to the application backend to allow or disallow an SMS or flashcall being initiated. By using the optional parameter custom on SinchVerification.createFlashCallVerification and createSmsVerification, any unique identifier can be passed from the application to the application backend. The data is passed as a string. If there is a need for a more complex datatype, it needs to be stringified or encoded before being sent.

Promises

As an alternative to callbacks, the verification session object also supports promises. The execution order is for callbacks to be called first, followed by promises. When using promises, the full flow may look like this:

var sinchClient = new SinchClient({applicationKey: YOUR_APPLICATION_KEY})

var verification = sinchClient.createSmsVerification(PHONE_NUMBER)

verification.initiate().then(function(successInfo) {
    // Act on success
    // Display "enter pin" UI
}).fail(function(errorInfo) {
    // Act on error
});

//PIN is retrieved from user
var code = codeFromUser;

verification.verify(code).then(function(successInfo) {
    // Act on success (valid number)
}).fail(function(errorInfo) {
    // Act on error and inform the user / retry
});

Miscellaneous

Phone numbers

The phone number should be specified according to the E.164 number formatting (http://en.wikipedia.org/wiki/E.164) recommendation and should be prefixed with a ‘+’. E.g. to call the US phone number 415 555 0101, the phone number should be specified as “+14155550101”. The ‘+’ is the required prefix and the US country code ‘1’ prepended to the local subscriber number.

Encryption export regulations

Please check the Summary of U.S. Export Controls Applicable to Commercial Encryption Products and ensure that the application is registered for the Encryption Regulations, if applicable. It can be found under this link.

Statistics

The Sinch SDK client uploads statistics to the Sinch servers at the end of a call, a call failure, or similar event. The statistics are used for monitoring of network status, call quality, and other aspects regarding the general quality of the service.

Some of the information is not anonymous and may be associated with the User ID call participants.

The statistics upload is done by the client in the background.

Third party libraries and copyright notices

All Third Party Libraries and Copyright notices can be found under this link.