Creating a sip-breakout product

Prerequisites

1. An OAuth 2.0 client
2. A client access token

Overview

In this guide, we will demonstrate how to create a product based on the Sipbreakout API. The primary function of this product is to record voice calls using FreeSWITCHopen in new window a free and open-source telephony software for real-time communications. When setup, this product will intercept all phone calls to and from the registered number. All phone calls will be recorded and stored as wav-file, but for this example content will not be altered. However, the same principles can be used to develop more advanced products, such as sending audio streams to third-party APIs for speech-to-text conversion and translation.

Please note that this demo product is just for demonstrative purposes and is not intended for production use, as it takes some shortcuts. It's sole purpose is to demonstrate how to use the Sipbreakout API.

Here is how the flow looks like:

Create B2BUA for intercepting calls

You can use any SIP B2BUAopen in new window, but in this example we'll focus on FreeSWITCH.

Before launching the FreeSWITCH you should make sure that:

• You have a valid TLS certificate for the domain you are going to use. We recommend using Let's Encryptopen in new window for that.
• You have configured your firewall to allow sending/receiving TCP/SIP traffic from our SBCs and sending/receiving UDP/RTP traffic from our media gateways:

Traffic	IPs	Ports
TCP/SIP	54.72.237.8/32, 52.209.193.98/32	5060, 5061, 5080, 5081
UDP/RTP	54.195.111.121/32, 34.254.133.110/32	10000-50000

We'll be using minimized official FreeSwitch docker container, which can be found hereopen in new window.

Now run the following command to launch FreeSWITCH:

docker run \
 --net=host \
 --rm -p YOUR_HOST_MACHINE_INTERNET_IFACE_IP:5060:5060 \
 --name freeswitch \
 -v /etc/freeswitch/:/etc/freeswitch \
 -v /tmp:/var/lib/freeswitch/recordings \
 safarov/freeswitch

Please note the volume mountings. The recorded calls will be stored in /tmp directory on the host machine, which is not ideal, but you can change it to any other directory you want. The same applies to the configuration directory that ends up in the /etc/freeswitch directory on the host machine.

It's enough to start the FreeSWITCH once, so that the config files are generated. After that you can stop it and edit the config files the way described below.

• Certificates

Move your Let's Encrypt certificate and key PEM files in agent.pem

cat fscrt.pem fskey.pem > /etc/freeswitch/tls/agent.pem
chmod 644 /etc/freeswitch/tls/agent.pem

Now edit /etc/freeswitch/sip_profiles/internal.xml and add the following lines:

<param name="tls-cert-dir" value="/etc/freeswitch/tls"/>

• External sip profile

In /etc/freeswitch/sip_profiles/external.xml add the following:

<gateways>
    <X-PRE-PROCESS cmd="include" data="external/*.xml"/>
    <gateway name="wg2_gateway">
      <param name="register" value="false"/>
      <param name="proxy" value="54.72.237.8"/>
      <param name="proxy" value="52.209.193.98"/>
      <param name="register-transport" value="tls"/> on the gw
    </gateway>
</gateways>

• ACL

In /etc/freeswitch/autoload_configs/acl.conf.xml add the following:

<list name="domains" default="deny">
  <!-- domain= is special it scans the domain from the directory to build the ACL -->
  <node type="allow" domain="${domain}"/>
  <!-- use cidr= if you wish to allow ip ranges to this domains acl. -->
  <node type="allow" cidr="52.209.193.98/32"/>
  <node type="allow" cidr="54.72.237.8/32"/>
</list>

• Dialplan

In /etc/freeswitch/dialplan/public/00_inbound_did.xml add the following:

<extension name="public_did_wg2">
    <condition field="destination_number" expression="^\+.*$">
      <!--
          If you're hosting multiple domains you will want to set the
          target_domain on these calls so they hit the proper domain after you
          transfer the caller into the default context.

          ${domain} is the default domain set from vars.xml but you can set it
          to any domain you have setup in your user directory.

      -->

      <action application="export" data="execute_on_answer=record_session ${recordings_dir}/${strftime(%Y%m%d%H%M%S)}_${sip_from_user}_${sip_to_user}.wav"/>
      <action application="bridge" data="{ignore_early_media=ring_ready,media_webrtc=true,sip_invite_from_uri=sip:${sip_from_user}@yourdomain.com;user=phone}sofia/gateway/wg2_gateway/${sip_to_user}@sbc.dub.prod.wgtwo.com;transport=tls"/>

    </condition>
</extension>

• FreeSWITCH vars

In /etc/freeswitch/vars.xml add the following:

<X-PRE-PROCESS cmd="set" data="internal_ssl_enable=true"/>
<X-PRE-PROCESS cmd="set" data="external_ssl_enable=true"/>
<X-PRE-PROCESS cmd="set" data="global_codec_prefs=PCMU,PCMA"/>
<X-PRE-PROCESS cmd="set" data="outbound_codec_prefs=PCMU,PCMA"/>

Testing the product

Now it's time to start the configured FreeSWITCH. Run the following command again:

docker run \
 --net=host \
 --rm -p YOUR_HOST_MACHINE_INTERNET_IFACE_IP:5060:5060 \
 --name freeswitch \
 -v /etc/freeswitch/:/etc/freeswitch \
 -v /tmp:/var/lib/freeswitch/recordings \
 safarov/freeswitch

Now set up a Loop registration by following the instructions in Sipbreakout API.

It's important to choose the right sipUri so we can loop the call back to you. E.g. you could use the following as an example.

Example code

The examples below demonstrate how to consume this API.

TIP

You can test our APIs without authorization by targetting sandbox.api.wgtwo.com instead of api.wgtwo.com and removing any authorization from the request/code sample.

Download proto definitions

curl -sL 'https://github.com/working-group-two/wgtwoapis/blob/master/image.bin?raw=true' -o wgtwo.bin

grpcurl -protoset wgtwo.bin \
  -d '
  {
      "registration": {
          "sipUri": "sips:loopdemo.yourdomain.com:5061",
          "routeType": "ROUTE_TYPE_LOOP",
          "phoneNumber": {
            "e164": "+YOUR_MSISDN"
          }
        }
  }
  ' \
  api.wgtwo.com:443 wgtwo.sipbreakout.v1.SipBreakoutService/UpsertRegistration

Example result

Success

{
  "statusCode": "STATUS_CODE_OK"
}

Error

{
  "statusCode": "STATUS_CODE_NOT_ACCEPTABLE",
  "errorMessage": "Secure SIP domain name required"
}

Once this is done you can call the number you set up a registration for, or you can call someone from that number.

What will happen is that once the call arrives to us in the mobile core network, we'll send it back to your FreeSWITCH instance, which will then forward it back to our SBCopen in new windows (while intercepting and recording the media), which we will then forward to the destination number.

After the call is complete a .wav file will be found in the /tmp directory on the host machine.