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. You can find these IP addresses in the section Settings → Virtual phone numbers or simply copy them from this guide.

• FRIENDLY NAME - sipurifr.zadarma.com
• CIDR NETWORK ADDRESS - 185.45.152.216 /32

• FRIENDLY NAME - sipuriny.zadarma.com
• CIDR NETWORK ADDRESS - 185.45.155.33 /32

• FRIENDLY NAME - sipde.zadarma.com
• CIDR NETWORK ADDRESS - 185.45.152.174 /32

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.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.

2. Call Routing in Twilio

n 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 SIP URI: sip: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 Zadarma personal 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}")

# Starting 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"Conference '{CONFERENCE_NAME}' 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.