Business Productivity

Integrating PSTN callers with Amazon Chime SDK meetings

Using Amazon Chime SDK meetings, you can create a custom meeting application for users to start or join calls over web browsers or mobile. However, you may also seek to support callers from Public Switched Telephone Networks (PSTN) phones dialing in to your Amazon Chime SDK meetings. This may include callers that have weak or no internet access and/or prefer to join the meeting over their PSTN phone. For example, callers could be joining in a café or train station as opposed to those joining from their offices or homes.

Amazon Chime SDK supports joining via Session Initiation Protocol (SIP). Because of this, you can use Amazon Chime Voice Connector to obtain a phone number, similar to a conference line. This number can be used by users to dial in from their phones to join or start an Amazon Chime SDK meeting. You can use any SIP-enabled Private Branch Exchange (PBX) with Interactive Voice Response (IVR) application features to create a simple voice menu. This menu prompts the user for a meeting ID and joins the caller’s audio to the meeting.

Overview of solution

In this post, we walk through using an open source PBX software, FreeSWITCH, to handle PSTN connectivity to Amazon Chime SDK meetings. An Amazon Chime Voice Connector integrates with the FreeSWITCH PBX and provides PSTN connectivity.

The following shows the solution flow beginning with starting an Amazon Chime SDK meeting. A PSTN caller calls in to the phone number assigned in the Amazon Chime Voice Connector. This triggers the FreeSWITCH PBX to interact with the PSTN caller through a voice menu. The caller is then joined to the desired meeting.

It is possible to use a single Amazon Chime Voice Connector for inbound/outbound calls. However, for this example, we use two Amazon Chime Voice Connectors. Using two Amazon Chime Voice Connectors allows you to stream and capture audio from each voice connector separately. You can also enable voice streaming in the Amazon Chime Voice Connector to stream audio from your meeting to Amazon Kinesis Video Streams. Once the audio is streamed to Amazon Kinesis, you can use other AWS services for added analytics. For example, you can use services like Amazon Transcribe, Amazon Comprehend, and Amazon SageMaker with the audio stream. You can also store the audio in Amazon Simple Storage Service (Amazon S3).

Architecture diagram with flow of PSTN caller dialing in and joining Amazon Chime SDK meeting

Architecture diagram with flow of PSTN caller dialing in and joining Amazon Chime SDK meeting

Prerequisites

Before getting started, make sure that you have the following resources in place:

Steps

To build this solution, you must use Amazon EC2 and Amazon Chime Voice Connector to connect to the Amazon Chime SDK meeting application. Download these files from GitHub to configure the IVR application in FreeSWITCH. Here are the high-level steps. Note, if you choose to use a paid AMI that has FreeSWITCH preinstalled, you can skip step 3 :

  1. Create two voice connectors for inbound and outbound calling
  2. Create an Amazon EC2 instance for the FreeSWITCH server.
  3. Install and compile FreeSWITCH
  4. Configure FreeSWITCH to connect to Amazon Chime Voice Connector
  5. Configure FreeSWITCH with an IVR application that plays a menu and connects the caller to the Amazon Chime SDK meeting
  6. Join your Amazon Chime SDK meeting from a PSTN phone

Create two voice connectors for inbound and outbound calling

The Amazon Chime Voice Connector connects PSTN phone numbers to your IVR application and the Amazon Chime SDK meeting.

  1. Log in to the Amazon Chime service console
  2. On the left pane under Calling, choose phone number management and select Provision phone numbers. Choose Voice Connector and press Next.
  3. Use the search options to select a phone number for your IVR application and press Provision
  4. On the left pane under Calling, choose voice connectors and select create new voice connector
  5. Enter a name (ex: “inbound_FreeSWITCH”) and select a region for your inbound voice connector. Change the default selection of encryption to disabled for this test environment.
  6. Under the voice connector configuration, choose the Origination tab and select enabled. Press New to add a new inbound route and enter the FQDN of your FreeSWITCH server. If you don’t have the FQDN yet, you can come back and enter this after the FreeSWITCH server is installed. Use 5080 for the port, TCP for the protocol, and priority and weights of 1.
  7. Assign the phone number you claimed earlier to this inbound voice connector by choosing the Phone Numbers tab and selecting Assign from inventory. Choose your phone number and press Assign from inventory.
  8. Add the outbound voice connector by choosing voice connectors on the left pane under Calling, and selecting create new voice connector
  9. Enter a name (ex: “outbound_FreeSWITCH”) and select a region for your outbound voice connector. Leave the default selection of encryption enabled.
  10. Under the voice connector configuration, choose the Termination tab and select enabled. Enter the IP address of your FreeSWITCH server in the Allowed hosts list. If you don’t have the IP address yet, you can come back and enter this after the FreeSWITCH server is installed.
  11. After the voice connectors are created, copy the Outbound host name of both voice connectors in the Amazon Chime service console. These values are used later when configuring the FreeSWITCH server

