Integration with Twilio

The integration of Zadarma and Twilio allows incoming calls from Zadarma virtual numbers to be directed to your Twilio account and processed according to your current Twilio settings. You can also make outgoing calls from Twilio through your Zadarma account at affordable Zadarma rates.

1. Incoming call setup

Adding a SIP domain in Twilio.

In your Twilio account, go to the Twilio Console → Voice → SIP Domains and click the + button to add a new domain.

Example of SIP domain settings:

• FRIENDLY NAME - domain name, for example, zadarma;
• SIP URI - domain, any name, for convenience you can use a virtual number.

In the Voice Authentication section, add the three IP ACCESS CONTROL LISTS one by one, which will contain the trusted IP addresses from Zadarma that Twilio will accept incoming calls from.

Make sure that all three added IP ACCESS CONTROL LISTS are selected in the SIP domain settings.

Below, in the Call Control Configuration section, in the A CALL COMES IN parameter, select what will manage incoming calls. If you have already set up incoming call routing in Twilio, choose your option, for example, Studio and your Flow (scenario) for incoming calls. Click Save to save the settings of your SIP domain.

Example of a Flow (scenario) for incoming calls▾

{{contact.channel.address | replace: "sip:", "" }}

{{flow.variables.step1_caller_id | replace: "@sip.zadarma.com", "" }}

{{flow.variables.step1_caller_id | replace: "@pbx.zadarma.com", "" }}

{{flow.variables.clean_caller_id}}

Next, in the SIP Domain settings, in the SIP Registration section, you need to enable the registration option by toggling the switch to Enabled.

Below, in CREDENTIAL LISTS, select the existing SIP Endpoint that will receive incoming calls using the softphone. If you don’t have a SIP Endpoint yet, create one by clicking the "+" button.

Adding SIP Endpoint▾

The SIP domain setup is complete. Click the Save button.

Call Routing in Twilio

In the previous step, we added a SIP domain in Twilio, which contains the required SIP URI for routing:

1. In Zadarma, open the section Settings → Virtual phone numbers.
2. Next to your number, click on the ⚙ (gear) icon.
3. Open the "External Server" tab.
4. Enable the "External Server" (SIP URI)" option.

5. In the field that appears, enter 15551111111@15551111111.sip.twilio.com

   - where 15551111111.sip.twilio.com – is your SIP URI from the SIP Domain settings in Twilio.

6. Click "Save".

1. In Zadarma, open the section My PBX → Extensions.
2. In the extension settings, next to the parameter "Call forwarding and voicemail" click "Enable".
3. Select call forwarding condition, for example "Always active".
4. In the parameter "Call forwarding for"select "External server (SIP URI)".

5. In the field that appears, enter 15551111111@15551111111.sip.twilio.com

   - where 15551111111.sip.twilio.com – is your SIP URI from the SIP Domain settings in Twilio.

6. Click "Save".

The setup for incoming calls is complete.

2. Outgoing Call Setup from Twilio

Outgoing Calls from Twilio can be made in several ways. Let's consider an example of initiating a call using the Twilio REST API (Calls API).

In the next example, a conference will be created between a SIP Endpoint with a configured softphone and an external number (a call via Zadarma).

The example will use a Python script, so before starting, make sure that Python and the Twilio library (www.twilio.com/docs/libraries/reference/twilio-python) are installed on your system.

To authenticate the request, you need to use the Account SID and Auth Token. You can find them in Twilio in the Account Dashboard in the top left corner of the page.

For outgoing call authorization, a SIP login and password will be used from your personal Zadarma account.

For outgoing call authorization, a PBX extension and its password will be used from your personal Zadarma account.

Create a script call.py with the following content:

from twilio.rest import Client

# Twilio credentials
ACCOUNT_SID = "Account_SID_value"
AUTH_TOKEN = "Auth_Token_value"
TWILIO_NUMBER = "+15559999999"  # A verified number in Twilio for Caller ID
CONFERENCE_NAME = "MyConferenceRoom"

