Tuesday, March 21, 2017

Quick Introduction of Plivo APIs

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.

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:

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:

callback_url:
The URL notified by the API response is available and to which the
response is sent.

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.

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:

The
caller loads the URL into a browser and clicks “Allow” to enable
the computer microphone for the app.

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.

Then
the caller enters the destination phone number in the text field and
clicks 'Call'.

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.

When
the call is hung up and the user clicks “logout” the endpoint is
deleted.

SMS
Tutorial

Send
a Single SMS

Send
a Long SMS

Send
Multiple(Bulk) SMS

Aplhanumeric
Sender ID

Receive
an SMS

Reply
to an Incoming SMS

Forward
an Incoming SMS

Get
Details of all Messages

Get
Details of a Single Message

Handling
SMS Delivery Reports

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.

Check
out our Helper Libraries page and install the right helper based on
the programming language you want to use.

Buy
a Plivo phone number.

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

Copy
the relevant code below into a text file and save it.

Replace
your AUTH_ID and your AUTH_TOCKEN with the AUTH ID and AUTH TOCKEN
found on your Plivo dashboard.

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.

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.

Edit
the 'text' field with your SMS text message.

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.

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

Copy
the relevant code below into a text file and save it.

Replace
you AUTH_ID and Your AUTH_TOKEN with the AUTH ID and AUTH TOKEN
found on your Plivo dashboard.

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.

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

Create
a new Plivo account.

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.

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:

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.