Custom Channel: mapping payload fields (inbound/outbound)

When the JSON your system sends or expects doesn't match Omnifox's default shape, field mapping lets you "translate" between the two formats without changing anything on your system's side.

Requirements

• A Custom Channel already created (see the "Connect a Custom Channel" article)
• The exact field names used in your inbound and outbound JSON payloads

How to configure the mapping

1. Open the channel (Channels → edit your Custom Channel) and expand the Field Mappings section.
2. Click Add to add a mapping row.
3. Pick the direction: In (inbound, messages coming from your system) or Out (outbound, messages Omnifox sends to you).
4. Fill in Source field (the field name as it appears in the source payload) and Target field (the matching field in the other format).
5. Repeat for every field you need to translate; delete rows with the trash icon.

Configuration

• Inbound (In): by default Omnifox looks for text (message text), sender (name of the person writing), id (external identifier), and type (image/photo/video/audio/voice/file/document — anything else is treated as text). If your system uses different names (e.g. body, from.name, msg_id), map them here.
• Outbound (Out): Omnifox's default body includes message_id, conversation_id, channel_id, recipient, type, content.text, content.media_url, content.caption, reply_to, sender.name, sender.phone, metadata, and sent_at. An outbound mapping defines which key on YOUR system corresponds to each of those fields (dot notation).
• Any source field missing from a message is sent as null — you don't have to map every field.

Example

If your system sends {"body": "Hi", "from": {"name": "Ana"}, "msg_id": "77"} as inbound, you'd map body → text, from.name → sender, msg_id → id. For outbound, if your API expects {"to": "...", "message": "..."}, you'd map to → recipient and message → content.text.

Tips

• Start without any mapping: if your system already uses the default names (text/sender/id/type), there's nothing to configure.
• The mapping is intentionally simple (no JSONPath, no transforms); for anything more advanced, adjust the format on your system's side instead.

Troubleshooting

• Inbound messages arrive blank or without a sender: check that the Source field matches the JSON key exactly, including case and dot notation for nested fields.
• Outbound messages reach your system with fields as null: double-check the mapping against the correct default key (e.g. content.text, not text).