Custom channel technical integration guide
Developer reference: HMAC signing, incoming and outgoing message formats, conversation events, read receipts, errors and code samples.
A guide for the developer connecting an external system to Omnifox through the custom channel (Custom Channel). If the channel has not been created yet, start with Custom channel: what it is and how to set it up.
Examples use placeholders: {TOKEN} (last part of the incoming URL), {SECRET} (the channel's secret key), {API_TOKEN}, {WORKSPACE_ID} and https://your-system.com/omnifox (your outgoing URL). Never paste real keys into tickets or logs.
Contents
- Summary
- Getting the URL and the key
- Incoming: your system → Omnifox
- Delivered and read receipts (your system → Omnifox)
- Outgoing: Omnifox → your system
- Conversation events
- The
conversation.readevent - Field mapping
- Limitations
- Code samples
- Checklist
- Troubleshooting
1. Summary
- Incoming:
POST https://omnifox.io/api/webhooks/custom/{TOKEN}with a JSON body and theX-Omnifox-Signatureheader = hex HMAC-SHA256 of the raw body using the secret key. Optional (recommended):X-Omnifox-Timestamp, in which case you sign"{ts}.{body}". - Every message identifies the user with
contact.id(their ID in your system). Without it, Omnifox returns 422. Each distinctcontact.idis a separate contact with its own conversation. - Outgoing: Omnifox sends a
POSTto your URL withX-Omnifox-Signature: sha256=…computed over"{ts}.{body}"andX-Omnifox-Timestamp. The body is fixed and includesrecipient(yourcontact.id),content,agent(who is replying) andassigned_agent. - Your system answers 2xx. On 5xx or timeout, Omnifox retries; a 4xx is final.
- One secret key for both directions.
- Conversation events (assigned, transferred, closed, reopened, AI handoff, read…) reach the same outgoing URL, with
event_idfor deduplication andsequencefor ordering. - Read receipts both ways: your system reports delivered or read for our messages, and Omnifox sends
conversation.readwhen a person reads the chat.
2. Getting the URL and the key
On screen
Under Channels → Connect New Channel → Custom Channel (or when editing the channel) you will find the Incoming Webhook URL (with a 32-character token that does not change on edit) and the Secret Key. The Regenerate button creates a new key: you then have to save the channel and update the key in your system.
On save, if there is an outgoing URL, Omnifox sends {"event":"health_check","type":"health_check"} signed exactly like a real outgoing message, with a 5 s timeout. Your receiver must answer 2xx or the channel is not saved.
Via the API
POST https://omnifox.io/api/v1/channels
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
"workspace_id": {WORKSPACE_ID},
"type": "custom",
"name": "My external system",
"settings": { "outbound_webhook_url": "https://your-system.com/omnifox" }
}
- The token is created under API Keys and needs permission to manage channels in that workspace.
credentials.signing_secretis optional: if you don't send it, Omnifox generates one.settings.match_contacts_by_phoneandsettings.match_contacts_by_email(booleans, defaultfalse) turn on merging with existing contacts (see 3.6).- The
201response includesdata.id,data.webhook_url(the URL with the token) anddata.signing_secret. This is the only time the key is returned: store it. outbound_webhook_urlmust behttp(s); otherwise 422. If the plan does not include custom channels: 402.- There is no endpoint to edit the channel via the API: changes are made on screen.
Note:
https://omnifox.io/api/webhooks/custom/{CHANNEL_ID}also works, but we recommend the token URL, which identifies the channel unambiguously.
3. Incoming: your system → Omnifox
3.1 Request
| Method | POST |
| URL | https://omnifox.io/api/webhooks/custom/{TOKEN} |
Content-Type |
application/json. The body must be a JSON object with a single message. |
X-Omnifox-Signature |
Required. Signature (3.2). Also accepted as the ?signature= query parameter. |
X-Omnifox-Timestamp |
Optional. Unix seconds. If present, it changes what is signed and protects against replays. |
| Processing | Synchronous: when you get the 200, the message is already in the inbox. |
3.2 Signature
without timestamp: signature = hex( HMAC_SHA256( key = SECRET, message = raw_body ) )
with timestamp: signature = hex( HMAC_SHA256( key = SECRET, message = ts + "." + raw_body ) )
(ts = exact value of X-Omnifox-Timestamp; max skew ±300 s)
- Hexadecimal, upper or lower case, with or without the
sha256=prefix. Base64 is not accepted. - Sign the same bytes you send. Do not re-serialize the JSON after signing.
- We recommend sending
X-Omnifox-Timestamp: a captured request then cannot be replayed later. Requests without a timestamp are accepted, but only deduplication byidprotects you.
3.3 Body
{
"id": "msg-1001",
"type": "text",
"text": "Hi, I'd like some information",
"contact": {
"id": "user-42",
"name": "Ana Pérez",
"phone": "+593991234567",
"email": "[email protected]",
"avatar_url": "https://cdn.example.com/ana.jpg",
"custom_fields": { "current_plan": "pro" }
},
"team": "Sales",
"assignee_email": "[email protected]"
}
| Field | Type | Req. | Description |
|---|---|---|---|
contact.id |
string | Yes | The user's ID in your system (max 191 characters). Accepted aliases: sender_id, user_id or sender.id. |
contact.name |
string | No | Name. Alias: sender as a string. |
contact.phone |
string | No | Only stored if it has 6 to 20 digits, with an optional + (spaces are ignored). |
contact.email |
string | No | Must be a valid email; otherwise 422. |
contact.avatar_url |
string | No | Absolute http(s) URL; otherwise 422. |
contact.custom_fields |
object | No | {"internal_name": value} for contact custom fields that already exist in Omnifox. |
team_id / team |
integer / string | No | Team to assign (3.7). team is the name, case-insensitive. |
assignee_id / assignee_email |
integer / string | No | Agent to assign (3.7). |
id |
string | Recommended | Message ID in your system (max 180). Used for deduplication. Alias: message_id. If missing, there is no deduplication. |
text |
string | Yes, if no attachments | Message text. No text and no attachments → 422. |
type |
string | No | text, image/photo/sticker, video, audio/voice, file/document. With attachments, it is inferred if missing. |
media |
object | No | One attachment: url (required, public), caption, mime_type, filename. |
attachments |
object or list | No | One or more attachments with the same shape (plus type). Takes priority over media. |
Type conversion: numbers and booleans are converted to strings ("id": 777 → "777"). null and "" count as missing. An object or list where text is expected → 422 with the field detail. Leading and trailing spaces are trimmed.
Not supported on incoming: external threads or conversations (Omnifox picks the conversation by contact and channel), quoting a message, a message date (the reception time is used), reactions, base64 or multipart, or several messages per request (a list as the body → 422).
3.4 Responses
| Case | HTTP | Body |
|---|---|---|
| Stored | 200 |
{"ok":true,"message_id":"3747","message_ids":["3747"],"conversation_id":"629","contact_id":"1607","duplicate":false} |
Repeated (same id) |
200 |
Same, with the original IDs and "duplicate":true |
| Missing signature | 401 |
{"code":40100,"message":"Missing signature: …"} |
| Invalid timestamp or more than 300 s skew | 401 |
{"code":40100,"message":"Invalid or stale X-Omnifox-Timestamp …"} |
| Wrong signature | 403 |
{"code":40300,"message":"Invalid signature"} |
| Omnifox account suspended | 403 |
{"code":40300,"message":"The Omnifox account that owns this channel is suspended; …"} |
| Unknown token | 404 |
{"code":40400,"message":"Unknown channel"} |
| Channel deactivated | 404 |
{"code":40400,"message":"Channel not found"} |
| Body is not a JSON object | 422 |
{"code":42200,"message":"The body must be a JSON object …","details":{…}} |
| Invalid body | 422 |
{"code":42200,"message":"The message body is not valid.","details":{"contact.id":["Required: …"]}} |
| Could not be stored | 500 |
{"code":50000,"message":"The message could not be stored. It is safe to retry with the same id."} |
If the message includes contact data, custom fields or assignment, the 200 response adds:
{"ok":true,"message_id":"3799","message_ids":["3799"],"conversation_id":"632","contact_id":"1612","duplicate":false,
"contact_updated":["display_name","phone","email"],
"custom_fields_updated":["current_plan"],
"assignment":"assigned",
"assigned_to":{"team":{"id":"2","name":"Sales"},"agent":null},
"contact_warnings":[
{"field":"contact.custom_fields.does_not_exist","code":"custom_field_unknown","message":"No contact custom field with that name exists in this workspace; ignored."}
]}
IDs are internal Omnifox IDs (strings). message_ids has one entry per message created (one per attachment).
When to retry: on 5xx or a network error, retry with the same id; if it had already been stored you will get duplicate:true. On 4xx, fix the request: sending it again unchanged will not help.
3.5 Attachments
- Each attachment creates one message.
textbecomes the caption of the first one; the rest carry their owncaption. - IDs: the first uses
id; the following onesid#2,id#3… (deduplication works for each). - Omnifox does not download the file: it stores the URL and the inbox displays it from there. The URL must be public and permanent.
- Type of each attachment: its own
type→ the top-leveltype(if there is a single attachment) →mime_type(image/*,video/*,audio/*, anything else = file) → URL extension.
3.6 Contact and conversation
- The user's identity is
contact.id: the first message creates the contact; later ones go to that contact and its open conversation. - First message from a new
contact.id, depending on the channel's Merge with existing contacts checkboxes (off by default):- Off: a separate contact is created. If the phone number already belongs to another contact, the new one is created without a phone number and the response warns
phone_in_use. The email is stored anyway. - Merge by phone: if a contact with that phone exists, the
contact.idis linked to it. - Merge by email: if there was no phone match, Omnifox looks it up by email (exact, case-insensitive).
- Risk: different people sharing a phone or email would end up in the same contact. Linking does not merge contacts: it only points the
contact.idat an existing one.
- Off: a separate contact is created. If the phone number already belongs to another contact, the new one is created without a phone number and the response warns
- Later messages: the contact is updated when
phone,email,nameoravatar_urlarrive with a different value. Empty values never erase anything. Changes are listed incontact_updated.- Invalid phone →
phone_invalidwarning; phone belonging to another contact → not changed,phone_in_usewarning. - The name is only replaced if the current one is what your system sent last time. If someone edited it in Omnifox, it is kept and you get
name_kept_manual_edit. - The email is stored in lowercase and may repeat across contacts.
- Invalid phone →
- Custom fields:
contact.custom_fieldswrites to contact custom fields already created in Omnifox (by internal name), with the same validation as the rest of the app. Unknown name →custom_field_unknown(no fields are created); invalid value →custom_field_invalid. - Warnings come in
contact_warningsas{field, code, message}and never prevent the message from being stored. - Incoming messages trigger the usual: workflows, the channel's AI agent, assignment and notifications.
3.7 Assigning a team or agent
| Field | What it does |
|---|---|
team_id or team |
Assigns the team and applies its distribution strategy. Must be a team in the channel's workspace. If both are sent, team_id wins. |
assignee_id or assignee_email |
Assigns that agent (workspace member). If a team is also sent, the team is assigned first and then the agent. |
- It only applies if the conversation is new or has no person or team assigned. Otherwise the response includes
"assignment":"skipped_already_assigned"and nothing changes. - The message is always stored. If the team or agent does not exist: 200 with
"assignment":"error"andassignment_error(team_not_foundorassignee_not_found). An impossible type (e.g.team_id: "abc") is a 422. - When it assigns:
"assignment":"assigned"andassigned_towithteamandagent(agentmay benullif the team uses a shared strategy or nobody is available). - It does not pause the AI agent. If you don't send these fields, the channel's automatic routing stays in place.
4. Delivered and read receipts (your system → Omnifox)
Use the same incoming URL and the same signature with this body:
{ "type": "status", "status": "read", "message_id": "mysys-3780", "timestamp": 1791043535 }
or several at once (max 100):
{ "statuses": [
{ "status": "delivered", "message_id": "mysys-3780", "timestamp": "2026-10-03T17:05:34Z" },
{ "status": "failed", "message_id": "mysys-3781", "error": { "code": "X1", "message": "undeliverable" } }
] }
| Field | Description |
|---|---|
status |
delivered, read or failed. |
message_id |
The ID your receiver returned when it got the message (5.5). Omnifox's own message_id is also accepted. To avoid ambiguity you can send external_id instead: then only your ID is looked up. |
timestamp |
Optional: Unix seconds or ISO-8601. |
error |
Optional, with failed: {code, message}. Shown in the inbox. |
- Only outgoing messages of that channel are looked up.
- Never goes backwards:
readdoes not revert todelivered, andfailedis only accepted if the message was not yet delivered or read. Repeating a receipt is harmless. - Response:
{"ok":true,"updated":1,"results":[{"message_id":"3780","status":"read","result":"updated"}]}, withresult=updated,unchangedornot_found. - If none was found: 404
Message not found in this channel.Invalid body: 422. No signature: 401. Wrong signature: 403.
5. Outgoing: Omnifox → your system
5.1 What is sent
Replies from human agents (inbox or API), the AI agent and workflows or automations. Internal notes are not sent. Without an outgoing URL, the message is marked as failed with the reason "missing outgoing webhook URL".
5.2 Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
X-Omnifox-Signature |
sha256=<lowercase hex> |
X-Omnifox-Timestamp |
Unix seconds |
X-Omnifox-Channel-Type |
custom |
X-Omnifox-Delivery |
UUID of this delivery |
5.3 Signature
expected = "sha256=" + hex( HMAC_SHA256( key = SECRET, message = X-Omnifox-Timestamp + "." + raw_body ) )
Verify against the raw bytes and compare in constant time. Omnifox does not enforce a time window on your side; we recommend rejecting anything more than 300 s off.
5.4 Body (fixed)
{
"event": "message",
"event_id": "message-3729",
"occurred_at": "2026-10-03T15:51:30+00:00",
"message_id": "3729",
"conversation_id": "625",
"channel_id": "18",
"recipient": "user-42",
"contact": { "id": "user-42", "name": "Ana Pérez", "phone": null, "email": null },
"omnifox_contact_id": "1603",
"type": "text",
"content": { "text": "Hi Ana! How can I help?", "media_url": null, "caption": null, "mime_type": null, "filename": null },
"reply_to": null,
"agent": { "type": "human", "id": "28", "name": "Laura Gómez", "avatar_url": null },
"assigned_agent": { "type": "human", "id": "28", "name": "Laura Gómez", "avatar_url": null },
"metadata": {},
"sent_at": "2026-10-03T15:51:30+00:00"
}
| Field | Content |
|---|---|
event |
"message". The test on save uses "health_check"; events use the names in section 6. |
event_id |
message-<message_id>, stable, for deduplication. |
message_id |
The message ID in Omnifox. Also stable if the agent clicks "Retry". |
recipient |
Your contact.id: who to deliver the message to. |
contact |
id (= recipient), name, phone, email of the contact in Omnifox. |
type |
text, image, video, audio, file, sticker, location, template, interactive… |
content.text |
Text (the caption, for media). |
content.media_url |
For media, an absolute downloadable URL. If the file was uploaded in Omnifox, it is a signed URL that expires within a few hours (6 h at most): download it right away. |
reply_to |
External ID of the quoted message (if it quotes one of yours, the id you sent). |
agent |
Who is sending: {"type":"human",…}, {"type":"ai",…} (AI agent) or {"type":"system","id":null,"name":<workflow name or null>}. |
assigned_agent |
The conversation's assignee: the person; if none, the AI agent; otherwise null. |
metadata |
Always an object ({} when empty). Informational content, not guaranteed. |
sent_at |
ISO-8601 with time zone. |
5.5 Expected response and retries
- Answer 2xx within 30 s and queue any heavy work.
- Optional: return
{"id":"..."}(ormessage_id/external_id). That ID is stored as the message's external ID and you will use it for receipts (section 4). - 5xx or network error: up to 3 attempts, waiting 1 s and 2 s, with the same body, signature and
X-Omnifox-Delivery. - 4xx: final rejection, no retry; the message is marked as failed. The agent can click "Retry": that is a new delivery with the same
message_id.
6. Conversation events
They reach the same outgoing URL, with the same signature and headers (plus X-Omnifox-Event), only for conversations on that channel. Each event can be switched off under Events to send; all are on by default. Messages are always sent.
| Event | When | changes |
|---|---|---|
conversation.created |
A new conversation opens | status: {from: null, to} |
conversation.assigned |
Assigned or transferred to a person and/or team (transfer = from not null) |
assigned_agent and/or team |
conversation.unassigned |
The person and/or team is removed | same, with to: null |
conversation.pending / snoozed / resolved / closed |
Status changes (including auto-close for inactivity) | status: {from, to} |
conversation.reopened |
Back to open | status: {from, to: "open"} |
conversation.priority_changed |
Priority changes (urgent, high, medium, low, none) |
priority: {from, to} |
conversation.tag_added / tag_removed |
A tag is added or removed | {} plus tag: {id, name} |
conversation.ai_handoff |
The AI hands the conversation to a person or team | ai_agent, ai_paused, plus reason (handoff, human_takeover…) |
conversation.ai_paused |
The AI is paused without a handoff | same as ai_handoff |
conversation.ai_resumed |
The AI is resumed | ai_agent: {from: null, to}, ai_paused: {from: true, to: false} |
conversation.read |
A person read the conversation (section 7) | is_unread: {from: true, to: false} |
There is no generic status_changed: any event whose changes contains status is a status change.
6.1 Body
{
"event": "conversation.assigned",
"event_id": "5b0e9a1c-7d2f-4c39-9f0e-1a2b3c4d5e6f",
"occurred_at": "2026-10-03T17:00:18.104+00:00",
"sequence": 3,
"channel_id": "20",
"conversation_id": "630",
"recipient": "user-42",
"contact": { "id": "user-42", "name": "Ana Pérez", "phone": null, "email": null },
"omnifox_contact_id": "1608",
"actor": { "type": "human", "id": "28", "name": "Laura Gómez", "avatar_url": null, "source": "user" },
"status": "open",
"priority": "none",
"assigned_agent": { "type": "human", "id": "30", "name": "Carlos Ruiz", "avatar_url": null },
"team": null,
"changes": {
"assigned_agent": {
"from": { "type": "human", "id": "29", "name": "Marta León", "avatar_url": null },
"to": { "type": "human", "id": "30", "name": "Carlos Ruiz", "avatar_url": null }
}
}
}
| Field | Content |
|---|---|
event_id |
Unique UUID, identical on every retry: deduplicate on it. |
sequence |
Order per conversation (1, 2, 3…). It may have gaps or be null; in that case use occurred_at. |
actor |
Who made the change: type human, ai or system, and source user, ai, api, workflow or system. |
status, priority, assigned_agent, team |
State after the change. |
changes |
What changed, always {field: {from, to}}. |
| Extras | tag (tags), reason (AI), last_read_message_id, last_read_external_id, read_at and read_via (read). |
A single change can produce several events: for example, an AI handoff to a team sends conversation.assigned and conversation.ai_handoff.
6.2 Delivery, retries and ordering
- Events are sent through a queue (usually within seconds); an agent's action never waits for your system.
- 15 s timeout per attempt. 2xx = delivered (your response body is ignored).
- 4xx = final. 5xx, network error or timeout: up to 5 attempts, waiting 30 s, 2 min, 10 min and 30 min. Each retry has a new timestamp and signature, but the same
X-Omnifox-Deliveryandevent_id. - A message may arrive before an event that happened slightly earlier (messages go out instantly, events through the queue). Order events by
sequenceand messages bysent_at. - Keep processed
event_ids (7 days is enough) and ignore repeats.
7. The conversation.read event
Sent when a person leaves the conversation read (the unread counter drops to 0):
{
"event": "conversation.read",
"event_id": "47dad59d-f43f-4bd3-9122-d097b962b17c",
"sequence": 26,
"recipient": "user-42",
"actor": { "type": "human", "id": "28", "name": "Laura Gómez", "avatar_url": null, "source": "user" },
"changes": { "is_unread": { "from": true, "to": false } },
"last_read_message_id": "3781",
"last_read_external_id": "msg-1002",
"read_at": "2026-10-03T17:06:03+00:00",
"read_via": "open"
}
read_via:open(opened the chat, or had it open when the message arrived) orreply(replied).last_read_external_idis theidof the last message your user sent: you can mark all their messages up to that one as read.- At most one
conversation.readevery 10 s per conversation. If nothing was unread, nothing is sent. - It is not sent when the AI "reads" the chat or when it is marked read via the API. It is also not sent if an admin opens someone else's chat and the workspace is set not to mark it as read.
8. Field mapping
If your system cannot send the format in 3.3, configure on screen which path in your JSON fills each Omnifox field. It is incoming only, the signature is checked against your original JSON, and mapped values take priority over the standard field. Details and an example in Custom channel: field mapping. There is no outgoing mapping: the outgoing body is always the one in 5.4.
9. Limitations
| Feature | Status |
|---|---|
| 24-hour window | Does not apply (it is a Meta rule). |
| AI agent | Yes, if the channel has one assigned; it goes out with agent.type = "ai". |
| Read receipts | Yes, both ways. Omnifox's read signal is per conversation, not per message. |
| "Typing…" indicator | No. |
| Editing or deleting messages, reactions | No. |
| Multiple outgoing URLs | No, one per channel. |
| Several messages per request | No (several attachments, yes). |
| Base64 or multipart | No, URLs only. |
| Replay protection | Only if you send X-Omnifox-Timestamp. |
10. Code samples
10.1 Send a message (bash + openssl)
#!/usr/bin/env bash
set -euo pipefail
URL="https://omnifox.io/api/webhooks/custom/{TOKEN}"
SECRET="{SECRET}"
# Build the body ONCE and sign exactly those bytes.
BODY='{"id":"msg-1001","text":"Hi, I would like some information","contact":{"id":"user-42","name":"Ana Pérez","phone":"+593991234567"}}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
curl -sS -w '\nHTTP %{http_code}\n' -X POST "$URL" \
-H "Content-Type: application/json" \
-H "X-Omnifox-Timestamp: $TS" \
-H "X-Omnifox-Signature: $SIG" \
--data-binary "$BODY"
Use printf '%s' (not echo, which adds a newline) and --data-binary (not -d). A read receipt uses the same URL and signature with BODY='{"type":"status","status":"read","message_id":"mysys-3780"}'.
10.2 Send a message (Node 18+)
import crypto from 'node:crypto';
const body = JSON.stringify({ id: 'msg-1001', text: 'Hi', contact: { id: 'user-42', name: 'Ana Pérez' } });
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', process.env.OMNIFOX_SECRET).update(`${ts}.${body}`, 'utf8').digest('hex');
const res = await fetch(process.env.OMNIFOX_INCOMING_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Omnifox-Timestamp': ts, 'X-Omnifox-Signature': sig },
body, // exactly the same string you signed
});
console.log(res.status, await res.json());
10.3 Minimal receiver (Node + Express)
const express = require('express');
const crypto = require('crypto');
const SECRET = process.env.OMNIFOX_SECRET;
const seen = new Set(); // processed event_ids; use Redis or your database in production
const app = express();
// RAW body: express.json() loses the exact bytes that were signed.
app.post('/omnifox', express.raw({ type: '*/*', limit: '2mb' }), (req, res) => {
const raw = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
const ts = req.get('X-Omnifox-Timestamp') || '';
const sig = req.get('X-Omnifox-Signature') || '';
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
.update(Buffer.concat([Buffer.from(ts + '.', 'utf8'), raw])).digest('hex');
const a = Buffer.from(sig), b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).end();
if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end();
const body = JSON.parse(raw.toString('utf8'));
if (body.event_id && seen.has(body.event_id)) return res.json({ ok: true, duplicate: true });
if (body.event_id) seen.add(body.event_id);
switch (body.event) {
case 'health_check':
break;
case 'message':
// Deliver body.content to user body.recipient and return your ID for receipts.
return res.json({ id: `mysys-${body.message_id}` });
case 'conversation.read':
console.log('read up to', body.last_read_external_id);
break;
default:
console.log(body.event, body.sequence, body.changes);
}
return res.json({ ok: true });
});
app.listen(3000);
10.4 Verify and send in PHP
<?php
// Receiver
$secret = getenv('OMNIFOX_SECRET');
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_OMNIFOX_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_OMNIFOX_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if ($sig === '' || ! hash_equals($expected, $sig) || ! ctype_digit($ts) || abs(time() - (int) $ts) > 300) {
http_response_code(401);
exit;
}
$msg = json_decode($raw, true);
if (($msg['event'] ?? '') === 'health_check') { http_response_code(200); exit; }
header('Content-Type: application/json');
echo json_encode(['id' => 'mysys-' . ($msg['message_id'] ?? '')]);
// Sender: sign the same string you send
$body = json_encode(['id' => 'msg-1', 'text' => 'Hi', 'contact' => ['id' => 'user-42', 'name' => 'Ana']]);
$ts = (string) time();
$sig = hash_hmac('sha256', $ts . '.' . $body, $secret);
// POST $body with Content-Type: application/json, X-Omnifox-Timestamp: $ts and X-Omnifox-Signature: $sig
11. Checklist
- You have the token URL and the current secret key.
- Every POST is a JSON object with a stable
contact.idper user and a uniqueidper message. - You sign the exact raw body, ideally with
X-Omnifox-Timestampand a synced clock. - You retry with the same
idon 5xx or network errors. - Attachments use public, permanent URLs.
- If you assign, you check
assignmentandassignment_errorin the response. - You decided whether to merge with existing contacts and created in Omnifox the custom fields you will send.
- The receiver verifies
sha256=overts + "." + body, answers 2xx within 30 s (and 2xx tohealth_check), dispatches onevent, deduplicates byevent_idand orders events bysequence. - You download
content.media_urlright away. - You return an
idfor every message received and use it fordeliveredandreadreceipts.
12. Troubleshooting
| Symptom | Likely cause |
|---|---|
401 Missing signature |
X-Omnifox-Signature is missing. |
401 stale X-Omnifox-Timestamp |
Clock off by more than 5 min, or timestamp in milliseconds. |
403 Invalid signature |
Wrong key (was it regenerated?), JSON re-serialized after signing, echo adding a newline or curl -d, timestamp sent but not signed (or vice versa), or a base64 signature. |
404 Unknown channel / Channel not found |
Token copied wrong, channel deleted or deactivated. |
422 contact.id |
The user ID is missing, or the mapping cannot find it. |
200 with duplicate:true |
That id had already been received. |
skipped_already_assigned |
The conversation already had a person or team. |
team_not_found / assignee_not_found |
The team or agent does not exist in the channel's workspace. The message was stored. |
phone_in_use |
That phone belongs to another contact; it was not moved. |
custom_field_unknown |
No contact custom field with that internal name exists. |
| All messages in the same contact | You are sending the same contact.id for everyone. |
| The channel won't save when clicking Continue | Your outgoing URL did not answer 2xx to the health_check within 5 s. |
| Failed replies in the inbox | The outgoing URL is missing or your receiver returned 4xx (e.g. it rejected the signature). |
content.media_url returns 403 later |
The signed URL expired. |
| Duplicates at your receiver | Retries or a manual "Retry": deduplicate by event_id. |
| An event never arrives | It is switched off under Events to send, there is no outgoing URL, or your receiver returned 4xx. |
| Receipt returns 404 | The message_id is neither the one your receiver returned nor Omnifox's, or it belongs to another channel. |
conversation.read never arrives |
It was already read, the AI or an API token read it, or less than 10 s passed since the previous one. |
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.