Table of Contents

First voice outbound call with EnableX

You can do your first Call with EnableX without writing a single line of code.

Sign-Up with EnableX

To sign up for a trial account, you would need a valid e-mail Id and a phone number to receive OTP for the verification.

Create your Project

Following are the steps to make your first voice project:

  • Register on the portal with your valid e-mail Id and Phone number for receiving an OTP.
  • Once you received App_ID and App_Key you will be able to login to the portal and create your first project From: 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 the trial shared phone numbers.

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

Choose Phone Number

  • Under Services > Voice
  • Click on phone numbers from the left navigation column
  • Select the Outgoing Phone number and add to your project

See: How to Add Phone number

Once the trial shared numbers are added you will be able to make your first voice call. Please take a note of your APP_ID and APP_KEY available on your dashboard as you will need these credentials to make a voice call.

Try a Call with just a curl command!

The primary way that you’ll interact with the EnableX platform is via the public API. To place an outbound call, you make a POST request to https://api.enablex.io/voice/v1/calls.

In the JSON block, event_URL is the URL of your application server where EnableX voice server tries to call. Since we are just using a Curl for now, we can avoid, since we can not handle the incoming requests, or say may be we are not interested in the error or success.

If your phone numbers (Called number to be configured and a valid destination number) are correct, you should be able to get the destination/called number phone !!

curl -X POST \
-H "Authorization: Basic $(echo -ne  APP_ID:APP_KEY  | base64 --wrap 0)" \
-H "content-type: application/json" -d ' \
{
	"name":"dial__out",
	"owner_ref":"xyz",
	"to":"xxxxxxxxx",	// Destination Number
	"from":"yyyyyyyyy",	// Caller Id 
	"action_on_connect":{
		 "play":{
			 "text":"Hi, This is a sample Text To Speech Message.",
			 "voice":"Female",
			 "language":"en-US"
		}
	},
	"event_url":"https://yourserver/callhandler" //Your WebHook
}' \
"https://api.enablex.io/voice/v1/calls"

Note that for Outbound Calls, you must use a configured shared phone number or a dedicated phone number with your project while calling respective API. The phone number used in API call will be validated against the configured phone number, failing which the call will fail. The validated shared phone is referred to as the CLI (Caller Line Identity).

Handle Incoming Voice Call with EnableX

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

Configure

  • 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, event is posted to the configured WebHook URL for further processing. The event would carry a voiceId which is referred by all API calls, events affecting the same Inbound call.

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

Pre-requisites Portal Configuration

To configure a voice service, the application needs the following resources to be configured:

  • Phone Number: A shared number of a dedicated number.
  • Voice Prompts: Though EnableX provides TTS (Text To Speech) engine to play prompts using text, service also facilitates pre-configured, recorded prompts
  • Service: Voice service

Step 1: Get the phone number

Navigate to Main Menu > Voice > Phone Numbers

For Outbound, 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.

Step 2: Configure Prompts

EnableX provides a set of predefined prompts that can be readily used by the subscriber. The user can upload the customized prompts as an “mp3”, “.wav” files that can be assigned to play. Each uploaded file is referred 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.

Step 3: Assign number and prompt to project

To use any voice service (Inbound or Outbound), a phone number and prompt is required to be associated with your project. 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 Dashboard > Projects > Project Dashboards.
  • Create a new project or select an existing project that needs to have voice services
  • To use a service, you need to add a phone number to project:
  • Navigate to Project Dashboard > voice > Configure > Phone Numbers
  • Click on Add Phone to Project
  • Choose an available (configured) phone number
  • Navigate to Project Dashboard > voice > Configure > Prompt Setting
  • Choose the Prompts from the available list

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);
    }
}

Try Sample Code from GitHub: Voice Outbound Call

Clone from Github

EnableX provides sample code you can download from Github

git clone https://github.com/EnableX/voicemessaging.git
cd voicemessaing/examples
npm install

Configure the Application

Edit the config.js file.

