Skip to main content

OmniMessage IMS Frontend

SIP transport layer for OmniMessage - handles getting messages into and out of IMS networks

What it Does

This is a lightweight SIP frontend that acts as a transport layer between IMS networks and the OmniMessage backend. All message processing, routing logic, and business logic is handled by OmniMessage - this frontend simply:

  • Receives SIP REGISTER messages and forwards subscriber data to OmniMessage
  • Receives Mobile Originated (MO) SMS via SIP MESSAGE and forwards to OmniMessage
  • Retrieves Mobile Terminated (MT) SMS from OmniMessage and sends via SIP MESSAGE
  • Reports delivery status back to OmniMessage
  • Handles SIP-level protocol details (headers, acknowledgments, etc.)

Architecture

The IMS frontend consists of two main components:

SIP protocol handling:

  • SIP REGISTER - Extracts subscriber data and forwards to OmniMessage
  • SIP MESSAGE - Receives MO SMS and forwards to OmniMessage
  • SIP MESSAGE - Sends MT SMS from OmniMessage to subscribers
  • SIP NOTIFY - Handles event notifications
  • UAC responses - Captures delivery confirmations and forwards to OmniMessage

OmniMessage backend transport layer:

  • insert_location() - Sends subscriber registration data to OmniMessage
  • insert_message() - Sends incoming MO messages to OmniMessage
  • get_queue() - Retrieves pending MT messages from OmniMessage
  • process_message() - Sends delivery status updates to OmniMessage
  • frontend_register() - Registers this frontend with OmniMessage

All message processing, routing decisions, queuing, storage, and business logic happens in OmniMessage. This frontend is purely a SIP transport adapter.

Configuration

All configuration is stored in the config.yaml file.

Configuration Parameters​

api_base_url - Base URL for the OmniMessage backend API

  • Format: https://hostname:port
  • Example: https://10.5.198.200:8443
  • Used for all backend API calls (insert_location, insert_message, get_queue, etc.)

location - Identifier for this IMS frontend instance

  • Format: FQDN-style identifier
  • Example: smsc01.mnc001.mcc001.3gppnetwork.org
  • Used to identify this frontend in the backend system
  • Should be unique across all frontends

s_cscf_sip_uri - S-CSCF SIP URI for routing messages (optional)

  • Format: sip:hostname:port
  • Example: sip:127.0.0.2:5060
  • If set, all outbound SIP MESSAGEs route through this S-CSCF
  • If not set, messages route directly to the IMS domain

ims_domain - IMS domain for subscriber routing

  • Format: IMS domain name
  • Example: ims.mnc001.mcc001.3gppnetwork.org
  • Used to construct SIP URIs for subscriber addressing
  • Used when s_cscf_sip_uri is not configured

Message Flow

SIP REGISTER Flow​

Mobile Originated (MO) SMS Flow​

Mobile Terminated (MT) SMS Flow​

Polling and Flush Cooldown

The frontend uses two mechanisms to check for MT messages to deliver:

  1. Periodic polling (rtimer) - Kamailio's rtimer module triggers Database_flush() at a fixed interval (configured in kamailio.cfg). The default interval is 2 seconds.

  2. Event-driven flushing - When a UAC response is received that doesn't match a tracked MT SMS (e.g. an MO-SMS ACK reply), Database_flush() is also called immediately.

To prevent these two mechanisms from overlapping and making redundant API calls, a flush cooldown is implemented using a shared timestamp file (/tmp/smsc_ims_last_flush). Every call to Database_flush() writes the current timestamp to this file. Before the rtimer fires, it checks the file's modification time - if a flush occurred within the last FLUSH_COOLDOWN seconds (default: 1 second), the rtimer poll is skipped.

This shared file approach is necessary because Kamailio spawns multiple worker processes, each with its own Python interpreter. Instance variables are not shared across processes, so the file acts as cross-process shared state.

The rtimer interval is configured in kamailio.cfg:

modparam("rtimer", "timer", "name=ta;interval=2;mode=1;")
Last updated on