SIP calls and registrations
This guide provides information on how to manage incoming and outgoing SIP calls.
Contents
How to call a 3rd-party PBX
In the scenario, use the callSIP method to initiate a call to a SIP address. Refer to the scenario example for a detailed understanding of its functionality.
Voximplant uses UDP as the default protocol for SIP calls. If you want to use the 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:
If you want to make sip calls from web or mobile SDKs, specify the SIP address in the first parameter of the call() method in your application. You can retrieve this value in the e.destination property in your scenario.
How to receive calls from a 3rd-party PBX
To receive calls in a Voximplant application, you need to whitelist your PBX domain's IP address in the control panel.
Whitelist the IP address, not the domain name. For example, if your 3rd party PBX is Linphone, whitelist 79.104.38.102 instead of sip.linphone.org
After that, you can call your Voximplant application from the whitelisted PBX via one of the following address formats:
destination@application.account.voximplant.com
app_id#account_id#destination@sip.voximplant.com
After you start a call in your SIP PBX, you receive this call in the specified application. Create a proper routing rule to match the destination field of the address.
The destination field of the address is processed by your scenario and can be retrieved from the e.destination property of the incoming call object.
You can specify a username in this field to refer to a particular user, or you can enter any string value. In either case, you can retrieve the value from the e.destination property and use it in your scenario logic as needed.
Refer to the voice calls guide or video calls guide to learn how to process incoming audio or video calls in the application.
You cannot accept incoming SIP calls from the voximplant.com domain. Learn how to call a Voximplant user via the platform.
How to use 3rd party SIP software with Voximplant
To authorize a 3rd party SIP application (such as Linphone or Jitsi), you need to create an application, and create a user in the control panel first.
Then open your 3rd party SIP software and add a new SIP account. Use your user as the account username, and the domain part of your application as the SIP domain.
You can specify UDP/TCP transport, or specify TLS transport to secure your connection.
After you sign in, you can make audio and video calls from your 3rd party SIP application.
How to work with SIP registrations
SIP registration is a feature that enables Voximplant to function as a third-party PBX softphone. This feature facilitates the easy forwarding of calls from your PBX to Voximplant without the need for intricate trunk configuration.
Create a SIP registration
You can create and manage SIP registrations via the control panel or Management API.
During creation, you need to specify at least the following parameters:
proxy – your provider's SIP proxy address. You can add a port number if it is different from the standard 5060 port, e.g. sip.provider.org. By default, Voximplant uses the UDP transport. If you need to use TCP, just add ;transport=tcp to the proxy address. So in the most complicated case, this field contains something like sip.provider.org:5090;transport=tcp
username – the user name, e.g. user12302
password – the password that was given to you by your provider
Also, some providers require you to specify outgoing proxy and auth user parameters, but most of the providers do not need that.
Please note that you pay for SIP registrations monthly according to our price list. So if you create a SIP registration and delete it immediately, your account is charged for the SIP registration monthly fee.
SIP registration statuses
In the control panel, you can view the status of each registration. Currently, there are three possible statuses:
- Successful – the registration was performed successfully
- In progress – Voximplant is about to initiate the registration that has been recently created or modified. Usually, the provisioning process takes up to 2 minutes
- Failed – Voximplant attempted to perform SIP registration but it was not successful. Usually, it is a result of some SIP error returned by the SIP proxy. You can obtain the status code and message in the information tooltip in the control panel.
When a SIP registration status changes from Successful to Failed and vice versa, you get an email notification to the contact email addresses and the HTTP callback invokes. You can learn more about HTTP callbacks in this article.
How to make calls with SIP registration
To make a call with a SIP registration, you need to pass the regId parameter to the VoxEngine.callSIP function. You can find the registration id in the SIP registration list in the control panel, or in the GetSipRegistrations and CreateSipRegistration functions' response. Usually, you need to specify only the username/number of the called party.
Configure a SIP registration
To process incoming calls to Voximplant, you need to attach a SIP registration to an application (in the SIP Registrations section of an application menu) and select the desired routing rule that handles the calls. Please note that you do not need to configure the rule pattern in this case — the rule works for all the calls to this SIP registration.
Frequently asked questions
Q: Can I create a SIP account on the Voximplant platform?
A: Voximplant users can act as SIP accounts. Use the username as the user part of the SIP address, and the application address as a domain part of your SIP address. For example: user@application.account.voximplant.com