Omnix
Home Send a Notification

Outbound Messaging: Send a Notification

Omnix supports two main forms of developer-initiated outbound notifications: Templated Messages (required for cold outbound on WhatsApp) and System Messages (free-form notifications for open conversations).

This guide walks through when and how to use each type of message.

Messaging Endpoint Summary

Use Case API Method Channel Support Key Requirement
Cold Outbound / Marketing / Alerts sendTemplatedMessage WhatsApp, SMS, Email Template must exist in workspace
Transactional alerts on open threads sendSystemMessage SMS, Email, WhatsApp (under 24h) Existing conversationId
System alerts (auto-creates threads) sendSystemMessageToContact SMS, Email, WhatsApp (under 24h) contactId required

1. Templated Messages (sendTemplatedMessage)

Use this method when initiating a new conversation on WhatsApp (or when the 24-hour customer service window is closed) and you must use a pre-approved template.

Request Example

{
  "method": "OmnixGatewayRpc.sendTemplatedMessage",
  "params": {
    "subscriptionId": "sub_123456",
    "contactId": "con_789012",
    "channelType": "whatsapp",
    "templateName": "shipping_update_v2",
    "variables": {
      "customer_name": "Jane",
      "order_number": "94817",
      "carrier": "FedEx"
    }
  }
}

Key Considerations

  • Variables: Keys must match the placeholders configured in the templates UI. Missing variables will fail validation with MISSING_TEMPLATE_VARIABLES.
  • Language: Defaults to the workspace's default language. If templates are localized, you can pass a languageCode (e.g. es, de).

2. System Messages on Existing Conversations (sendSystemMessage)

If you have a webhook receiving incoming events (or if an agent has already engaged the user), you will have a conversationId. Use sendSystemMessage to send quick transactional updates or replies.

Request Example

{
  "method": "OmnixGatewayRpc.sendSystemMessage",
  "params": {
    "subscriptionId": "sub_123456",
    "conversationId": "conv_998877",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "metadata": {
      "alertType": "appointment_reminder"
    }
  }
}
  • If sent to a WhatsApp conversation where the 24-hour window has expired, this call will fail with WHATSAPP_WINDOW_CLOSED. In this case, you must fall back to sendTemplatedMessage.

3. System Messages directly to Contact (sendSystemMessageToContact)

If you do not track active conversation IDs locally but want to dispatch a free-form message to a contact's default channel, use sendSystemMessageToContact. Omnix will resolve the active conversation or start a new one automatically.

Request Example

{
  "method": "OmnixGatewayRpc.sendSystemMessageToContact",
  "params": {
    "subscriptionId": "sub_123456",
    "contactId": "con_789012",
    "channelType": "sms",
    "body": "Your invoice INV-2026-44 is ready for download."
  }
}

Channel Constraints

WhatsApp

  • 24-hour rule: You can send free-form system messages only within 24 hours of the contact's last inbound message. Outbound messages outside this window must be sent via sendTemplatedMessage.

SMS

  • Messages are formatted as plain text. Rich media is only supported if configured on your Twilio MMS endpoint.
  • Standard E.164 phone formats are strictly enforced.