Integração com a Twilio

A integração da Zadarma e da Twilio permite encaminhar chamadas recebidas dos números virtuais da Zadarma para a sua conta Twilio e processá-las de acordo com as suas configurações atuais da Twilio. Também pode realizar chamadas de saída a partir da Twilio através da sua conta Zadarma, beneficiando das tarifas vantajosas da Zadarma.

1. Configuração das chamadas recebidas

Adicionar um domínio SIP na Twilio.

No seu painel da Twilio, aceda a Twilio Console → Voice → SIP Domains e clique no botão + para adicionar um novo domínio.

Exemplo de configurações do domínio SIP:

• FRIENDLY NAME - nome do domínio, por exemplo, zadarma;
• SIP URI - domínio, nome arbitrário, para conveniência pode usar um número virtual.

Na secção Voice Authentication, adicione, um por um, três IP ACCESS CONTROL LISTS que conterão os endereços IP de confiança da Zadarma, a partir dos quais a Twilio aceitará chamadas recebidas. Pode encontrar esses IPs na secção Configurações → Números Virtuais ou simplesmente copiá-los a partir desta instrução.

• 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

Certifique-se de que todas as três IP ACCESS CONTROL LISTS adicionadas estão selecionadas nas configurações do domínio SIP.

Abaixo, na secção Call Control Configuration, no parâmetro A CALL COMES IN, selecione o que irá gerir as chamadas recebidas. Se já tiver a roteamento de chamadas configurado na Twilio, escolha a sua opção, por exemplo, Studio e o seu Flow (cenário) para chamadas recebidas. Clique em Save para guardar as configurações do seu domínio SIP.

Exemplo de Flow (cenário) para chamadas recebidas▾

{{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}}

Em seguida, nas configurações do SIP Domain, na secção SIP Registration, é necessário ativar a opção de registo, alternando o botão para Enabled.

Abaixo, em CREDENTIAL LISTS, selecione um SIP Endpoint existente que receberá chamadas recebidas através do softphone. Se ainda não tiver um SIP Endpoint, crie um clicando no botão "+".

Adicionar SIP Endpoint▾

A configuração do SIP Domain está concluída. Clique no botão Save.

Encaminhamento de chamadas na Twilio

No ponto anterior, adicionámos um domínio SIP na Twilio que contém o SIP URI necessário para o encaminhamento:

1. Aceda à secção Definições → Números virtuais no Zadarma.
2. Em frente ao seu número, clique no ícone ⚙ (roda dentada).
3. Abra o separador "Servidor externo".
4. Ative a opção "Servidor externo (SIP URI)".

5. No campo que aparece, insira o SIP URI: 15551111111@15551111111.sip.twilio.com

   - onde 15551111111.sip.twilio.com é o seu SIP URI das configurações do domínio SIP na Twilio.

6. Clique em "Guardar".

A configuração das chamadas recebidas está concluída.

2. Configuração de chamadas de saída a partir da Twilio

As chamadas de saída da Twilio podem ser feitas de várias formas. Vamos analisar um exemplo de iniciação de chamada através da Twilio REST API (Calls API).

No exemplo seguinte será demonstrada a criação de uma conferência entre um SIP Endpoint configurado com um softphone e um número externo (chamada através da Zadarma).

No exemplo será utilizado um script em Python. Antes de começar, certifique-se de que o Python e a biblioteca da Twilio estão instalados no seu sistema (www.twilio.com/docs/libraries/reference/twilio-python).

Para autenticar o pedido, é necessário utilizar o Account SID e o Auth Token — pode encontrá-los no painel da conta Twilio, no canto superior esquerdo da página.

Para autorizar a chamada de saída será utilizado o login SIP e a palavra-passe disponíveis na área pessoal da Zadarma.

Para autorizar a chamada de saída será utilizado o número interno da central telefónica e a palavra-passe disponíveis na área pessoal da Zadarma.

Crie um ficheiro call.py com o seguinte conteúdo:

from twilio.rest import Client

# Credenciais Twilio
ACCOUNT_SID = "Account_SID_value"
AUTH_TOKEN = "Auth_Token_value"
TWILIO_NUMBER = "+15559999999"  # Número verificado na Twilio para Caller ID
CONFERENCE_NAME = "MyConferenceRoom"

# Credenciais SIP Zadarma
ZADARMA_SIP_URI = "sip:+525500000777@sip.zadarma.com"  # Destino da chamada via Zadarma
ZADARMA_SIP_USER = "12345"  # Substitua 12345 pelo seu login SIP da Zadarma
ZADARMA_SIP_PASSWORD = "my_sip_password"  # Palavra-passe do login SIP Zadarma

# SIP Endpoint (local)
SIP_ENDPOINT = "sip:11111@15551111111.sip.twilio.com"  # Seu SIP Endpoint onde o softphone está configurado para receber chamadas

# Inicialização do cliente Twilio
client = Client(ACCOUNT_SID, AUTH_TOKEN)

# Função para adicionar participante à conferência
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>"""
    }

    # Adiciona autenticação
    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"Chamada para {to_number} iniciada, SID: {call.sid}")

# Iniciar chamadas
add_to_conference(ZADARMA_SIP_URI, from_number=TWILIO_NUMBER, sip_auth_user=ZADARMA_SIP_USER, sip_auth_password=ZADARMA_SIP_PASSWORD)  # Chamada para número externo via Zadarma
add_to_conference(SIP_ENDPOINT)  # Conectar o SIP Endpoint

print(f"Conferência '{CONFERENCE_NAME}' criada!")

from twilio.rest import Client

# Credenciais da Twilio
ACCOUNT_SID = "Account_SID_value"
AUTH_TOKEN = "Auth_Token_value"
TWILIO_NUMBER = "+15559999999"  # Número confirmado na Twilio para o Caller ID
CONFERENCE_NAME = "MyConferenceRoom"

# Credenciais SIP da Zadarma
ZADARMA_SIP_URI = "sip:+525500000777@pbx.zadarma.com"  # Para onde ligamos via Zadarma
ZADARMA_SIP_USER = "1234-100"  # Substitua 1234-100 pelo seu número interno da central telefónica Zadarma
ZADARMA_SIP_PASSWORD = "my_pbx_password"  # Palavra-passe do número interno da central telefónica Zadarma

# SIP Endpoint (local)
SIP_ENDPOINT = "sip:11111@15551111111.sip.twilio.com"  # O seu SIP Endpoint com softphone configurado para receber chamadas

# Inicialização do cliente Twilio
client = Client(ACCOUNT_SID, AUTH_TOKEN)

# Função para adicionar participante à conferência
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>"""
    }

    # Adicionar autenticação
    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"Chamada para {to_number} iniciada, SID: {call.sid}")

# Início das chamadas
add_to_conference(ZADARMA_SIP_URI, from_number=TWILIO_NUMBER, sip_auth_user=ZADARMA_SIP_USER, sip_auth_password=ZADARMA_SIP_PASSWORD)  # Chamada para número externo via Zadarma
add_to_conference(SIP_ENDPOINT)  # Ligar SIP Endpoint

print(f"Conferência '{CONFERENCE_NAME}' criada!")

Guarde e execute o seu script call.py. Se tudo estiver configurado corretamente, as chamadas serão recebidas no softphone e no número externo a partir do seu login SIP da Zadarma.

Guarde e execute o seu script call.py. Se tudo estiver configurado corretamente, as chamadas serão recebidas no softphone e no número externo a partir do seu número interno da central telefónica virtual da Zadarma.