Custom channel technical integration guide

Developer reference: HMAC signing, incoming and outgoing message formats, conversation events, read receipts, errors and code samples.

Oct 04, 2026

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

  1. Summary
  2. Getting the URL and the key
  3. Incoming: your system → Omnifox
  4. Delivered and read receipts (your system → Omnifox)
  5. Outgoing: Omnifox → your system
  6. Conversation events
  7. The conversation.read event
  8. Field mapping
  9. Limitations
  10. Code samples
  11. Checklist
  12. Troubleshooting

1. Summary

  • Incoming: POST https://omnifox.io/api/webhooks/custom/{TOKEN} with a JSON body and the X-Omnifox-Signature header = 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 distinct contact.id is a separate contact with its own conversation.
  • Outgoing: Omnifox sends a POST to your URL with X-Omnifox-Signature: sha256=… computed over "{ts}.{body}" and X-Omnifox-Timestamp. The body is fixed and includes recipient (your contact.id), content, agent (who is replying) and assigned_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_id for deduplication and sequence for ordering.
  • Read receipts both ways: your system reports delivered or read for our messages, and Omnifox sends conversation.read when 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_secret is optional: if you don't send it, Omnifox generates one.
  • settings.match_contacts_by_phone and settings.match_contacts_by_email (booleans, default false) turn on merging with existing contacts (see 3.6).
  • The 201 response includes data.id, data.webhook_url (the URL with the token) and data.signing_secret. This is the only time the key is returned: store it.
  • outbound_webhook_url must be http(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 by id protects 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. text becomes the caption of the first one; the rest carry their own caption.
  • IDs: the first uses id; the following ones id#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-level type (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.id is 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.id at an existing one.
  • Later messages: the contact is updated when phone, email, name or avatar_url arrive with a different value. Empty values never erase anything. Changes are listed in contact_updated.
    • Invalid phone → phone_invalid warning; phone belonging to another contact → not changed, phone_in_use warning.
    • 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.
  • Custom fields: contact.custom_fields writes 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_warnings as {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" and assignment_error (team_not_found or assignee_not_found). An impossible type (e.g. team_id: "abc") is a 422.
  • When it assigns: "assignment":"assigned" and assigned_to with team and agent (agent may be null if 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: read does not revert to delivered, and failed is 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"}]}, with result = updated, unchanged or not_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":"..."} (or message_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-Delivery and event_id.
  • A message may arrive before an event that happened slightly earlier (messages go out instantly, events through the queue). Order events by sequence and messages by sent_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) or reply (replied).
  • last_read_external_id is the id of the last message your user sent: you can mark all their messages up to that one as read.
  • At most one conversation.read every 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.id per user and a unique id per message.
  • You sign the exact raw body, ideally with X-Omnifox-Timestamp and a synced clock.
  • You retry with the same id on 5xx or network errors.
  • Attachments use public, permanent URLs.
  • If you assign, you check assignment and assignment_error in the response.
  • You decided whether to merge with existing contacts and created in Omnifox the custom fields you will send.
  • The receiver verifies sha256= over ts + "." + body, answers 2xx within 30 s (and 2xx to health_check), dispatches on event, deduplicates by event_id and orders events by sequence.
  • You download content.media_url right away.
  • You return an id for every message received and use it for delivered and read receipts.

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.
Was this helpful?

Related articles

Message us on WhatsApp