Overview#
During an active emergency, dispatchers route calls and messages through Twilio, then a department switches carriers to VoIP.ms for cost reasons, and suddenly every integration breaks. The Multi-Provider Omnichannel Messaging module unifies SMS, MMS, WhatsApp, RCS, and Signal messaging behind a single, portable provider adapter. Organisations swap carriers without rewriting dispatch logic; inbound callbacks route automatically to the right tenant; tenant credentials move with the organisation, not baked into platform settings.
The module provides a vendor-agnostic messaging dispatch layer that normalises carriers and secure messaging providers behind one governed workflow. Each provider connection supports outbound delivery, inbound verification, and message normalisation. Conversations and message history layer on top, tracking unread counts, starred messages, and last message content without exposing provider-specific payloads to dispatch users.
Key Features#
- Provider Abstraction: A common provider model hides carrier-specific request shapes, credentials, and delivery states, so dispatchers never branch on the provider.
- Multi-Channel Support: Carries SMS, MMS, WhatsApp, RCS (Twilio), SMS/MMS (VoIP.ms), and Signal on one normalised transport; channel is selected per message, not per tenant.
- Portable Per-Tenant Credentials: Credentials are stored in the organisation's own provider configuration, so credentials and configuration move with the tenant to any deployment.
- Automatic Inbound Routing: Tenant is resolved from inbound DID or phone number; webhooks from any provider route to the correct organisation without manual lookup tables.
- Vendor-Neutral Message Model: Normalised outbound and inbound message records abstract away channel prefixes, provider payload shapes, and vendor-specific metadata.
- Conversation State Tracking: Unread message counts, last message content, and starred message flags are persisted per conversation, enabling UI to show engagement state and quick reference without re-fetching history.
- Inbound Verification: Each provider connection verifies inbound origin using the verification model supported by that provider, with constant-time comparison where shared secrets or signatures are used.
- Provider Resolution Priority: Tenant-configured provider (from database) is tried first; platform/environment fallback only applies when the tenant has no own configuration, ensuring a tenant's carrier choice is never masked by platform settings.
Use Cases#
Multi-Carrier Deployment#
Organisations operating across multiple regions or cost-optimising their carrier mix provision different providers per tenant without touching code. A regional centre uses Twilio for reliability; a satellite office uses VoIP.ms for cost. Both dispatch through the same omnichannel service.
Carrier Migration#
When switching carriers, update the tenant's provider configuration and inbound and outbound messaging route to the new carrier. No redeployment and no downtime for message dispatch are required.
Encrypted Messaging with Scale#
Support WhatsApp and Signal alongside SMS/MMS, each with its own vendor (Twilio for business messaging, signal-cli for encrypted peer-to-peer). Dispatchers type a message once; the platform picks the right channel per contact.
Portable Emergency Communications#
When an agency deploys to a satellite or remote office with limited connectivity, carry omnichannel credentials in the tenant configuration. Messaging works immediately because there are no hard-coded secrets or environment assumptions.
Integration#
Organisations provision provider credentials in the tenant's own provider configuration. The messaging registry resolves the right provider for the channel and organisation, sends outbound messages through the selected provider, and returns a normalised delivery state.
Inbound messages are verified, normalised, routed to the correct conversation, and persisted with audit context. Per-tenant credentials and inbound verification prevent one organisation's messaging configuration from being reused by another, while automatic number routing avoids manual lookup tables for each deployment.
Open Standards#
- ITU-T E.164: Phone numbers are normalised to E.164 format before routing, conversation matching, and persistence.
- HMAC, RFC 2104: Providers that sign inbound events can be verified using keyed message authentication with constant-time comparison.
- JSON-RPC 2.0: Secure messaging providers that expose JSON-RPC style envelopes can be normalised into the same conversation model.
- ISO 8601: Inbound message timestamps (received timestamp) and all real-time WebSocket broadcast timestamps are expressed in ISO 8601 format, ensuring interoperability across time zones.
- RFC 4122 UUID: Conversations, messages, channels, and verification records are all keyed by RFC 4122 UUIDs, giving stable, globally unique identifiers across multi-tenant deployments.
- WebSocket (RFC 6455): Real-time dispatcher updates (new messages, conversation state changes) are pushed to PSAP dashboards over WebSocket connections, scoped per tenant.
- HTTPS / TLS (RFC 2818): Outbound provider requests and inbound provider callbacks are expected to use encrypted transport.
Security & Compliance#
- Constant-Time Signature Verification: All webhook signatures are compared in constant time to prevent timing-based attacks that could distinguish valid from invalid signatures.
- Portable Credentials: Provider secrets are stored per-tenant, reducing the surface for cross-tenant credential leaks and enabling secure multi-tenant isolation.
- Webhook Authentication: Every inbound webhook is authenticated against the provider's shared secret or HMAC signature before the payload is normalised or persisted, preventing spoofed messages.
- E.164 Normalisation: Phone numbers are normalised to E.164 format (leading
+, no spaces) across all channels, preventing injection attacks and number mismatch issues. - Secrets Logging Safety: Credential resolution failures are logged without exposing key values; only the tenant ID and resolution status are recorded.
Last Reviewed: 2026-06-04 Last Updated: 2026-06-05