Tuesday, March 21, 2017

Quick Introduction of Plivo APIs

Plivo - SMS API, Voice API and Global Carrier Provider
  • Amazon of Telephony is a cloud based API platform for building voice and SMS enabled apps.
  • Provides API to make and receive calls, send SMS, make a conference call and more.

Getting Started with Plivo Web SDK

  • Plivo WebSDK allows us to make and receive calls using Plivo apps directly from any web browser.
  • Using SDK we can create apps like Click to Call, Conferencing Bridges and even Web Phones.
  • Currently plivo supports WebRTC on Google Chrome, and for all other browsers we falls back to Flash.
  • With the Web SDK, we can add many interesting functionality into Web app:
    • Call Center
    • Click to Call
    • Web based help desk
    • Web Conferencing
Web SDK

Plivo WebSDK allows us to make and receive calls using Plivo applications directly from any web browser. Using our SDK we can create appls like Click to Call, Conferencing apps and even Webphones. Currently plivo support WebRTC on Google Chrome, and for all other browsers, SDK falls back to Flash.

Including the javascript

<script type="text/javascript" src="https://s3.amazonaws.com/plivosdk/web/plivo.min.js"/>

Initializing the Plivo JS Object

The Plivo JS object needs to be initialized. Two event listeners are mandatory for the initialization.

//These two listeners are required before init
Plivo.onWebrtcNotSupported = webrtcNotSupportedAlert;
Plivo.onReqdy = onReady;
Plivo.init();

Registering using Plivo Endpoint

Register using your Plivo Endpoint credentials

var username = ' vinodkumartiwari';
var pass = 'XXXXXX';
Plivo.conn.login(username, pass);


Making a call to any number/sip endpoint. Do rember that the app attached to the registered endpoint should hava an answer url that will ensure that the correct <Dial> element is returned


var dest = “vinodkumartiwari@outlook.com”;
Plivo.conn.call(dest);

Accepting a Call

This is how an incoming call should be answered once the onIncomingCall event is received

Plivo.conn.answer()

Sending DTMF

The snippet below shows how can send a DTMF tone when in a phone call

var digit = “1”;
Plivo.conn.send_dtmf(digit);

Registeringn Events

The Plivo JS object receives many events. Take a look at how to add listeners for those events. In the following example the onLogin function is added as a listener for the onLogin events.

Function onLogin(){
console.log(“I have received the onLogin event!”);
}
Plivo.onLogin = onLogin;


Configuration Parameters

fallback_to_flash: If set to true uses flash in the browsers which do not support Web RTC. Default value is true.

debug: Enable debug message in JS log. Default is false.

mask_page_on_perm: Disable/masking page when webrtc/flash ask for permission to use microphone. Default is false.

perm_on_click: Set to true, if we want to ask for mic permission before each call. Set to false, if we want to ask for mic permission on page load.


Methods Exposed by the PlivoJS Object
  • Plivo.init(config): Initialize the PlivoJS object.
  • Plivo.conn.login(username, password): Register a Plivo endpoint.
  • Plivo.conn.logout(): Log out from a registered Plivo Endpoint.
  • Plivo.conn.call(destination, extraHeader): Make a call destination string/number or sip address and extraheader.
  • Plivo.conn.answer(): Answer an incoming call
  • Plivo.conn.hangup(): Hangup an ongoing call
  • Plivo.conn.send_dtmf(digital): Send digits as dtmf.
  • Plivo.conn.unmute()
  • Plivo.setRingTone(url)
  • Plivo.setDtmfTone(digit, url)
  • Plivo.setDebug(debug)


PlivoJS Object Receives Events

  • onReady
  • onLogin
  • onLoginFailed
  • onLogout
  • onCalling
  • onCallRemoteRinging
  • onCallAnswered
  • onCallTerminated
  • onIncomingCall(callerName, extraHeader)
  • onIncomingCallcanceled
  • onCallFailed(cause)
  • onWebrtcNotSupported
  • onMediaPermission

Extra Headers

Sometimes, we may need to add extra sip headers. The extraHeader param serves that purpose. It is in the form of javascript object of key value pairs. Where the key is the header name and the value is the header value.


var extraHeader = {
'X-PH-Header1' : 'value1',
'X-PH-Header2' : 'value2'
}

Plivo API

Plivo APIs are based on HTTP methods, which make it easy to write apps. We can use any HTTP client in any programming language or even our browser to interact with the API.

The below diagram outlines a typical case where API is called from our app and how Plivo works in such cases:



Default Base URL

The default base URL for Plive is: https://api.plive.com/{version}/
Note: For security reasons, all Plivo APIs are served over HTTPS only.

API Request

Plivo exposes a list of REST APIs to perform various actions. These APIs can be used in combination with an XML to create voice and SMS apps.

The base URL for all API requests is https://api.plivo.com/v1/.

Authentication

All requests to Plivo API are aulthenticated with Basic Auth using our AUTH ID and AUTH TOCKEN our Plivo AUTH ID and AUTH TOCKEN can be found when we login to our dashboard.

