Rate this page:

Rapid callback app development

One of the most popular telephony scenarios is a callback, in this scenario, VoxImplant makes 2 calls (to a phone number, SIP or SDK) and connects them with each other. Scenario execution can be controlled via HTTP API, the 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://manage.voximplant.com/auth/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/auth, 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:

Scenario code

Scenario code

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 the Applications section of the control panel, let's call it callback (full name will be callback.youraccountname.voximplant.com) and within the Scenarios tab of the newly created application we create a new scenario with the following code:

Second scenario code

Second scenario code

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.

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:

StartScenarios HTTP-request

StartScenarios HTTP-request

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.