Omnix
Home Contacts

Contacts

A contact is the central entity in Omnix — it represents a real person your business communicates with. Every conversation, message, and campaign is linked to a contact.

Contact Identifiers

Contacts can be identified by any of the following. You do not need all of them — just what you have:

FieldTypeFormatDescriptioncontactIdstringOmnix ObjectIdThe Omnix-assigned ID of an existing contactemailstringValid emailEmail addresssmsstringE.164 (+15551234567)Phone number for SMSvoicestringE.164Phone number for voice callswhatsappstringE.164Phone number for WhatsApp

At least one identifier is required. When multiple identifiers are provided, Omnix searches for an existing contact matching any of them.

E.164 Phone Format

All phone numbers must be in E.164 format:

+ [country code] [subscriber number]

✅  +15551234567
✅  +447911123456
❌  555-123-4567
❌  07911 123456

The ContactInfo Object

The ContactInfo object is used across multiple Gateway API methods — findOrCreateContact, requestOtp, and sendTemplatedMessage. Its full shape:

{
  contactId?:  string;   // Omnix contact ID (if known)
  firstName?:  string;
  lastName?:   string;
  email?:      string;   // must be valid email format
  sms?:        string;   // E.164
  voice?:      string;   // E.164
  whatsapp?:   string;   // E.164
  context?:    Record;  // arbitrary key-value store
}

All fields except the identifier are optional. At minimum, provide one identifier.

The context Field

The context field is a free-form key-value store you can use to attach your own application's data to an Omnix contact. It is merged with (not replaced by) any existing context on the contact.

Common uses:

{"context": {
    "app_user_id": "usr_abc123",
    "plan": "pro",
    "signup_source": "landing_page_v2",
    "crm_id": "SF-00123456"}}

  • Context data is visible in the contact detail panel within Omnix.

  • It can be referenced in message templates using {{context.app_user_id}} syntax.

  • Fields are merged shallowly — nested objects are replaced, not deep-merged.

Contact Upsert Behavior

findOrCreateContact is an upsert — it finds an existing contact or creates a new one:

  1. Match by contactId — if provided and valid, the contact is returned directly.

  2. Match by identifier — email, sms, voice, or whatsapp are checked in order. The first match wins.

  3. Create — if no match is found, a new contact is created with all provided fields.

When an existing contact is matched:

  • Name fields (firstName, lastName) are updated if provided.

  • context is merged with existing context.

  • Identifiers you did not provide are not changed.

The response includes isNew: true if a contact was created, isNew: false if one was matched.

Contact Merge

When the same person exists as two separate contacts (e.g., first created by email, later by WhatsApp number), they can be merged from within the Omnix UI or via the OmniContactsRpc (internal use). The merged contact retains both identifiers going forward.