Content Type

Plivo only accepts input of the type application/json. All POST requests arguments mush be passed as json with the Content-Type set as application/json.

All GET and DELETE request arguments must be passed in the query string.

Asynchronous Request

All requests to Plivo API can be made asynchronous by adding the parameters listed below. When an asynchronous call is made, Plivo will return a generic response with the api_id and the API responses will be sent to the callback URL.


Arguments:

  1. callback_url: The URL notified by the API response is available and to which the response is sent.
  2. callback_method: The method used to notify the callback_url. Defaults to POST.

Response

{
“message”: “async api spawned”,
“api_id”: 63f0761a-e0ed-11e1-8ea7-12313924e3a6"
}

API Response

All Plive API return a response in json format. An api_id is set in each response to uniquely identify your request. The API returns one of the following HTTP status codes.

  • 200 – Request has been executed
  • 201 – Resource created
  • 202 – Resource changed
  • 204 – Resource deleted
  • 400 – A parameter is missin or is invalid
  • 401 – Authentication failed
  • 404 – Resource cannot be found
  • 405 – HTTP method not allowed
  • 500 – server error

Response Examples

Success
{
“api_id”: 97ceeb52-58b6-11e1-86da-77300b68f8bb",
“message”: “call fired”,
“request_uuid”: “75b26856-8638-11e0-802c-6d99d509954e”
}


Error

{
“api_id”: “97ceeb52-58b6-11e1-86da-77300b68f8bb”,
“error”: answer_url parameter is missing”,
“request_uuid”: 56hf4856-8638-11e0-802c-65j6gd39954e"
}


Response Attributes

api_id: Identifies the request.
error: Indicates there is an error and provides information regarding the error.
Message: Provides information regarding request.

Endpoint

A Plivo endpoint, also known as SIP endpoint, can be any IP phone, mobile phone, wireless device or PDA, a laptop or desktop PC, that uses the Session Initial Protocol(SIP) to perform communications operations.

Endpoints are used to receive or make calls from SIP phone, webSDK and our mobile SDKs. They support use-cases which involve an agent taking to a client, call centers, etc.

The following actions can be performed using the Endpoint API:

  1. Create an Endpoint
  2. Get Details of All Endpoints
  3. Get Details of a Single Endpoint
  4. Modify an Endpoint
  5. Delete an Endpoint

BaseURI https://api.plivo.com/v1/Account/{auth_id}/Endpoint/


Create an Endpoint

This API lets us create a new endpoint on Plivo.

POST https://api.plivo.com/v1/Account/{auth_id}/endpoint/

Arguments:

username -the username for the endpoint to be created.
Password – the password for your endpoint username.
Alias – alias for this endpoint.
app_id – the app_id of the app that is to be attached to this endpoint.

Response Attributes

username
alias
endpoint_id
sip_contact
sip_expires
sip_registered
sip_uri
sip_user_agent
sub_account

Create Dynamic SIP Endpoints

The ability to create dynamic SIP endpoints is useful in use cases where each call connection needs to be unique and non-replicable. This can previent uninvited callers from calling in on an existing line. When dynamic SIP endpoints are enabled, the following sequence of events will occur:

  1. The caller loads the URL into a browser and clicks “Allow” to enable the computer microphone for the app.
  2. The caller clicks “login” to login automatically with a newly created SIP Endpoint credential. This occurs because the app is sending a HTTP request to the Endpoint API when the “login” button is clicked. Then newly created endpoint credentials is then passed to app and the user is automatically logged in.
  3. Then the caller enters the destination phone number in the text field and clicks 'Call'.
  4. The call status will indicate the stage of the call. Once the call is answered the caller may click “End” to hang up the call.
  5. When the call is hung up and the user clicks “logout” the endpoint is deleted.


SMS Tutorial

  1. Send a Single SMS
  2. Send a Long SMS
  3. Send Multiple(Bulk) SMS
  4. Aplhanumeric Sender ID
  5. Receive an SMS
  6. Reply to an Incoming SMS
  7. Forward an Incoming SMS
  8. Get Details of all Messages
  9. Get Details of a Single Message
  10. Handling SMS Delivery Reports
  11. SMS to Email

Send a Single SMS

To send an outbound Short Message Service(SMS) using Plivo's REST API. This can be used in any web or mobile app that requires communication with end users via SMS text messages including delivery notifications, system alerts, two-factor authentication and even rideshare alerts.

Plivo's Message API supports Unicode UTF-8 encoded texts, which means that we can send messages in any language. The Message API also automatically splits long messages at 160 characters and concatenates them into a single SMS on the receiver's end. Delivery reports are also automatically supported in networks where they are provided by the operator.

To send an SMS we'll need to make an HTTP POST request to the Message API.

POST https://api.plivo.com/v1/Account/{auth_id}/Message

