Rate this page:

Processing calls in scenarios

This article will help you to make and receive calls in a scenario.

A scenario is the cloud part of your Voximplant application, which is responsible of making and receiving calls, and directing the calls between endpoints. Before you start writing your scenario, create an application first and create a scenario itself.

Contents

Copy URL

How to call a Voximplant user

Copy URL
How to create a user

Follow this guide to learn how to create a Voximplant user.

See Available Roles

To call another Voximplant user, use the callUser method in your scenario. Specify the user you want to call in the username parameter and the callerID you want to show to the callerid parameter. See the example scenario to understand how it works:

Call a Voximplant user

Call a Voximplant user

Call legs

Please note, that if you are making a call via web or mobile SDK, it consists of two call legs: SDK → scenario and scenario → destination. In this case, the SDK → scenario call leg is considered an incoming call in the scenario, so you need to process it via the CallAlerting event as well.

See Available Roles

You can make a peer-to-peer call, which connects two devices directly instead of routing through Voximplant servers. It provides better connection security and audio/video quality. To make a peer-to-peer call, use the callUserDirect method:

Peer-to-peer call

Peer-to-peer call

How to call a phone number

Copy URL
Destination restrictions

Calls that cost more than 20 cents per minute and calls to Africa are restricted for security reasons. To enable them, contact us: support@voximplant.com

See Available Roles

To call a phone number, use the callPSTN method in your scenario. Specify the phone number you want to call to the number parameter, and the caller ID to show to the callerid parameter.

You can use the following numbers as your caller ID:

  1. A real phone number that is rented from Voximplant (you cannot use test numbers)
  2. Any phone number that is verified via an automated call from Voximplant and confirmation code
  3. A phone number from an incoming call to the rented number. You can retrieve it as Caller ID

See the example scenario to understand how it works:

Call a phone number

Call a phone number

Please note, that if you are making a call from a US phone number to a US destination, you additionally need to add the Call.ring() method to the incoming call leg in the scenario.

In this case, the scenario for US to US phone calls looks like this:

US to US phone call

US to US phone call

How to call a SIP address

Copy URL

To call a SIP address, use the callSIP method in your scenario.

UDP/TCP transport

Voximplant uses UDP as the default protocol for SIP calls. If you want to use TCP protocol, specify it in the callSIP method as shown below in the code example

See Available Roles
Call SIP

Call SIP

To enable TLS support for your SIP calls, change the sip: prefix of your address to the sips: prefix or simply specify the TLS transport type. See the code example:

Enable TLS for SIP calls

Enable TLS for SIP calls

Refer to the SIP calls article to learn more about SIP calls in Voximplant.

How to process incoming calls

Copy URL

To process incoming calls, subscribe to the CallAlerting event in the scenario. Use the call.answer method to answer the call, or the call.reject method to decline the call.

You can use the call.startEarlyMedia method to cast early media to the call before it is answered. It allows you to play music or synthesize speech such a voicemail prompt.

Early media limit

A call can be in the early media state for up to 60 seconds.

See Available Roles
Answer a call in a scenario

Answer a call in a scenario

Frequently asked questions

Copy URL

Q: How to redirect a call from a rented number to my mobile phone?
A: You can manage all the calls in the scenario. Receive the call into the platform by subscribing to the CallAlerting event, then use the callPSTN method to call your mobile phone, and unite two calls via the easyProcess method. You can see the scenario example in the How to call a phone number section of this article. Do not forget to create a routing rule for your scenario.

Q: How can I limit the dialing time? For example, if a user does not respond in 20 seconds, call the mobile number instead?
A: You can use the setTimeout method to set the timeout for the dialing time, and then call the phone number using the callPSTN method.

Q: How do I find the reason why a call fails?
A: To find the reason, subscribe to the CallEvents.Failed event and read the e.code property. It contains the error code. You can find the list of error codes in the event description.

Q: Can I share the same variable across different scenarios?
A: If both your scenarios are attached to the same routing rule, they execute in one context and share all the variables between. If you want to share a variable between two different JS sessions, you can use Key-value storage to save the variable.