MSRP Gateway

The majority of SIP User Agents still only support the MESSAGE method for providing Instant Messaging. However, modern Unified Communications(UC) ecosystems and more advanced messaging services, such as RCS(Rich Communication Services), are built on top of Session Mode messaging, which uses the MSRP protocol.

With the addition of the new msrp_gateway module, OpenSIPS 3.3 introduces a way of bridging this gap by providing the possibility to translate between these two modes of communication.

Gateway sessions

In contrast to MSRP-based messaging, which first establishes a session using SIP and then sends messages via the MSRP protocol, the SIP MESSAGE method involves a series of unrelated messages. As such, we need to create a “session” at the MSRP gateway level, which will associate a series of MESSAGE requests with a SIP session on the MSRP client side.

In order to create such a mapping, we need to build a correlation key, at script level, that we can infer both from MESSAGE requests and from the initial INVITE from the MSRP side. This is an arbitrary, opaque string for the module, as there is no fixed criteria for bundling MESSAGE requests that we consider to belong to the same “session”.

Session termination

In terms of terminating gateway sessions, the user on the MSRP side can simply send a BYE request, but from the MESSAGE side the only hint we have is no request received for an interval of time(controlled via the message_timeout module parameter). There is also the option to end the session “manually” via the msrp_gw_end_session MI command.

Module overview

The main functionality of the msrp_gateway module is encapsulated by the following script functions:

• msrp_gw_answer(key, …) – create a new gateway session by answering an initial INVITE from an MSRP client;
• msg_to_msrp(key, …) – translate a MESSAGE request into a SEND request on the MSRP client side(creating a new MSRP session if one does not exist for this key).

For the MESSAGE to MSRP initial direction, we handle each request in the script with the msg_to_msrp() function. Once the MSRP session is established, SEND requests are also translated into MESSAGE requests automatically.

For the MSRP to MESSAGE initial direction, we call msrp_gw_answer() for the initial INVITE and the module takes care of the rest. On the other hand, for the messages received from the other side of this gateway session, we still need to call msg_to_msrp() for every MESSAGE request.

MESSAGE side failure reporting

When starting a new gateway session by handling a MESSAGE request, there is a distinct possibility that the setup of the MSRP session fails. In this case it would not be wise to just wait for the final reply from the MSRP side, before replying to the SIP MESSAGE request, since it might take a lot of time. Nevertheless, we might want to just reply with a 200 class response and report back to the MESSAGE side later, if a failure occurs, by sending a custom message. The module offers this possibility by triggering the E_MSRP_GW_SETUP_FAILED event.

Configuration

Below is a simple OpenSIPS config example, containing all the MSRP-related scripting required for implementing a fully-working gateway. The session key is built as FromUri:ToUri.

loadmodule "b2b_entities.so"
loadmodule "proto_msrp.so"

# configure the MSRP UA to be used by the gateway
loadmodule "msrp_ua.so"
modparam("msrp_ua", "my_uri", "msrp://192.168.1.249:2855;tcp")
modparam("msrp_ua", "advertised_contact", "sip:192.168.1.249:5060")

loadmodule "msrp_gateway.so"
# terminate session if no MESSAGE received in the last 30 minutes
modparam("msrp_gateway", "message_timeout", 1800)

route{
    ...
    if (is_method("INVITE")) {
        msrp_gw_answer("$fu:$tu", "text/plain", $fu, $tu, $ru);
        exit;
    } else if (is_method("MESSAGE")) {
        msg_to_msrp("$tu:$fu", "text/plain");
        send_reply(200, "OK");
        exit;
    }
    ...
}

# if msg_to_msrp() fails, send custom MESSAGE
event_route[E_MSRP_GW_SETUP_FAILED] {
    t_new_request("MESSAGE", $param(ruri), "sip:$param(from_uri)", "sip:$param(to_uri)",
        "text/plain Failed to establish session, error: $param(code) $param(reason)");
}

Conclusions

The new MSRP Gateway in OpenSIPS 3.3 offer an easy to use way of providing access for MESSAGE-only SIP users to advanced Instant Messaging services unlocked by Session Mode messaging and MSRP.

You can find out more about all the Messaging related features in OpenSIPS 3.3 during the OpenSIPS Summit 2022 in Athens.