Prerequisites

  1. Sign up for a Plivo trial account.
  2. Check out our Helper Libraries page and install the right helper based on the programming language you want to use.
  3. Buy a Plivo phone number.
  4. Use a web hosting service to host your web app. There are many inexpensive cloud hosting providers that you can user for just a few dollars a month. Follow the instructions of your hosting provider to host web app.

Implementation

  1. Copy the relevant code below into a text file and save it.
  2. Replace your AUTH_ID and your AUTH_TOCKEN with the AUTH ID and AUTH TOCKEN found on your Plivo dashboard.
  3. Add your 'src' phone number. This will show up as your Sender ID. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes.
  4. Add your 'dst' phone numbers. These are the phone numbers you will be sending SMS text messages to. To send multiple messages in the same API request, separate your destination phone numbers with the “<” character. Be sure that all phone numbers include country code, area code and phone number without spaces or dashes.
  5. Edit the 'text' field with your SMS text message.
  6. Make the 'HTTP POST' request to Plivo. If successful, Plivo will queue your SMS deliver it to your recipients at a base rate of 1 message per second.

Send Multiple (Bulk) SMS

An unique feature of Plivo's REST APIs is that you can send bulk(multiple) SMS using a single API request. To send bulk SMS, make an HTTP POST request to the Message API similar to sending a single outbound SMS, with the additional step of adding multiple dst destination numbers by separating each phone number with the “<” character.
POST https://api.plivo.com/v1/Account/{auth_id}/Message/

Prerequisites
  1. Sign up for a free Plivo trial account
  2. Check a Plivo phone number
  3. Buy a Plivo phone number
  4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to hsot your web application.

Implementation

  1. Copy the relevant code below into a text file and save it.
  2. Replace you AUTH_ID and Your AUTH_TOKEN with the AUTH ID and AUTH TOKEN found on your Plivo dashboard.
  3. Add your src phone number. This will show up as your Sender ID. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes.
  4. Add your dst phone numbers. These are the phone numbers you wish to send SMS text messages to. To send messages in bulk, separate your destination phone numbers with the delimiter.
  5. Edit the text field with your SMS text message.
  6. Make the HTTP POST request to Plivo. If successful, Plivo will queue your SMS deliver it to your recipents at a base reate of 1 message per second.

Setup Plivo Phone
  1. Create a new Plivo account.
  2. Created plivo endpoint, which generates a new Plivo sim phone, for all agents that are going to use Plivo phone. As an example, an endpoint driadi generated sip phone: sip:driadi1411022@phone.plivo.com. Plivo WebSDK also requires an endpoint to initialize and login.
  3. Create Plivo application. Plivo application need to be attached to a Plivo number or an endpoint. Every time a call is made to/from a Plivo number/sip endpoint, Plivo sends an HTTP request to the Answer URL defined in an application and expects and XML response back as an instruction on what to do with the call. An example of an HTTP request sent by Plivo looks like: https://plivo.liveops-labs.com/dial_client_plivo.html?To=sip:driadi141102@phone.plivo.com and example of XML response as:

<Response>
<Dial>
<User>sip:driadi121102@liveops.com</user>
</Dial>
</Response>


Plivo WebSDK

Plivo WebSDK is Plivo's Javascript client API that offers phone functionalities through the browser with the help of browser's WebRTC or Flash capabilities. It requires a Plivo endpoint's username and password to initialize. Some of the features that it supports including: answering, rejecting, hanging up, muting, unmuting calls and sending DTMF digits. These features are all wrapped within LiveOps Browser Phone API.


Using Plivo to handle calls through the browser

In addition to Twilio, Phone JS API now extends its capabilities and to support Plivo as another browser phone vendor. When Plivo is used Phone API would receive Plivo specific configuration througth PSAPI Query API call. An example of JSON response that PSAPI returns is shown below:

//Plivo

bowserPhoneConfig” : {
“vendor” : “PLIVO”,
“plivoUsername” : “user”,
“plivoPassword” : “xxx”,
“plivoJsApiUrl” : “s3.amazonaws.com/plivosdk/web/plivo.min.js”
}


plivoJsAPiUrl attribute of browserPhoneConfig indicates Phone API where to load the Plivo WebSDK. The WebSDK provides phone functionalities that Plivo offers through the browser by utilizing browser's WebRTC or Flash capabilities.

Additionally, Phone API uses the values of plivoUsername and plivoPassword to establish connection with Plivo. All existing Phone API features such as answering call, hanging up, rejecting, muting/unmuting, and sending DTMF are also supported by Plivo.

Selecting from multiple work phones easily at any point in time, we are utilizing callcenter feature that allows agent to have multiple work phones. When the feature is enabled, agent can input more than one work phones on callcenter edit agent page and those phone numbers are stored in the re_work_phone table.

We extended PSAPI Query API's logic that retrieves agent work phone to take into account this feature. The new changes enable Query API to choose and return agent work phone and browser phone configuration based on certain conditions. An activity diagram below shows the Query API logic that selects agent work phone.