Apps, Scenarios, Rules and Users

JavaScript cloud scenarios

The Voximplant architecture is based on scenarios, that is, a modern ES2017 JavaScript code created by a customer and executed automatically upon receiving an incoming call or the backend request. This code has access to standard JavaScript features alongside with VoxEngine API. That API allows to control voice and video calls in real-time from the running JavaScript code and use Voximplant built-in features like recording, text-to-speech and more. To create a scenario, you need to be registered at the Voximplant control panel:

During the registration, you will need to define a unique username (also known as the "account name") and specify an email to receive platform notifications. You can change notifications or add more emails later using the "Contacts" control panel section. After registering and logging in, open the control panel, select Scenarios on the top menu, and click Create scenario:


This will open the New scenario editor window where you can enter the scenario name and the source code. If needed, you can rename the scenario or change the source code later, or upload them automatically via the HTTP API. At this step, name your scenario ‘callcenter’ and enter the following source code:

VoxEngine.addEventListener(AppEvents.CallAlerting, e => {
 // this code is executed in the cloud on every incoming call;"hello from the cloud", Language.US_ENGLISH_FEMALE);

The Voximplant cloud platform is fully asynchronous: there are no waiting or blocking operations. All method calls start corresponding operations and return immediately. If you place two "say" methods one after another, the second playback will immediately replace the first one.

You subscribe to events, schedule actions, and your code is called when some event happens. The code starts with the addEventListener method of a global VoxEngine object. The method allows subscribing to global events, and here we subscribe to CallAlerting so that the handler function will be called in the cloud right after an incoming voice or video call arrives.

After the call arrives, we have full control over it via JavaScript. We can inspect the caller’s phone number, answer or reject the call, deliver some audio to the caller and so on. In this example, we are calling the startEarlyMedia method of the call object to inform the caller’s phone service provider that we want to send some audio to the caller. Then we call the say method to synthesize voice from text. Note that we need to answer a call if we want to send any audio into it.


"Application" groups multiple scenarios under a single unique name. This name is then used as an "access point" for connecting phone numbers, targeting SIP calls, attaching platform features like "call queues" and so on. To create an application, click Applications on the top menu and then click Create application.


This will open the New application editor window where you should enter the application name and confirm by clicking Create. The window will change into the application editor where you can associate your JavaScript scenario with the incoming call.


"Rules" further groups scenarios within an application and provides a way to start one or more scenarios via HTTP API or via an incoming phone call. Any incoming call has two numbers associated with it: "caller id", which is the number of a person making the call, and "dialed number", which is a number being called. On an incoming call, Voximplant will execute scenario(s) associated with the first rule whose "pattern" regular expression matches "dialed number". If multiple scenarios are assigned to one rule, they are executed one after another in a single context, allowing to re-use common JavaScript code. To create a rule, select an application, click the Rules tab and then click Add rule.


This will open the new rule editor window where you can enter the rule name and select JavaScript scenarios. For quickstart examples, name the rule ‘incoming’ and click the ‘callcenter’ scenario created previously, so that the rule widget switches from ‘available’ to ‘assigned’. Click Add to confirm the rule creation.


User credentials are used to accept and initiate calls with non-PSTN endpoints: Web pages with our Web SDK, Android and iOS devices with our mobile SDKs and SIP-enabled software or hardware devices. Users can be created programmatically via HTTP API or via control panel. Before usage, user credentials should be associated with one or more applications.

Next: Receiving and handling calls in the cloud