DIY Asterisk Integration

[david.bohorquez]

Hi folks,

I just configured Rocket.Chat integration with Asterisk, and to save you all the pain I’ll share with you my findings and make it easy.

Requirements:

• Asterisk 16.19.0 or higher (I used FreePBX 16.0.10.40 with Asterisk 18.6.0)
• Valid SSL certificate (valid domain of course)
• I used Rocket.Chat SaaS under trial period 4.8.1

So, hands-on.

0. Prepare FreePBX (if you have one ready skip this step, probably)
   Install your FreePBX server, as usual (that’s out of the scope of this tutorial), and update it using your OS package manager, I used CentOS 7, in such case it’s:

yum update -y

Enter your server web interface http://your.domain.name and set password and update settings, and do the activation process, DON’T SKIP, you’ll need some features later that are only available if you activate your server instance (that’s also out of the scope of this tutorial, but you can do it for free so don’t be lazy and do it).

Complete the firewall basic configuration. We will do some more afterward.

1. Configure the FreePBX firewall
   Now we need to prepare the FreePBX firewall to accept AMI (Asterisk Manager Interface) and WSS (WebSocket Secure), these two don’t come by default.
   1.1 Configure custom services AMI and WSS
   Go To Connectivity - Firewall - Services, under the Services tab search for WebRTC and mark Internet and Other options, Local is active by default.
   
   
   
   We want WebRTC in the Internet zone because the Webphone will connect from the client’s IP address, which could be anywhere.

Turn to the “Custom Services” tab and hit the “Create new service” button, name the service AMI, select TCP, and write the port range 5038:5039, click Save

Mark the “Other” option and save (green button), AMI goes in the “Other” zone because only some specific endpoints should be connecting to AMI.

1.2 Whitelist Rocket.Chat
Now we don’t want our Rocket.Chat to get banned by the FreePBX firewall so we will add it to the Whitelist List. First, we need to know the IP or IP Networks from our Rocket.Chat instance. When you have a SaaS Rocket.Chat instance you will have a URL (subdomain) like MyChosenName.rocket.chat, so just ping it, in my case:

As Rocket.Chat uses a robust infrastructure and by experience, I know that Rocket.Chat will be connecting from the whole network 51.81.0.0/16
If you have your own Rocket.Chat instance self-hosted or similar, you should know what’s your IP address or network.

Now, turn back to the Connectivity - Firewall - Networks tab menu, and add the IP address needed or Network select the Other zone and save:

Rocket.Chat will be in the Other zone because it’s our special guest.

2. Configure SSL (I used Letsencrypt)
   This will only work if you have your FreePBX already activated (I told you so). Go to the menu Admin - Port Management, here we will change the Admin (web portal) to another port and set Let’s Encrypt to port 80, click Update Now.
   
   
   
   Until here we have been accessing the server by HTTP (not HTTPS) on port 80, until we finish SSL configuration we will be using the newly selected port, 8080 in my case.

Now go to the Admin - Certificate Management menu, and click on New Certificate - Generate Let’s Encrypt Certificate:

Fill out the form according to your settings and click on Generate Certificate:

Let it roll and wait. Once it’s generated mark it as the system’s default:

Now it’s time to start using it. Go to the Admin - System Admin - HTTPS Setup menu and then to the settings tab, there select the certificate that was just generated and click on install, wait, then select the Protocols you like to use. I’m selecting only TLS 1.2 and 1.3 as others are considered deprecated or insecure:

Finally, click on “Save and Restart Apache” (I would suggest a server restart some things are different after a restart, sad experience). Test in incognito that the changes had been applied and that the certificate is recognized as valid.

Additionally, you can go back to the Admin - System Admin - Port Management menu to enforce HTTPS, select your FQDN and select the force (arrow) button from HTTP (8080) to HTTPS (443), then click on save:

Test it. Congratulations! you have an HTTPS valid SSL FreePBX server up and running.

3. Configure Asterisk to use PJSIP as the main (or only) SIP channel
   For my taste, I’m no longer interested in chan_sip, so I’m using chan_pjsip as the only SIP driver. Go to the Settings - Advanced Settings menu search for SIP Channel Driver and choose chan_pjsip, then Submit.

4. Configure Asterisk HTTP/WebSocket features
   Here I’m guiding myself by the article Configuring Asterisk for WebRTC Clients in Asterisk’s Wiki, I’m going here only for the principal parameters if you need more details the article is a great guide.
   4.1 Enable Asterisk’s WebSocket and mini-HTTP
   First, check that you have the needed modules loaded using the command “module show like <module_name>”
   

   
   
   We will reuse the Let’s Encrypt certificates for the Asterisk mini-HTTP server and all about WebSockets, TLS encryption, etc, etc. Start by going to the Settings - Advanced Settings menu (again), search for the " Asterisk Builtin mini-HTTP server" section and configure as shown, apply changes, and I would suggest restarting Asterisk:
   
   
   
   Using the command “http show status” verify that both HTTP and HTTPS are up and running:
   
   If HTTP is but HTTPS doesn’t check that asterisk can read the certificate and private key files.
   TO-DO: Add capture of file reading error.
   4.2 Enable the WS and WSS SIP transports
   Go to the Settings - Asterisk SIP Settings menu, there into the General SIP Settings tab configure your audio codecs (remember opus), enable video, and select video codecs (vp8 and vp9 needed for WebRTC), NAT, etc. Then in the SIP Settings (chan_pjsip) tab choose your valid SSL certificate for TLS/SSL/SRTP and enable all the desired transports, especially WS and WSS:
   
   
   
   Click submit and apply changes (an Asterisk restart never goes bad)
   4.3 Test Asterisk HTTP mini-server
   Navigate to https://mysub.domainname.domain:8089/httpstatus and verify that it loads, that SSL Port is present, and that the SSL certificate is valid:
   
   Congrats! you have a valid SSL Asterisk WebRTC ready server.