# Zadarma SIP credentials
ZADARMA_SIP_URI = "sip:+525500000777@sip.zadarma.com"  # Where the call is being made through Zadarma
ZADARMA_SIP_USER = "12345"  # instead of 12345 should be your SIP login from Zadarma
ZADARMA_SIP_PASSWORD = "my_sip_password"  # Password for the SIP login from Zadarma

# SIP Endpoint (local)
SIP_ENDPOINT = "sip:11111@15551111111.sip.twilio.com"  # Your SIP Endpoint on which the softphone is set up to receive calls

# Initializing Twilio client
client = Client(ACCOUNT_SID, AUTH_TOKEN)

# Function for adding a participant to the conference
def add_to_conference(to_number, from_number=None, sip_auth_user=None, sip_auth_password=None):
    call_params = {
        "to": to_number,
        "from_": from_number if from_number else TWILIO_NUMBER,
        "twiml": f"""<Response>
                        <Dial>
                            <Conference>{CONFERENCE_NAME}</Conference>
                        </Dial>
                     </Response>"""
    }

    # Adding authentication
    if sip_auth_user and sip_auth_password:
        call_params["sip_auth_username"] = sip_auth_user
        call_params["sip_auth_password"] = sip_auth_password

    call = client.calls.create(**call_params)
    print(f"Call to {to_number} initiated, SID: {call.sid}")

# Initiating calls
add_to_conference(ZADARMA_SIP_URI, from_number=TWILIO_NUMBER, sip_auth_user=ZADARMA_SIP_USER, sip_auth_password=ZADARMA_SIP_PASSWORD)  # Call to an external number through Zadarma
add_to_conference(SIP_ENDPOINT)  # Connecting the SIP Endpoint

print(f"The conference '{CONFERENCE_NAME}' has been created!")

from twilio.rest import Client

# Twilio credentials
ACCOUNT_SID = "Account_SID_value"
AUTH_TOKEN = "Auth_Token_value"
TWILIO_NUMBER = "+15559999999"  # A verified number in Twilio for Caller ID
CONFERENCE_NAME = "MyConferenceRoom"

# Zadarma SIP credentials
ZADARMA_SIP_URI = "sip:+525500000777@pbx.zadarma.com"  # Where the call is being made through Zadarma
ZADARMA_SIP_USER = "1234-100"  # insteda of 1234-100 should be your Zadarma PBX extension
ZADARMA_SIP_PASSWORD = "my_pbx_password"  # Zadarma PBX extension password
# SIP Endpoint (local)
SIP_ENDPOINT = "sip:11111@15551111111.sip.twilio.com"  # Your SIP Endpoint on which the softphone is set up to receive calls

# Initializing Twilio client
client = Client(ACCOUNT_SID, AUTH_TOKEN)

# Function for adding a participant to the conference
def add_to_conference(to_number, from_number=None, sip_auth_user=None, sip_auth_password=None):
    call_params = {
        "to": to_number,
        "from_": from_number if from_number else TWILIO_NUMBER,
        "twiml": f"""<Response>
                        <Dial>
                            <Conference>{CONFERENCE_NAME}</Conference>
                        </Dial>
                     </Response>"""
    }

    # Adding authentication
    if sip_auth_user and sip_auth_password:
        call_params["sip_auth_username"] = sip_auth_user
        call_params["sip_auth_password"] = sip_auth_password

    call = client.calls.create(**call_params)
    print(f"Вызов на {to_number} начат, SID: {call.sid}")

# Initiating calls
add_to_conference(ZADARMA_SIP_URI, from_number=TWILIO_NUMBER, sip_auth_user=ZADARMA_SIP_USER, sip_auth_password=ZADARMA_SIP_PASSWORD)  # Call to an external number through Zadarma
add_to_conference(SIP_ENDPOINT)  # Connecting the SIP Endpoint

print(f"The conference '{CONFERENCE_NAME}' has been created!")

Save and run your script call.py. If everything is set up correctly, calls will be received in the softphone and on the external number from your SIP login on Zadarma.

Save and run your script call.py. If everything is set up correctly, calls will be received in the softphone and on the external number from your Zadarma virtual PBX extension.