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:
- 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”,
“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:
- Create an Endpoint
- Get Details of All Endpoints
- Get Details of a Single Endpoint
- Modify an Endpoint
- 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:
- 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.
POST
https://api.plivo.com/v1/Account/{auth_id}/Message
Prerequisites
- Sign up for a Plivo trial account.
- 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.
POST
https://api.plivo.com/v1/Account/{auth_id}/Message/
Prerequisites
- Sign up for a free Plivo trial account
- Check a Plivo phone number
- Buy a Plivo phone number
- 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.
- 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.
- 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 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:
<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.
Thanks for sharing !! Our Bulk SMS API is provided free of charge and supports all major development languages and environments including ASP, PHP, C# etc.
ReplyDelete