5. Create and configure some PJSIP extensions WebRTC ready
   Create an extension (Applications - Extensions menu) as usual, the quid is in the Advanced tab, configure as follows:
   

   
   
   
   
   
   
   
   
   
   

6. (Optional) Test FreePBX readiness using FOP2
   You can install FOP2 and FOP2ś WebRTC webphone plugin in your FreePBX server, if the plugin works your WebRTC configuration is complete and working. Is not complicated, and it could help you to diagnose any issue, but it’s out of the scope of this tutorial.

7. Configure Asterisk Manager Interface and users
   Last but not least, Rocket.Chat needs an AMI connection to be able to read your Asterisk configuration and connect extensions to RC users. So, go to the Settings - Asterisk Manager Users menu, there you will create a user to be used by RC and limit the access of this user only to the IP address or network where your RC is. Something like:
   

   

Notice that here netmask goes in octets rather than bits. Submit and apply changes.

8. Activate Omnichannel
   Here we can follow a little of the Rocket.Chat documentation on https://docs.rocket.chat/guides/rocket.chat-call-center and so on. Start by activating Omnichannel as explained in Omnichannel - Rocket.Chat Docs
9. Configure the VoIP Omnichannel feature
   Rocket Chat establishes two connections with Asterisk, one via AMI to read configuration and list extensions, queues, and some other things, and the second one is the WebRTC SIP registration.
   9.1 Configure AMI connection
   Go to the menu Administration - Settings - Call Center - Settings, and into the Management Server section you fill the form with the FQDN of your server, and the user/password that we just created:
   
   

9.1.1 Test AMI Connection
To test AMI connection turn to the Extensions tab, there you should see a list of the existing extensions in Asterisk:

Also enabling the AMI debug you may see connections coming and the RC AMI user connected:

manager set debug on
manager show connected

If you see it, your RC is connected to the Asterisk’s AMI.

9.2 Configure WebSocket Server Connection
Now the correct parameters for a FreePBX connection are:

Change them according to your Asterisk server conditions. Then in the Settings tab assign at least one extension to a RC user. When that user logs in to RC the webphone will try to connect to Asterisk.

9.2.1 Test WebSocket Connection
To test the WebSocket Connection we just need to log in with a user associated with an extension and check if the extension registers successfully:

The phone icon with a slash over it means that the WebSocket connection is possible, RC could send a SIP Options packet to Asterisk, and it was successfully answered. Click on the phone icon and it will turn green:

Now the user is ready to receive calls, and in Asterisk, you should have received a SIP register packet and the extension should be properly registered, validate it with:

pjsip show endpoints

That’s awesome! we have successfully configured our Rocket.Chat with Asterisk!

10. Configure FreePBX features, inbound routes, queues
    Now if you want to get real you gotta configure a DID inbound route to an IVR and then a queue, and then you will be able to receive calls. This kind of configuration requires that you use “call back login” instead of “agent login” and that you use extensions rather than agents. But those configurations are out of this tutorial.

10.1 Test inbound calls
Now just call your extension from another extension or from outside, play, enjoy, and get fun.

11. Bonus - Troubleshooting
    11.1 AMI Troubleshooting
    If your RC doesn’t list extensions and shows a red error pop-up, it is not connecting with Asterisk. It could be because the username or password or host is wrong, can be a firewall issue too, or, my favorite, Rocket.Chat is not sending the connection.
    First and obvious, verify your username/password/host.
    Let’s see if we are receiving the connection from RC into asterisk, our friend here will be the command manager set debug on. Once activated you should see messages in Asterisk CLI that indicate that RC AMI user is connecting and executing commands, like this:
    
    
    
    In this example, the user that is connecting is the admin user, something similar should be seen for RC AMI user, if you don’t see it a firewall may be blocking the connection or it is not being sent.
    Let’s diagnose if the server is receiving the connection request before the firewall or not. One simple test is to disable the firewall, but come on we can do better. Let’s use tcpdump, type:

tcpdump dst port 5038

This command will show us all the connection attempts that are arriving at the server to the port 5038 before the firewall catches them, if we see something coming good, check the firewall adjust and done; if not RC is not sending the connection attempt. When it’s working we see something like:

You can use option -n to stop tcpdump resolving IP Addresses into FQDN.

If we suspect that RC is not sending the connection and we have a SaaS we gotta go to https://cloud.rocket.chat/ login with our username and password and reload the workspace, to do so, click on the 3-dot menu at the right and select restart:

After that, you will start to see connections coming to the server while executing tcpdump.

11.2 Webphone troubleshooting
Once you have a user associate with an Asterisk extension, it will show a phone icon, but if the icon has a black background it means that the webphone couldn’t connect with Asterisk:

Enabling the PJSIP debug or using tcpdump should show us if the connection is arriving at Asterisk or not. When you activate PJSIP debug:

pjsip set logger host ip.add.res.s

You should see SIP options packets like:

Otherwise use tcpdump to verify that your server is receiving connections attempts to the WebSocket port:

tcpdump dst port 8089

An attempt connection should looks like:

If no messages are being received, the browser console will be your best friend:

Check your error messages and solve whatever is there. In this case, the WSS URL is obviously wrong as such FQDN does not exist, but while I was doing this I had difficulties trying different ways to write the “Websocket Path” until I found the correct way to do it, the original docs don’t shed too much light on it.