Rapid callback app development

Rapid callback app development


One of the most popular telephony scenarios is a callback, in this scenario VoxImplant makes 2 calls (to phone number, SIP or SDK) and connects them with each other. Scenario execution can be controlled via HTTP API, developer can invoke functions remotely or make HTTP requests right from the scenario itself. Check this step-by-step tutorial to build your callback app.

First of all, you need to get a VoxImplant developer account. It's free, just visit https://voximplant.com/sign-up/ and submit the registration form. After you get the account and activate it you can login into VoxImplant control panel at https://manage.voximplant.com/#login , it provides convenient web interface that lets developers control apps and users, write and debug scenarios, check call history and make payments, get API access info, etc. After you log in you will see the following interface:

For our callback application we will need to create VoxImplant application, scenario and application rule to connect our scenario to the application. In the end we will make HTTP-request to start the session (scenario). After the HTTP-request, if everything was done right, we will receive media_session_access_url, which will let control the session remotely using RPC mechanism. For example, if we need to stop the scenario execution we can write the following code in our VoxEngine scenario:

VoxEngine.addEventListener(AppEvents.HttpRequest, handleHttpRequest);
function handleHttpRequest(e) { VoxEngine.terminate(); }

If you have this code in your scenario then after HTTP-request to media_session_access_url the session will be terminated. But let's return to our callback application. First, create the app in Applications section of the control panel, let's call it callback (full name will be callback.youraccountname.voximplant.com) and in the Scenarios section we create a new scenario with the following code:

let call1, call2, data;
const callerId = '+1234567890'; // Rented or verified phone number

VoxEngine.addEventListener(AppEvents.Started, handleScenarioStart);

function handleScenarioStart(e) {
  // Data can be passed to scenario using customData
  // script_custom_data param in StartScenarios HTTP request will be available to scenario as customData
  // in this scenario we will pass number1:number2 string via script_custom_data
  data = VoxEngine.customData();
  data = data.split(':');
  // start scenario - calling number 1
  call1 = VoxEngine.callPSTN(data[0], callerId);
  // assign event handlers
  call1.addEventListener(CallEvents.Connected, handleCall1Connected);
  call1.addEventListener(CallEvents.Failed, function (e) {
  call1.addEventListener(CallEvents.Disconnected, function (e) {

function handleCall1Connected(e) {
  // first call connected successfully, play message
  call1.say('Hi, this call is from callback service, please wait', { "language": VoiceList.Amazon.en_US_Joanna });
  call1.addEventListener(CallEvents.PlaybackFinished, function (e1) {
    // after message played - calling number 2
    call2 = VoxEngine.callPSTN(data[1], callerId);
    // assign event handlers
    call2.addEventListener(CallEvents.Connected, handleCall2Connected);
    call2.addEventListener(CallEvents.Failed, function (e2) {
      call1.say('Unfortunately, the connection can\'t be established', { "language": VoiceList.Amazon.en_US_Joanna });
      call1.addEventListener(CallEvents.PlaybackFinished, function (e3) {
    call2.addEventListener(CallEvents.Disconnected, function (e2) {

function handleCall2Connected(e) {
  // connect two calls with each other - media 
  VoxEngine.sendMediaBetween(call1, call2);
  // and signalling
  VoxEngine.easyProcess(call1, call2);

This scenario makes calls to phone numbers we will pass using script_custom_data param of the StartScenarios in the following format - phonenumber1:phonenumber2. First, scenario calls phonenumber1 and then plays a message using Text-to-speech, then it calls phonenumber2 and connects two calls with each other. We don't handle some events, like call failure, for example, if we can't establish connection with phonenumber1 we just terminate the session (stop scenario execution). If we add some additional logic we can notify outer world about the issue, let's change

call1.addEventListener(CallEvents.Failed, function(e) { VoxEngine.terminate(); });


call1.addEventListener(CallEvents.Failed, handleCall1Failed);

and then add handleCall1Failed description:

function handleCall1Failed(e) { // failure reason available here
  const code = e.code;
  const reason = e.reason;
  // we can send it to outer world using HTTP request
    .then(response => {
    // HTTP request info - 
    // response.code, 
      // response.text, 
      // response.data, 
      // response.headers
    // terminate session

This example shows simple HTTP-request (GET method). HTTP-request parameters (method, headers, etc.) can be customized using HttpRequestOptions. After our scenario is ready we need to save it using some name, let's say Callback, and go to Applications section of the Control Panel, where we can connect scenario to the application using Rule and get Rule id - it will be used for HTTP-request to launch the scenario (StartScenarios): 1. Start editing the application 2. Open the Routing tab 3. Click the New rule button 4. Specify the name for a rule (let's say Callback) and choose the Callback scenario from the Available Scenarios drop-down list.

Created rule will appear in the Rules list and its ID should be visible now - we will need this ID for our HTTP-request.

5. Save the app by clicking the Save button in General tab. That's it! Now we can make StartScenarios HTTP-request (we will need some additional params for it, including the api_key you can get in API Access section of the Control Panel):


Just replace the params (account_id, api_key, rule_id, number1 and number2) with your data and, if everything was done correctly, you will see the result of the request:

  "result": 1,
  "media_session_access_url": "http:\/\/\/request?id=93e41c6e20811b9b.1380201554.0@" 

This media_session_access_url can be used for communication with the session (RPC). You can always check logs in Calls section of the Control Panel (arrow in the top right corner) or use our cloud debugger. The text of the scenario is available at our GitHub account: VoxImplant Callback Scenario at GitHub

B6A24216-9891-45D1-9D1D-E7359CEB8282 Created with sketchtool.


Add your comment

Please complete this field.


Sign up for a free Voximplant developer account or talk to our experts