config.from		= '199999999';		// CLI. Number opted/purchased from EnableX
config.to		= '188888888';		// Destination Number to call
config.prompt_name	= 'dir-welcome';
config.text		= 'My TTS message';	// Your Text-to-Speech prompt

Execute to call

node outgoing_playtext.js

EnableX sample code will use Ngrok tunneling for webhook URL. This is created automatically.

Server running on port 3000
ngrok tunnel set up: https://c1d0ab7dccce.ngrok.io
Making an outbound call to 65XXXXXXXX result: {"voice_id":"e44090ab-0b3b-44d6-91d7-117b7ddf7bd5","state":"initiated","timestamp":"2020-06-03T02:27:44.941Z"}
Received enx voice event {"voice_id":"e44090ab-0b3b-44d6-91d7-117b7ddf7bd5","from":"60YYYYYYYYYY","to":"65XXXXXXXX","play_id":"9da44abd-6d1e-4e61-a8da-306bb1c35866","playstate":"initiated"}
Received enx voice event {"voice_id":"e44090ab-0b3b-44d6-91d7-117b7ddf7bd5","from":"60YYYYYYYYYY","timestamp":"2020-06-03T02:27:54.768Z","channel_id":"8587cfc1-1674-45c5-a5fb-e340f1c2c039","state":"connected"}
Call established
Received enx voice event {"voice_id":"e44090ab-0b3b-44d6-91d7-117b7ddf7bd5","to":"65XXXXXXXX","play_id":"9da44abd-6d1e-4e61-a8da-306bb1c35866","playstate":"playfinished","timestamp":"2020-06-03T02:28:00.029Z"}
Received enx voice event {"voice_id":"e44090ab-0b3b-44d6-91d7-117b7ddf7bd5","to":"65XXXXXXXX","play_id":"88c24a0b-8bf6-4acd-87e8-3317b26e095d","playstate":"playfinished","timestamp":"2020-06-03T02:28:08.184Z","prompt_ref":"1"}
Received play finished from the voice server
Disconnecting the call e44090ab-0b3b-44d6-91d7-117b7ddf7bd5
Received enx voice event {"voice_id":"e44090ab-0b3b-44d6-91d7-117b7ddf7bd5","from":"60YYYYYYYYYY","timestamp":"2020-06-03T02:28:09.027Z","state":"disconnected","channel_id":"8587cfc1-1674-45c5-a5fb-e340f1c2c039"}
Call is disconnected

When you run the script above, the destination phone number will ring. Once the call is connected, it will played the sample Text-to-Speech that is specified in the config.js file

Manage your Voice Prompts

EnableX provides a set of predefined Voice Prompts used by all Customer’s projects by default. However, you may upload your own Customized Voice Projects in .mp3 format and may be used with one or more projects of yours. Each uploaded Voice Prompt File us assigned with a Unique Number to be be used as a handle with Play Prompt Command (Explained in API Reference).

See: How to Manage voice prompts

Upload Voice Prompts

Follow the given steps to upload new customized Voice Prompt File

  • Login for EnableX Portal
  • Navigate: (Main Menu) Voice / Preferences / Voice Prompts -> (Button) Add New Prompt File

Add Voice Prompt File Form: The following form you get to upload voice prompt file.

Here are the explanation of different fields in the form:

  • Prompt Group: This is to organize your Voice Prompt files in different group. Select one if you already defined a group, or add a new group name.
  • Prompt Title: A title/name given to the prompt file
  • Upload Voice File: To choose the .mp3 file to upload

Configure Voice Prompt with Project

To use your customized Voice Prompts in your Project, you need to configure them with your Project. Follow the steps given below:

  • Login to EnableX Portal
  • Navigate: (Main Menu) Projects / My Projects
  • Click a Project that includes Voice Service to go to the Project Dashboard. Alternately, you may like to create a Project with Voice Service and then go to its Dashboard.
  • Navigate: (Project Dashboard) Voice (Left Bar) – You reach Voice Service Page
  • Navigate: (Voice Service Page) Prompt Settings (Left Bar) – You reach a form to assign a Prompt Group to the Project.

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