API driven SIP User-Agent end-point with OpenSIPS 3.4

While OpenSIPS is mainly a SIP proxy, SIP Back-2-Back capabilities have been supported for a while. But, what about the “end user agent” support in OpenSIPS? Meaning the ability to create and control a Server / Client SIP User Agent, doing all the SIP magic (transactional and dialog level) transparently for you.

Considering the integration requirements, having OpenSIPS acting as a SIP end-point / user-agent is a quite strong need. This basically translates into having OpenSIPS act as a mixed (SIP and non-SIP) back-to-back, with a User-Agent entity (server or client) on one side and some custom logic on the other side, API controlling what how the SIP side should behave.

This ability is essential particularly when comes to building class 5 services, such as :

• you need to be able to perform advanced call controlling, to originate or answer (not proxying) calls on the OpenSIPS side
• to have some custom logic to control the behavior of the SIP User Agent side
• to be able to integrate with external control logics via API – so OpenSIPS will be the SIP UA engine, while the control is outsourced to third-party apps, via APIs and Events.

Small note here, OpenSIPS already has an Calling API for controlling calls, but that is for proxied calls, not for UA calls.

The SIP User Agent support

Starting version 3.4, OpenSIPS provides full User-Agent – server and client- SIP capabilities via the b2b_entities module. This is done via what is called a SIP User Agent session. And the module is able to run such SIP UA sessions, hiding all SIP particularities (transparently taking care of transactional and dialog SIP level) while passing you the full control over the behavior of the SIP UA sessions.

A SIP UA session may be created by:

• handling an incoming initial INVITE, at script level, so creating a SIP UA server
• firing an MI command to send out an initial INVITE, so creating a SIP UA client

Once the SIP UA session is created, OpenSIPS provided both scripting and MI/API ways of further controlling the session:

• sending replies, including answering an UA server session
• generating in-dialog (or sequential) SIP requests
• ending / terminating the session

For a proper call controlling, OpenSIPS is firing an UA session related event, each time something happens with the session, like reply received, in-dialog request received or session is terminated.

This combination of MI commands (for controlling the call) and events (for monitoring the call) form a powerful kind of API that may be used by external SIP-agnostic applications to originate or answer SIP calls.

The UA Server scenario

The incoming calls – that need to be handled as UA server – are detected at script level, upon receiving the initial INVITE. Once the UA server is created, it is up to the script writer how much handling (like replying) is done at script level or how fast he wants to pass the control to an external application. The minimum you need to do at script level is to create the UA Server session – after that you may pass the session key to the app, using various methods, like raising an event for external consumers, doing a REST call to an external app or even pushing the data via database or external script execution.

Once the call is established, using events (to get updates on the call evolution) and MI command, the external application has full control over the call.

The UA Client scenario

There is a wide range of cases where the call needs to started by the external application, so OpenSIPS will be SIP UA Client. In such case the call may be started only via the MI interface. But once the call is established, similar to the UA Server scenario, the application has full control.

This UAC scenario is a typical one when there is a need to call a destination and injected an already existing stream (from a media engine without SIP capabilities)

Notes

The b2b_entities module takes care only of the SIP signalling part, it is not involved at all in the RTP part. The proper SDP (or whatever data the call may carry) must be provided as parameters to the API/script functions.

During OpenSIPS Summit 2023 we will show some cool demos using this UAC and UAS related APIs, controlling media streaming. So join us !