OmniMessage SMPP Gateway - Operations Guide

Version: 1.0.0 For Operations Teams

What is the SMPP Gateway?

The OmniMessage SMPP Gateway is one of several frontend protocols for the OmniMessage telecommunications platform. It enables SMS messaging by connecting your infrastructure to mobile networks using the industry-standard SMPP (Short Message Peer-to-Peer) protocol.

Important: This gateway is a stateless protocol frontend. It has no business logic, message processing, or storage capabilities. All intelligence comes from OmniMessage, accessed via REST API. Like other OmniMessage frontends (Diameter, MAP, IMS), it simply translates protocol messages to/from OmniMessage's internal format.

Key Capabilities

• Bidirectional SMPP Messaging: Send and receive SMS messages via SMPP
• Multiple Connections: Connect to multiple carriers simultaneously
• High Performance: Handle thousands of messages per second
• Monitoring: Built-in Prometheus metrics and web dashboard
• Reliability: Automatic reconnection and message retry
• Stateless Operation: All processing delegated to OmniMessage backend

Who Should Use This Guide?

This guide is for operations teams responsible for:

• Installing and configuring the gateway
• Monitoring message traffic
• Managing SMPP connections
• Troubleshooting issues

Quick Start

First Time Setup

1. Access Web Dashboard: https://your-server:8087
2. Check System Status: Navigate to SMPP → Live Status
3. Review Configuration: See CONFIGURATION.md
4. Set Up Monitoring: See MONITORING.md

Daily Operations

Common operational tasks:

Task	Action
Check connection status	Web UI → SMPP → Live Status
View message traffic	Web UI → Queue
Monitor system health	Web UI → Logs or Prometheus metrics
Add/modify connections	Web UI → SMPP → Client/Server Peers

See OPERATIONS.md for detailed procedures.

System Architecture

The SMPP Gateway is a stateless protocol translator that operates as part of the OmniMessage platform:

Key Concepts:

• SMPP Gateway: Protocol translator only - no message processing, storage, or business logic
• OmniMessage: Core platform handling all messaging logic, routing, and storage
• API Communication: Gateway retrieves messages to send from OmniMessage and reports delivery status

OmniMessage Integration

The OmniMessage SMPP Gateway is a protocol frontend for the OmniMessage messaging platform. It is one of several identical frontend types that interface with mobile networks using different protocols:

Frontend	Protocol	Purpose
SMPP Gateway	SMPP (SMS)	SMS messaging via SMPP protocol
Diameter Gateway	Diameter	IMS-based messaging
MAP Gateway	MAP	Mobile network signaling
IMS Gateway	IMS	IP Multimedia Subsystem

All frontends share the same architecture: They are stateless protocol translators that delegate all intelligence to OmniMessage Core.

How It Works

Inbound Message Flow (External System → Carrier):

Outbound Message Flow (Carrier → SMPP Gateway):

What the Gateway Does

• Receives SMPP PDUs from carriers and external clients
• Parses and validates SMPP protocol messages
• Translates SMPP format to OmniMessage internal format
• Calls OmniMessage REST API with message data
• Receives messages from OmniMessage via API polling
• Converts OmniMessage format back to SMPP PDUs
• Reports delivery receipts back to OmniMessage

What the Gateway Does NOT Do

• ❌ No message storage or persistence
• ❌ No routing decisions (OmniMessage decides)
• ❌ No rate limiting (OmniMessage enforces)
• ❌ No number validation (OmniMessage validates)
• ❌ No state tracking (OmniMessage maintains state)
• ❌ No business logic (OmniMessage handles all logic)

OmniMessage REST API

The gateway communicates with OmniMessage Core via REST API:

Configuration:

config :omnimessage_smpp,
  api_base_url: "https://omnimessage-core.example.com:8443"

Key API Operations:

• GET /api/message_queue?destination_smsc=<bind_name> - Retrieve pending messages
• PUT /api/messages/<id>/delivery_status - Report delivery receipt
• GET /api/system/health - Health check

Message Format: Messages in the queue contain all necessary delivery information:

• Destination number
• Message body
• Source number
• Priority
• Validity period
• Target SMSC (carrier bind name)

The gateway simply retrieves these, formats them as SMPP, sends them to the carrier, and reports back the status.

Documentation Structure

This documentation is organized into the following guides:

• CONFIGURATION.md - Complete configuration reference with all parameters explained
• MONITORING.md - Prometheus metrics and alerting guide
• OPERATIONS.md - Day-to-day operational procedures
• TROUBLESHOOTING.md - Common issues and solutions
• GLOSSARY.md - Terms and definitions

Access Points

Web Dashboard

• URL: https://your-server:8087
• Features:
  • View SMPP connection status
  • Monitor message queue
  • View system logs
  • Configure SMPP peers
  • Access documentation

Prometheus Metrics

• URL: http://your-server:4000/metrics
• Format: Prometheus text format
• Use: Integration with Grafana/Prometheus

API Endpoint

• URL: Configured in API_BASE_URL
• Purpose: Message queue backend integration

Quick Reference

Common Tasks

Task	Command/Location
Start gateway	systemctl start omnimessage-smpp
Stop gateway	systemctl stop omnimessage-smpp
Restart gateway	systemctl restart omnimessage-smpp
View logs	journalctl -u omnimessage-smpp -f
Check status	Web UI → SMPP → Live Status
View metrics	curl http://localhost:4000/metrics
Edit config	/opt/omnimessage-smpp/config/runtime.exs

Important Files

File	Purpose
/opt/omnimessage-smpp/config/runtime.exs	Main configuration
/opt/omnimessage-smpp/priv/cert/	SSL certificates
/var/log/omnimessage-smpp/	Application logs
/etc/systemd/system/omnimessage-smpp.service	Service definition

Security Notes

• Web UI: Uses HTTPS with your SSL certificates
• API Communication: Can verify SSL or use self-signed certs
• SMPP: Plain text protocol - use network security
• Credentials: Stored in configuration file - protect access

Next Steps

1. Review CONFIGURATION.md for all configuration options
2. Set up MONITORING.md with Prometheus
3. Familiarize yourself with OPERATIONS.md for daily tasks
4. Bookmark TROUBLESHOOTING.md for quick reference
5. Review GLOSSARY.md for terminology

---

Copyright © 2025 Omnitouch Network Services Licensed to: Omnitouch