Table of Contents

Make First Voice 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.

On Signup, you get a credit of $2 to use and evaluate the Video, Text, and Voice services. You will be able to make 10 calls of 30 sec durations to the select countries or make 10 SMS text to 10 destination countries using the free credit.

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).

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