Create an Amazon EC2 instance for the FreeSWITCH server

The Amazon EC2 instance AMI we use for this example is a Debian 10 Buster AMI in a t3a.medium size. By using an AMI with FreeSWITCH preinstalled, you can skip choosing the Debian 10 Buster AMI and the install and compile FreeSWITCH step.

  1. Log in to the Amazon EC2 service console
  2. Choose Instances on the left pane and select Launch Instance
  3. Search for “Debian” in the AWS Marketplace to locate the Debian 10 Buster AMI and press select and continue
  4. Choose the t3a.medium size and press next
  5. Select the correct network and subnet that allows the instance to reach the internet
  6. Configure inbound rules for the security group to allow SSH, RTP media, and SIP signaling to host from the subnet IP address ranges
    7. port numbers protocol IP address ranges description
    16384-32767 udp 99.77.253.0/24, 3.80.16.0/23 Media
    5080, 5060, 5061, 6063 tcp 3.80.16.0/23, 99.77.253.0/24 Signaling
    22 tcp <Your Admin IP Address>/32 SSH
  7. Choose Review and Launch and select Launch

Install and compile FreeSWITCH

Now, install and compile FreeSWITCH on the Amazon EC2 instance. This instance handles inbound calls for joining a meeting and transferring to the Amazon Chime SDK meeting.

  1. Follow the Easy Way instructions to install and compile FreeSWITCH and dependencies for the Debian 10 Buster operating system. Instructions can be found on the FreeSWITCH.org website. Before the compile step to enter command ./configure, make the following changes to the modules.conf file under /usr/src/freeswitch:
    • Uncomment lines for applications/mod_curl and Languages/mod_v8
    • Comment out line for applications/mod_enum
  2. Continue with the build commands as follows:
./configure
make
make install

Take note of the FreeSWITCH configuration locations:

————————– FreeSWITCH configuration ————————–

Locations:

prefix: /usr/local/freeswitch

confdir: /usr/local/ freeswitch/conf

certsdir: /usr/local/ freeswitch/certs

scriptdir: /usr/local/ freeswitch/scripts

soundsdir: /usr/local/ freeswitch/sounds

——————————————————————————

Configure FreeSWITCH to connect to Amazon Chime Voice Connector

The following steps set up TLS to the outbound voice connector and edit FreeSWITCH configuration files for integration with the voice connectors.

  1. Generate certificates with the following commands using the name of your FreeSWITCH instance. You may need to add executable permissions to the gentls_cert utility (ex: chmod +x gentls_cert)

    2. The gentls_cert utility is located in the /usr/src/freeswitch/scripts directory. The certs are created in /usr/local/freeswitch/certs. 

    ./gentls_cert setup -cn <FreeSWITCH server FQDN> -alt DNS:<FreeSWITCH server FQDN> -org <your server domain>
./gentls_cert create_server -cn <FreeSWITCH server FQDN> -alt DNS: <FreeSWITCH server FQDN> -org <your server domain>
  2. Copy the generated certificate files from the default directory (/usr/local/freeswitch/certs) to the /etc/freeswitch/tls directory.
  3. To enable TLS, modify the SIP profile (external.xml). Edit the external.xml file located in the /usr/local/freeswitch/conf/sip_profiles/ directory to use /etc/freeswitch/tls/:
    4. <!-- Location of the agent.pem and cafile.pem ssl certificates (needed for TLS server) -->
<!--<param name="tls-cert-dir" value="/etc/freeswitch/tls/ "/>-->
  4. Modify vars.xml in the /usr/local/freeswitch/conf directory. This changes the default password, sets the domain value to the FQDN of the FreeSWITCH server, and enables SRTP with the correct cipher
    5. <X-PRE-PROCESS cmd="set" data="default_password=<new password here>"/>
<X-PRE-PROCESS cmd="set" data="domain=<freeswitch_server.example.com>"/>
<X-PRE-PROCESS cmd="set" data="zrtp_secure_media=true"/>
<X-PRE-PROCESS cmd="set" data="rtp_secure_media_outbound=true:AES_CM_128_HMAC_SHA1_80"/>
  5. Modify modules.conf.xml and switch.conf.xml located in the /usr/local/freeswitch/conf/autoload_configs directory. This enables curl to be used for the IVR application to join the PSTN caller to the Amazon Chime SDK meeting.
    • modules.conf.xml – uncomment <!-- <load module="mod_xml_curl"/> -->
    • switch.conf.xml – uncomment <!-- <param name="rtp-start-port" value="16384"/> --> <!-- <param name="rtp-start-port" value="16384"/> -->, 

    Note the ports used for the internal and external SIP profiles in the vars.xml file in case you must modify these.

    <!-- Internal SIP Profile -->
