Custom channel: field mapping
Use field mapping so Omnifox understands your system's JSON without changing it. It applies to incoming messages only.
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,idand, when relevant,mediaorattachmentswith 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
- Open the channel from Channels and edit it (or set it up while creating it).
- Under Field Mappings, click Add.
- 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. - On the right, pick the Omnifox field that value fills.
- 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
Related articles
-
WhatsApp (Meta) error codes: what they mean and what to do
A table of the most common Meta error codes when sending on WhatsApp (131026, 131047, 131049, 130497, 141006, 131031, 131056, 132000, 190, 368…) and how to fix each one.
-
How to connect Telegram
Connect a Telegram bot to your Omnifox inbox in minutes using BotFather.
-
Instagram and Facebook comments: reply and moderate from Omnifox
See and answer comments on your Facebook and Instagram posts and ads, publicly or privately, and set up automatic replies.
-
Sending and receiving videos on each channel: formats and size limits
Which videos you can send and receive on WhatsApp, Instagram, Messenger, Telegram, web chat and email, the real size limits, and what to do with a large video.
-
Move from WhatsApp QR to Coexistence or Cloud API
Once you're done testing with the QR code, move your number to the official connection: no caps, with templates and broadcasts, and no volume-based ban risk.