Jitsi SIP integration with Jigasi and the video SIP gateway

Jigasi is the Jitsi SIP gateway, and it handles audio only. A participant who dials in from a telephone joins the meeting so they can hear the room and speak into it, but they do not send or receive video. Browser participants see the phone caller as a participant in the room, while the phone caller sees and hears only the audio mix. Before you promise anyone a dial-in number, decide whether audio-only participation meets the use case. If the meeting depends on people seeing shared screens or on video from a room system, Jigasi will not cover that need, and the video SIP gateway described in the next section is a separate design.

In the official Docker setup, Jigasi is not part of the default stack. You enable it by including the jigasi.yml compose file alongside the core compose file, then configure it through its SIP settings in the environment file. The settings you will work with are JIGASI_SIP_URI, JIGASI_SIP_PASSWORD, JIGASI_SIP_SERVER, JIGASI_SIP_PORT and JIGASI_SIP_TRANSPORT. The URI identifies the SIP account, the password authenticates it, and the server, port and transport tell Jigasi where to register and how to reach it. Keep the password out of version control and handle it the same way you handle other service secrets. The Docker guide also notes that Jigasi needs UDP ports 20000 to 20050 open when it is deployed for SIP access, so raise this with your network and firewall team early, because it is easy to overlook.

The SIP account does not come from Jitsi. It comes from your organization's telephony provider or PBX, which issues the account, the registration credentials, and the rights to place and receive calls on a given number or extension. Ask the provider or PBX administrator to confirm four things in writing: that the account is allowed to register from your server's address and transport, that it can receive inbound calls on the dial-in number you plan to publish, that it can place outbound calls if you need them, and whether the provider charges per call minute or per channel. Some providers limit concurrent calls or restrict which destinations are reachable, and those limits will shape how many phone participants a meeting can take. Confirm them before you configure anything, because the account's permissions set the ceiling for the whole design.

Plan the transport choice and the network path with the provider's documentation in hand. Whether the SIP signaling uses UDP, TCP or TLS must match what the provider supports, and the port must be the one the provider expects, not the default you find in a sample file. Test registration first with a single account and confirm that inbound and outbound calls connect and that audio flows in both directions. Only then add the dial-in number to your meeting invitations. A common failure is a registration that appears to succeed while one-way audio or dropped calls appear once real traffic starts, which usually points to the UDP range or a NAT setting on the path rather than to Jigasi itself.

Choose the video SIP gateway when room systems in your estate must send video into a Jitsi meeting, because the audio-only Jigasi gateway does not carry that stream. The video gateway uses a Jibri instance configured with a SIP video device, so the room system reaches the meeting through Jibri. Before you commit, list which rooms need video in, how often they dial in, and whether audio-only dial-in through Jigasi already meets the need. The video path adds a Jibri machine to operate, so it should be justified by a named room use case and a signed-off requirement.

The documented constraints shape the design before any hardware is ordered. The gateway is available only to non-guest users, so every person who starts a call from a room system needs an authenticated account and cannot rely on the guest path. It relies on enableUserRolesBasedOnToken together with a JWT, which means your token issuance must carry the roles that Jitsi checks, and your guest and authenticated domains must be configured separately. It also calls SIP addresses returned by a people search service, so the directory behind that service must hold correct, dialable SIP addresses for each person who should be reachable from a room. Confirm the exact token claims and search service settings against the video SIP gateway page in the Jitsi handbook for your release.

Run Jibri on its own machine or VM, separate from the web server, Prosody, Jicofo and the videobridge, because it runs Chrome in a virtual framebuffer and encodes with ffmpeg, which is resource-intensive. The Jibri README states that only one recording at a time is supported on a single Jibri. Treat each active room system call as occupying that Jibri until you have verified otherwise. Ask the Jitsi project, your implementation partner and your own load tests to confirm whether a SIP video session follows the same single-session limit, how many Jibri instances you need for the largest number of rooms that could dial in at once, and how a busy Jibri is reported to the people trying to join.

Do not promise room coverage until the capacity plan is written down. A workable plan lists each room, the device it uses, the Jibri instances behind it, the expected number of simultaneous calls, the directory coverage for SIP addresses, and the accounts allowed to start calls. Ask for a written quote that prices the Jibri machines, the token and directory integration, the testing of concurrent calls, and the runbook for a busy or failed Jibri. Plan for the recurring cost of running those machines and of keeping the people search data current, since both change as staff and rooms change.

Test the SIP path in both directions and in each role before any user is told to rely on it. Start with inbound and outbound test calls between a phone and a meeting in your Jitsi deployment, using the SIP account configured through JIGASI_SIP_URI, JIGASI_SIP_PASSWORD, JIGASI_SIP_SERVER, JIGASI_SIP_PORT and JIGASI_SIP_TRANSPORT. Confirm with your SIP provider which transport and port it expects, because a registration that succeeds can still fail on media. For each call, run a one-way audio check and a two-way audio check. Speak from the phone and confirm browser participants hear you, then speak from a browser and confirm the phone hears the meeting. Jigasi needs UDP ports 20000 to 20050 open, so a fault in only one direction often points to media ports or NAT before it points to signaling.

Confirm that the phone caller is audio only. Jigasi is an audio gateway, so the dial-in participant should appear without a video tile, and no video should be sent back to the phone. Next, check the video SIP gateway, which runs on a Jibri configured with a SIP video device and is available only to non-guests. Join the same room once with a token that marks the user as a non-guest and once as a guest, using enableUserRolesBasedOnToken with a JWT. The non-guest session should reach the gateway and the guest session should not. Then confirm the gateway calls only the SIP addresses returned by your people search service, using a directory entry you control. A guest who can start an outbound call is the most consequential failure in this section, so record the result for each token type.

Test a second concurrent video session and compare the result with the Jibri documentation, which states that only one recording at a time is supported on a single Jibri. Start one session through the video gateway, then start a second while the first is active. Record what the user sees and what the logs show. Do not assume the second session queues, fails or joins the first. If your business needs two sessions at the same time, treat that as a capacity decision. Confirm in the Jibri documentation how additional instances are added, and place each Jibri on its own machine or VM as the README recommends. Repeat this test after any change to the number of Jibri instances.

Watch the Jigasi and Jibri logs for the full test window, and keep a baseline from before the first call. With the Docker setup, follow the output of the jigasi and jibri services and note timestamps for each test call so that a log entry can be matched to a specific attempt. Look for SIP registration or authentication failures, port binding errors, token rejections and Jibri startup failures. Record each call in a simple test log that lists direction, participant role, audio result, video result and related log entries. Keep this log with the change record, because it becomes the evidence your team uses when a later upgrade or credential rotation changes the SIP path.

Plan the rollback before the first test call. If a check fails and cannot be fixed quickly, disable the gateway by removing the jigasi.yml compose file from the stack and redeploying, or remove the room device route that sends calls to the video SIP gateway. Then confirm that the dial-in number no longer answers, that no room device can start a call, and that browser users can still join meetings normally. Rehearse this sequence in a non-production environment first, and decide in advance who has authority to make the change and who must be informed. Do not leave a partially working gateway live while the team investigates.