<X-PRE-PROCESS cmd="set" data="internal_auth_calls=true"/>
<X-PRE-PROCESS cmd="set" data="internal_sip_port=5060"/>
<X-PRE-PROCESS cmd="set" data="internal_tls_port=5063"/>
<X-PRE-PROCESS cmd="set" data="internal_ssl_enable=false"/>
<!-- External SIP Profile -->
<X-PRE-PROCESS cmd="set" data="external_auth_calls=false"/>
<X-PRE-PROCESS cmd="set" data="external_sip_port=5080"/>
<X-PRE-PROCESS cmd="set" data="external_tls_port=5061"/>
<X-PRE-PROCESS cmd="set" data="external_ssl_enable=true"/>
  6. Create a SIP profile configuration in FreeSWITCH to connect to the outbound voice connector by adding a new file. Name this file vc.xml in the /usr/local/freeswitch/conf/sip_profiles/external directory. Edit the file with the required fields below. Replace values with your outbound voice connector ID that was copied earlier from the Amazon Chime console. See the example.xml file in this directory for more optional parameters.
    7. <include>
<gateway name="<voice connector id>.voiceconnector.chime.aws">
<!--/// account username *required* ///-->
<param name="username" value="not-used"/>
<!--/// account password *required* ///-->
<param name="password" value="not-used"/>
<!--/// proxy host: *optional* same as realm, if blank ///-->
<param name="proxy" value="<voice connector id>.voiceconnector.chime.aws"/>
<!--/// do not register ///-->
<param name="register" value="false"/>
<!-- which transport to use for register -->
<param name="tls-version" value="tlsv1.2"/>
<param name="register-transport" value="tls"/>
<!--How many seconds before a retry when a failure or timeout occurs -->
<!--<param name="retry-seconds" value="30"/>-->
<!--Use the callerid of an inbound call in the from field on outbound calls via this gateway -->
<param name="caller-id-in-from" value="true"/>
</gateway>
</include>

     

Configure FreeSWITCH with an IVR application that plays a menu and connects the caller to the Amazon Chime SDK meeting

  1. Create a new XML file named chime.xml for the dial plan in the /usr/local/freeswitch/conf/dialplan/public directory. The file content is listed below. Use your voice connector ID in the application bridge section. The +17035550122 phone number is a static number that is used for the Amazon Chime Voice Connector and Amazon Chime SDK integration.
    2. <include>
<extension name="meeting-ivr">
<condition field="destination_number" expression="^\+1">
<!-- call the script to collect the meeting ID and resolve the join token -->
<action application="javascript" data="JoinMeeting.js" />
<!-- bridge the call to the voice connector with the join token as an INVITE parameter -->
<action application="bridge" data="{sip_invite_params=X-chime-join-token=${join-token}}sofia/gateway/<voice connector id>.voiceconnector.chime.aws/+17035550122" />
</condition>
</extension>
</include>
  2. Add script to play a menu for PSTN callers to join the meeting. Copy the JoinMeeting script with audio files. Add the JoinMeeting.js file to the /usr/local/freeswitch/scripts directory. Add the two wav files (please_enter_id.wav and now_join.wav) to the /usr/local/freeswitch/sounds directory.

Join your Amazon Chime SDK meeting from a PSTN phone

  1. Start an Amazon Chime SDK meeting with an eight-digit, numeric meeting ID (for example, 12345678). If you have different meeting ID criteria, you can modify the JoinMeeting.js file to change your meeting ID format.
  2. Call in to the phone number you assigned to your Amazon Chime Voice Connector and when prompted, enter your meeting ID (12345678)
  3. Your call should now be connected as a participant in the Amazon Chime SDK meeting. The following is an example screenshot.
    4. Amazon Chime SDK meeting console with participant list and meeting controls

    Amazon Chime SDK meeting with participants list.

  4. As an option, you can enable streaming on your outbound voice connector to capture the audio from your meeting for storage or analytics in AWS. Once enabled, your audio is streamed to Kinesis. Here, you can use other AWS services such as Amazon Transcribe and Amazon Comprehend in real time or on stored audio.

Cleaning up

To avoid incurring future charges, delete the Amazon EC2 instance, Amazon Chime Voice Connector, and the obtained PSTN phone number. Also, remove your Amazon Chime SDK serverless application if you created one for this demo.

Conclusion

In this post, you learned how to add the ability for PSTN callers to participate in your Amazon Chime SDK meetings. You also built an open source PBX in AWS and learned about how to obtain a PSTN phone number in Amazon Chime Voice Connector. Now your custom Amazon Chime SDK meetings can include callers that do not have an internet connection suitable for audio. You can also include callers who prefer to use their PSTN phone to join. For more information on Amazon Chime Voice Connector streaming and transcription, see this GitHub sample project for Amazon Chime Voice Connector streaming. Learn more about building a meeting application using the Amazon Chime SDK to create and customize your own experience.