Get Started with EnableX Voice

Table of Contents

• Pre-Requisites in Portal Configuration
  • Create Project
  • Get API Access
  • Buy Phone Number
  • Configure Phone Number
  • Configure Voice Prompts
• Handle Incoming Voice call with EnableX
  • Inbound Call Setting
• Make an Outbound call with EnableX
• Receiving DTMFs
• Handling Webhook
  • Securing Webhook

Pre-requisites Portal Configuration

We assume that you have registered and signed up with EnableX and have a valid account. If you do not have an account yet, please signup here: https://portal.enablex.io/cpaas/trial-sign-up/

To create your first voice project, you need perform following steps:

• Create Project: Login to Portal and Create Project with Voice Service
• Get API Access Credentials: Get API Credentials to access Voice Rest API Service.
• Configure Voice Service: To use any voice service (Inbound or Outbound), a phone number and prompt is required to be associated with your project.
  • Phone Number:  Can be a shared number or a dedicated number.
  • Voice Prompts: Though EnableX provides TTS (Text To Speech) engine to play prompts using text, the service also facilitates pre-configured, recorded prompts
  • Service: Voice service

Create Project

• Login to the portal and create your first project, Projects Menu -> Create New Project. Click on the “Voice” checkbox
• If you are on the trial period, you will be able to test with shared free numbers.
• Provision one of the available trial shared phone numbers depending on your requirement for inbound or outbound.

See: How to create voice project

Get Access Credentials

• Once you created a project, navigate to My Project > Project Name OR select the desired project from the list of project
• Take note of the App ID and App Key as you will need these to execute your first call

Buy Phone Number

• This is not applicable to trial account, but should you need a dedicated phone number for the application, you can buy a number from EnableX.
• Under Services > Voice
• Click on phone numbers from the left navigation column
• Select the Phone number and the desired direction (Inbound or Outbound) and click to add to your project

See: How to Add Phone number

Configure Phone Number

EnableX service has a pool of available shared or dedicated numbers for users on rent. If the phone number you require is not available, you will need to place an order for a number as in Step 1

The voice services are subscribed and configured by logging in to portal.

• Navigate to Project Dashboard > voice > Configure > Phone Numbers
• Click on Add Phone to Project
• Choose an available (configured) phone number

Configure Voice Prompts

EnableX provides a set of predefined prompts that can be readily used by the subscriber. The user can upload the customized prompts as “.wav” files that can be assigned to play. Each uploaded file is referred to by a unique name, that can be used as a handle during the “Play Prompt command” as mentioned in the section below.

To configure the prompts::

• Navigate to the Configure prompt through Voice -> Voice-Prompts.
• If a new prompt is desired, click on “Add new prompt”
• The system allows us to upload a prompt media file and return a unique identification to play the prompt through the API “Play Prompt” described below.

Handle Incoming Voice Call with EnableX

Inbound Voice Call is processed through pre-configured WebHook URL to accept, play Tones / Voice Prompts and make onward call to Bridge. Inbound Voice Service needs to be configured for your Project through EnableX Portal.

Inbound Call Setting

• A Phone Number to receive Inbound Voice Call
• Voice Prompt (Optional) – If not configured, default prompts would be played
• WebHook to process Inbound Voice Call

If you have chosen a shared incoming call, you will get a PIN displayed along with the assigned phone number. This PIN will be used for receiving a call and once the caller dials the PIN, call will be routed to your application.

Handle Call Events

When an Inbound Call is received at EnableX Voice Service, the event is posted to the configured WebHook URL for further processing. The event would carry a voiceId which is referred by all further API calls, events affecting the same Inbound call.

Details of Events may be found in latest API Reference Documentation.

Navigate to Main Menu > Voice > Phone Numbers

Make Outbound Voice Call with EnableX

Configure or select the outbound phone number.

The selected number will be placed as a CLI (Caller Line Identity). The CLI provided in the Voice API calls by the developer, is validated against the configured number. If the number is not matched, the call will fail.

You can test your Outbound call quickly using OpenAPI page. To try out here: https://openapi.enablex.io/voice/v1/api-docs/#/calls/makeCall

To execute it in the real, click on authenticate and enter following credentials:

Username: APP_ID

Password: APP_Key

Click on “Try it Out”, update the json field “from:” with your configured Outbound Phone number and “to:” with desired destination number and click on “Execute”

An Outbound call be initiated and the progress / status will be shown on the response window

Receiving DTMF

EnableX receives DTMF on the voice call and can dispatch it to the application for further processing.

DTMFs are asynchronous events, and EnableX expect API developers to provide a webhook. The webhook will be invoked by the EnableX platform on Application server in the DTMF event.

The DTMF are conveyed in plain text, but are encrypted by the Webhook security provided by the platform.

Note: DTMF Event is different from “digitcollected” event which comes for the voice menu, and this event will come only after the call is bridged.

Event:

{
     "voice_Id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", // Call_Id
     “channel_id”:” fdgdfg451c0-8f2a-4fe8-b5ef-9addawrttfh”,
     “state”: “dtmfcollected”,
     “digit”: 12345,
     “timestamp": "2017-02-16T10:52:00Z"
}

voice_id	Unique call Identifier
channel_id	Unique channel Id for which the DTMF is received
digit	DTMF value received
state	DTMF collected
timestamp	UTC timestamp at which the event was generated

Handle Webhook

Webhooks are the Asynchronous callbacks posted by the server upon completion of certain request made by the clients. The request could be succesfull or failed. The result of the request is stored in the response body.

Webhook security

Webhooks are the public URLs that are exposed by the developer on application server, these URLs are called by the voice server on the event completion.

Since Webhook URLs are accessible from the public network, it is important that these services are encrypted and secured.

In order to secure the data, EnableX adopts following way to secure Webhook either inbound or outbound.:

• While sending the Webhook event, the server will always encrypt the payload using AppID and also send other headers to support encoding/format types in the webhook event.
• The server will send x-algorithm, x-encoding, x-format header in all webhook request, so that client will decrypt the message with the same values with which server have encrypted the message.
• The client will decrypt the payload using AppID and mentioned headers than the only client can access the webhook message.

To demonstrate the use, please take a look at the enxVoicelib.js file hosted on the GitHub sample projects. Its a nodejs file. It includes a crypto package and calls a decrypt with the API_ID that you have received from EnableX. The following code will be included in your WebHook Event handler.

var crypto = require('crypto'); // Crypto package 
exports.decryptpacket = function(req, callback) {
try {
    if(req.body) {
    var key = crypto.createDecipher(req.headers['x-algoritm'], app_id);
    var decryptedData = key.update(req.body['encrypted_data'], req.headers['x- format'], req.headers['x-encoding']);
    decryptedData += key.final(req.headers['x-encoding']);
    let voice_event = JSON.parse(decryptedData);
    callback(voice_event);
    } else
      callback(null);
    } catch (e) {
      console.log('failed to decrypt the payload ' + e);
      callback(null);
    }
}

Note that all prompt files in the assigned Prompt Group may be used in your API Call

Need Help!

We’re always ready to help you with your implementation as you start building your Video Application. You can also reach out to our support team or check out the sample code available on Github

Stay updated with the latest at EnableX by checking our blogs section!.

To know more about our products & pricing, check out our product and pricing pages or reach out to our Sales team.