Custom channel: field mapping

Use field mapping so Omnifox understands your system's JSON without changing it. It applies to incoming messages only.

Jul 11, 2026

Field mapping on the custom channel is for when your system cannot send messages in Omnifox's standard format. Instead of changing your system, you tell Omnifox where each value lives in your JSON.

Note: mapping is incoming only (messages coming from your system). What Omnifox sends to your outgoing URL always has the same format, described in the technical integration guide: your system has to adapt to it.

When you need it

  • You don't need it if your system already sends contact.id, text, id and, when relevant, media or attachments with those names.
  • You do need it if your system already produces its own JSON that you cannot change, for example {"data":{"user":{"uid":"..."}}}.

How to set it up

  1. Open the channel from Channels and edit it (or set it up while creating it).
  2. Under Field Mappings, click Add.
  3. On the left, type the path of the value in your JSON, using dots: data.user.id. For lists, use the position number: items.0.url. You may start the path with $. if you prefer.
  4. On the right, pick the Omnifox field that value fills.
  5. Repeat for each value and click Continue to save.

Available Omnifox fields

Omnifox field What it is for
Contact ID (required) The user's ID in your system. If it arrives neither directly nor through a mapping, the message is rejected.
Contact name, phone, email and photo URL Contact details.
Message text The text.
Message type text, image, video, audio or file.
Message ID (deduplication) Prevents duplicates if your system resends the same message.
Media URL, caption, MIME type and file name One attachment. If you map any of these, the message's attachments list is ignored.
Attachments list A full list of attachments.
Team (id or name) and Agent (id or email) Who a new or unassigned conversation goes to.
Custom field: name One appears for each contact custom field created in your workspace.

Rules

  • Mapped values take priority over a field with the standard name.
  • If the path does not exist in a given message, that row simply does nothing.
  • The message signature is always checked against your original JSON; the mapping is applied afterwards.
  • Paths are simple: no wildcards, filters or transformations.

Example

Your system sends:

{"data":{"user":{"uid":"user-M","nombre":"Mario"},"msg":{"mid":"m-1","cuerpo":"Hello","foto":"https://cdn.example.com/a.jpg"}}}

With these rows:

Path in your JSON Omnifox field
data.user.uid Contact ID
data.user.nombre Contact name
data.msg.cuerpo Message text
data.msg.mid Message ID
data.msg.foto Media URL

Omnifox creates the contact user-M named "Mario" and an image message with the caption "Hello".

Common issues

  • "contact.id required" error: the contact ID path does not match your JSON. Check capitalization, dots and nesting levels.
  • The message arrives without text or without the image: the path for that value is misspelled or points to the wrong level.
  • My system expects a different format for replies: there is no outgoing mapping; adapt your receiver to Omnifox's fixed format.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp