Processing calls in a scenario
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.
How to call a Voximplant user
Follow this guide to learn how to create a Voximplant user.
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:
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 inbound call in the scenario, so you need to process it via the CallAlerting event as well.
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:
How to call a phone number
Calls that cost more than 20 cents per minute and calls to Africa are restricted for security reasons. To enable them, contact us: email@example.com
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:
- A real phone number that is rented from Voximplant (you cannot use test numbers)
- Any phone number that is verified via an automated call from Voximplant and confirmation code
- A phone number from an inbound call to the rented number. You can retrieve it as Caller ID
See the example scenario to understand how it works:
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 inbound call leg in the scenario.
In this case, the scenario for US to US phone calls looks like this:
How to call a SIP address
To call a SIP address, use the callSIP method in your scenario.
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
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:
Refer to the SIP calls article to learn more about SIP calls in Voximplant.
How to process inbound calls
To process inbound 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.
A call can be in the early media state for up to 60 seconds.
Frequestly asked questions
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.