Omnix
Home Your First API Call

Your First API Call

This guide walks through three real API calls that cover the most common integration pattern: verify your key → register a contact → send them a message.

Prerequisites

  • A running Omnix instance (cloud or self-hosted)
  • An API key — see Authentication
  • A message template created in your workspace (Admin → Templates)
  • curl or any HTTP client

Set your base URL and API key as environment variables to keep examples clean:

export OMNIX_URL="https://your-omnix-instance.com"
export OMNIX_KEY="your_api_key_here"

Step 1 — Verify Your Key with ping

curl -s -X POST "$OMNIX_URL/api/rpc" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $OMNIX_KEY" \
  -d '{"method": "OmnixGatewayRpc.ping", "params": {}}'

Success response:

{
  "success": true,
  "message": "Pong!",
  "subscriptionId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "userId": "64a1b2c3d4e5f6a7b8c9d0e2"
}

Save the subscriptionId — it appears in error logs and is useful for support requests.

If you get a 401, double-check your x-api-key header name and value. See Authentication.

Step 2 — Find or Create a Contact

Omnix uses a single upsert operation — you never need to check if a contact exists before creating one. Pass any identifier you have (email, phone, or WhatsApp number) and Omnix will match an existing contact or create a new one.

curl -s -X POST "$OMNIX_URL/api/rpc" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $OMNIX_KEY" \
  -d '{
    "method": "OmnixGatewayRpc.findOrCreateContact",
    "params": {
      "contactInfo": {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]",
        "sms": "+15551234567",
        "context": {
          "app_name": "MyApp",
          "app_user_id": "usr_abc123"
        }
      }
    }
  }'

Success response:

{
  "contactId": "64c9f1a2b3d4e5f6a7b8c9d0",
  "isNew": true,
  "displayName": "Jane Smith"
}
  • isNew: true means a contact was created. isNew: false means an existing contact was found and updated.
  • The context field lets you store your own application's reference data (user IDs, plan names, etc.) on the contact — it merges with any existing context.
  • For full parameter details, see the OmnixGatewayRpc reference.

Step 3 — Send a Templated Message

Use a template you've created in your workspace. The templateName must match exactly (case-sensitive).

curl -s -X POST "$OMNIX_URL/api/rpc" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $OMNIX_KEY" \
  -d '{
    "method": "OmnixGatewayRpc.sendTemplatedMessage",
    "params": {
      "contactInfo": {
        "email": "[email protected]"
      },
      "channelType": "sms",
      "templateName": "welcome_message",
      "templateData": {
        "first_name": "Jane",
        "account_type": "Pro"
      },
      "createConversation": true
    }
  }'

Success response:

{
  "success": true,
  "messageId": "msg_64d0a1b2c3d4e5f6",
  "conversationId": "conv_64d0a1b2c3d4e5f7"
}
  • createConversation: true opens a conversation in the Omnix Unified Inbox for this message, so your team can follow up manually if needed.
  • If you do not want a conversation opened (notification-only), set createConversation: false.

What's Next

You've authenticated, created a contact, and sent a message. From here: