Guía técnica de integración del canal personalizado

Referencia para desarrolladores: firma HMAC, formato de mensajes entrantes y salientes, eventos de conversación, acuses de lectura, errores y ejemplos de código.

Oct 04, 2026

Guía para el desarrollador que conecta un sistema externo con Omnifox mediante el canal personalizado (Custom Channel). Si todavía no creaste el canal, empieza por Canal personalizado: qué es y cómo configurarlo.

En los ejemplos se usan marcadores: {TOKEN} (parte final de la URL entrante), {SECRET} (clave secreta del canal), {API_TOKEN}, {WORKSPACE_ID} y https://tu-sistema.com/omnifox (tu URL saliente). Nunca pegues claves reales en tickets ni en registros.

Índice

  1. Resumen
  2. Obtener la URL y la clave
  3. Entrante: tu sistema → Omnifox
  4. Acuses de entregado y leído (tu sistema → Omnifox)
  5. Saliente: Omnifox → tu sistema
  6. Eventos de conversación
  7. Evento conversation.read
  8. Mapeo de campos
  9. Limitaciones
  10. Ejemplos de código
  11. Lista de verificación
  12. Problemas frecuentes

1. Resumen

  • Entrante: POST https://omnifox.io/api/webhooks/custom/{TOKEN} con un JSON y el encabezado X-Omnifox-Signature = HMAC-SHA256 en hexadecimal del cuerpo crudo con la clave secreta. Opcional (recomendado): X-Omnifox-Timestamp, y entonces se firma "{ts}.{cuerpo}".
  • Cada mensaje identifica al usuario con contact.id (su ID en tu sistema). Sin él, Omnifox responde 422. Cada contact.id distinto es un contacto distinto, con su propia conversación.
  • Saliente: Omnifox hace POST a tu URL con X-Omnifox-Signature: sha256=… calculada sobre "{ts}.{cuerpo}" y X-Omnifox-Timestamp. El cuerpo es fijo e incluye recipient (tu contact.id), content, agent (quién responde) y assigned_agent.
  • Tu sistema responde 2xx. Ante 5xx o tiempo agotado, Omnifox reintenta; un 4xx es definitivo.
  • Una sola clave secreta para los dos sentidos.
  • Eventos de conversación (asignada, transferida, cerrada, reabierta, traspaso de la IA, leída…) llegan a la misma URL saliente, con event_id para deduplicar y sequence para ordenar.
  • Acuses de lectura en los dos sentidos: tu sistema informa entregado o leído de nuestros mensajes, y Omnifox avisa con conversation.read cuando una persona lee el chat.

2. Obtener la URL y la clave

Desde la pantalla

En Canales → Conectar nuevo canal → Custom Channel (o editando el canal) encontrarás la URL de webhook entrante (con un token de 32 caracteres que no cambia al editar) y la Clave secreta. El botón Regenerar crea una clave nueva: después hay que guardar el canal y actualizarla en tu sistema.

Al guardar, si hay URL saliente, Omnifox envía {"event":"health_check","type":"health_check"} firmado igual que un saliente real, con 5 s de espera. Tu receptor debe responder 2xx o el canal no se guarda.

Por API

POST https://omnifox.io/api/v1/channels
Authorization: Bearer {API_TOKEN}
Content-Type: application/json

{
  "workspace_id": {WORKSPACE_ID},
  "type": "custom",
  "name": "Mi sistema externo",
  "settings": { "outbound_webhook_url": "https://tu-sistema.com/omnifox" }
}
  • El token se crea en Claves API y necesita el permiso de gestionar canales en ese espacio de trabajo.
  • credentials.signing_secret es opcional: si no lo envías, Omnifox genera uno.
  • settings.match_contacts_by_phone y settings.match_contacts_by_email (booleanos, por defecto false) activan la unión con contactos existentes (ver 3.6).
  • La respuesta 201 trae data.id, data.webhook_url (la URL con token) y data.signing_secret. Es la única vez que se devuelve la clave: guárdala.
  • outbound_webhook_url debe ser http(s); si no, 422. Si el plan no incluye canales personalizados: 402.
  • No hay endpoint para editar el canal por API: los cambios se hacen en la pantalla.

Nota: también funciona https://omnifox.io/api/webhooks/custom/{ID_DEL_CANAL}, pero recomendamos la URL con token, que identifica el canal sin ambigüedad.

3. Entrante: tu sistema → Omnifox

3.1 Solicitud

Método POST
URL https://omnifox.io/api/webhooks/custom/{TOKEN}
Content-Type application/json. El cuerpo debe ser un objeto JSON con un solo mensaje.
X-Omnifox-Signature Obligatorio. Firma (3.2). También se acepta como parámetro ?signature=.
X-Omnifox-Timestamp Opcional. Segundos Unix. Si viene, cambia lo que se firma y protege contra repeticiones.
Procesamiento Síncrono: cuando recibes el 200, el mensaje ya está en la bandeja.

3.2 Firma

sin timestamp:  firma = hex( HMAC_SHA256( clave = SECRET, mensaje = cuerpo_crudo ) )
con timestamp:  firma = hex( HMAC_SHA256( clave = SECRET, mensaje = ts + "." + cuerpo_crudo ) )
                (ts = valor exacto de X-Omnifox-Timestamp; desfase máximo ±300 s)
  • Hexadecimal, en mayúsculas o minúsculas, con o sin prefijo sha256=. No se acepta base64.
  • Se firman los mismos bytes que envías. No vuelvas a serializar el JSON después de firmar.
  • Recomendamos enviar X-Omnifox-Timestamp: así una solicitud capturada no se puede repetir más tarde. Sin timestamp se acepta, pero solo te protege la deduplicación por id.

3.3 Cuerpo

{
  "id": "msg-1001",
  "type": "text",
  "text": "Hola, quiero información",
  "contact": {
    "id": "user-42",
    "name": "Ana Pérez",
    "phone": "+593991234567",
    "email": "[email protected]",
    "avatar_url": "https://cdn.example.com/ana.jpg",
    "custom_fields": { "plan_actual": "pro" }
  },
  "team": "Ventas",
  "assignee_email": "[email protected]"
}
Campo Tipo Oblig. Descripción
contact.id string Sí ID del usuario en tu sistema (máx. 191 caracteres). Alias aceptados: sender_id, user_id o sender.id.
contact.name string No Nombre. Alias: sender como texto.
contact.phone string No Solo se guarda si tiene entre 6 y 20 dígitos, con + opcional (se ignoran los espacios).
contact.email string No Email válido; si no, 422.
contact.avatar_url string No URL http(s) absoluta; si no, 422.
contact.custom_fields objeto No {"nombre_interno": valor} para campos personalizados de contacto que ya existen en Omnifox.
team_id / team entero / string No Equipo al que asignar (3.7). team es el nombre, sin distinguir mayúsculas.
assignee_id / assignee_email entero / string No Agente al que asignar (3.7).
id string Recomendado ID del mensaje en tu sistema (máx. 180). Sirve para deduplicar. Alias: message_id. Si falta, no hay deduplicación.
text string Sí, si no hay adjuntos Texto del mensaje. Sin texto ni adjuntos → 422.
type string No text, image/photo/sticker, video, audio/voice, file/document. Con adjuntos, si falta se deduce.
media objeto No Un adjunto: url (obligatoria, pública), caption, mime_type, filename.
attachments objeto o lista No Uno o varios adjuntos con la misma forma (más type). Tiene prioridad sobre media.

Conversión de tipos: números y booleanos se convierten a texto ("id": 777 → "777"). null y "" cuentan como ausentes. Un objeto o una lista donde va texto → 422 con el detalle del campo. Se recortan los espacios de los extremos.

No existe en el entrante: hilos o conversaciones externas (Omnifox decide la conversación por contacto y canal), respuesta citando un mensaje, fecha del mensaje (se usa la hora de recepción), reacciones, base64 o multipart, ni varios mensajes por solicitud (una lista en el cuerpo → 422).

3.4 Respuestas

Caso HTTP Cuerpo
Guardado 200 {"ok":true,"message_id":"3747","message_ids":["3747"],"conversation_id":"629","contact_id":"1607","duplicate":false}
Repetido (mismo id) 200 Igual, con los IDs del original y "duplicate":true
Falta la firma 401 {"code":40100,"message":"Missing signature: …"}
Timestamp inválido o con más de 300 s de desfase 401 {"code":40100,"message":"Invalid or stale X-Omnifox-Timestamp …"}
Firma incorrecta 403 {"code":40300,"message":"Invalid signature"}
Cuenta de Omnifox suspendida 403 {"code":40300,"message":"The Omnifox account that owns this channel is suspended; …"}
Token desconocido 404 {"code":40400,"message":"Unknown channel"}
Canal desactivado 404 {"code":40400,"message":"Channel not found"}
El cuerpo no es un objeto JSON 422 {"code":42200,"message":"The body must be a JSON object …","details":{…}}
Cuerpo inválido 422 {"code":42200,"message":"The message body is not valid.","details":{"contact.id":["Required: …"]}}
No se pudo guardar 500 {"code":50000,"message":"The message could not be stored. It is safe to retry with the same id."}

Si el mensaje trae datos de contacto, campos personalizados o asignación, la respuesta 200 agrega:

{"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":["plan_actual"],
 "assignment":"assigned",
 "assigned_to":{"team":{"id":"2","name":"Ventas"},"agent":null},
 "contact_warnings":[
   {"field":"contact.custom_fields.no_existe","code":"custom_field_unknown","message":"No contact custom field with that name exists in this workspace; ignored."}
 ]}

Los IDs son IDs internos de Omnifox (texto). message_ids trae uno por cada mensaje creado (uno por adjunto).

Cuándo reintentar: ante 5xx o error de red, reintenta con el mismo id; si ya se había guardado, recibirás duplicate:true. Ante 4xx, corrige la solicitud: repetirla igual no sirve.

3.5 Adjuntos

  • Cada adjunto crea un mensaje. El text va como leyenda del primero; los demás llevan su propio caption.
  • IDs: el primero usa id; los siguientes, id#2, id#3… (la deduplicación funciona para cada uno).
  • Omnifox no descarga el archivo: guarda la URL y la bandeja lo muestra desde ahí. La URL debe ser pública y permanente.
  • Tipo de cada adjunto: su type → el type general (si hay un solo adjunto) → mime_type (image/*, video/*, audio/*, otro = archivo) → extensión de la URL.

3.6 Contacto y conversación

  • La identidad del usuario es contact.id: el primer mensaje crea el contacto; los siguientes caen en ese contacto y en su conversación abierta.
  • Primer mensaje de un contact.id nuevo, según las casillas Unir con contactos existentes del canal (apagadas por defecto):
    • Apagadas: se crea un contacto propio. Si el teléfono ya pertenece a otro contacto, el nuevo se crea sin teléfono y la respuesta avisa phone_in_use. El email se guarda igual.
    • Unir por teléfono: si existe un contacto con ese teléfono, el contact.id se vincula a él.
    • Unir por correo: si no hubo coincidencia por teléfono, se busca por email (exacto, sin distinguir mayúsculas).
    • Riesgo: personas distintas que comparten teléfono o correo terminarían en el mismo contacto. Vincular no fusiona contactos: solo apunta el contact.id a uno existente.
  • Mensajes siguientes: el contacto se actualiza cuando phone, email, name o avatar_url llegan con un valor distinto. Lo que llega vacío no borra nada. Los cambios se listan en contact_updated.
    • Teléfono inválido → aviso phone_invalid; teléfono de otro contacto → no se cambia, aviso phone_in_use.
    • El nombre solo se reemplaza si el actual es el que tu sistema envió la última vez. Si alguien lo editó en Omnifox, se respeta y se avisa name_kept_manual_edit.
    • El email se guarda en minúsculas y puede repetirse entre contactos.
  • Campos personalizados: contact.custom_fields escribe en campos de contacto ya creados en Omnifox (por su nombre interno), con la misma validación que en el resto de la aplicación. Nombre inexistente → custom_field_unknown (no se crean campos); valor inválido → custom_field_invalid.
  • Los avisos llegan en contact_warnings como {field, code, message} y nunca impiden guardar el mensaje.
  • Lo entrante dispara lo de siempre: flujos, agente de IA del canal, asignación y notificaciones.

3.7 Asignar equipo o agente

Campo Qué hace
team_id o team Asigna el equipo y aplica su estrategia de reparto. Debe ser un equipo del espacio de trabajo del canal. Si vienen los dos, manda team_id.
assignee_id o assignee_email Asigna a ese agente (miembro del espacio de trabajo). Si también viene un equipo, primero se asigna el equipo y después el agente.
  • Se aplica solo si la conversación es nueva o no tiene persona ni equipo asignados. Si ya los tiene, la respuesta trae "assignment":"skipped_already_assigned" y no cambia nada.
  • El mensaje se guarda siempre. Si el equipo o el agente no existen: 200 con "assignment":"error" y assignment_error (team_not_found o assignee_not_found). Un tipo imposible (por ejemplo team_id: "abc") sí es 422.
  • Si asigna: "assignment":"assigned" y assigned_to con team y agent (agent puede ser null si la estrategia del equipo es compartida o no hay nadie disponible).
  • No pausa al agente de IA. Si no envías estos campos, se mantiene el enrutamiento automático del canal.

4. Acuses de entregado y leído (tu sistema → Omnifox)

Usa la misma URL entrante y la misma firma con este cuerpo:

{ "type": "status", "status": "read", "message_id": "mysys-3780", "timestamp": 1791043535 }

o varios a la vez (máximo 100):

{ "statuses": [
    { "status": "delivered", "message_id": "mysys-3780", "timestamp": "2026-10-03T17:05:34Z" },
    { "status": "failed",    "message_id": "mysys-3781", "error": { "code": "X1", "message": "no entregable" } }
] }
Campo Descripción
status delivered, read o failed.
message_id El ID que tu receptor devolvió al recibir el mensaje (5.5). También se acepta el message_id de Omnifox. Para evitar ambigüedad puedes enviar external_id: entonces solo se busca por tu ID.
timestamp Opcional: segundos Unix o ISO-8601.
error Opcional, con failed: {code, message}. Se muestra en la bandeja.
  • Solo se buscan mensajes salientes de ese canal.
  • Nunca retrocede: read no vuelve a delivered, y failed solo se acepta si el mensaje aún no estaba entregado ni leído. Repetir un acuse es inofensivo.
  • Respuesta: {"ok":true,"updated":1,"results":[{"message_id":"3780","status":"read","result":"updated"}]}, con result = updated, unchanged o not_found.
  • Si ninguno se encontró: 404 Message not found in this channel. Cuerpo inválido: 422. Sin firma: 401. Firma incorrecta: 403.

5. Saliente: Omnifox → tu sistema

5.1 Qué se envía

Las respuestas de agentes humanos (bandeja o API), del agente de IA y de los flujos o automatizaciones. Las notas internas no se envían. Sin URL saliente, el mensaje queda fallido con el motivo "falta la URL del webhook saliente".

5.2 Encabezados

Encabezado Valor
Content-Type application/json
X-Omnifox-Signature sha256=<hex en minúsculas>
X-Omnifox-Timestamp Segundos Unix
X-Omnifox-Channel-Type custom
X-Omnifox-Delivery UUID de esta entrega

5.3 Firma

esperada = "sha256=" + hex( HMAC_SHA256( clave = SECRET, mensaje = X-Omnifox-Timestamp + "." + cuerpo_crudo ) )

Verifica sobre los bytes crudos y compara en tiempo constante. Omnifox no impone una ventana de tiempo de tu lado; recomendamos rechazar más de 300 s de desfase.

5.4 Cuerpo (fijo)

{
  "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": "¡Hola Ana! ¿En qué te ayudo?", "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"
}
Campo Contenido
event "message". La prueba al guardar usa "health_check"; los eventos, los nombres de la sección 6.
event_id message-<message_id>, estable, para deduplicar.
message_id ID del mensaje en Omnifox. Estable también si el agente pulsa "Reintentar".
recipient Tu contact.id: a quién entregar el mensaje.
contact id (= recipient), name, phone, email del contacto en Omnifox.
type text, image, video, audio, file, sticker, location, template, interactive…
content.text Texto (en medios, la leyenda).
content.media_url En medios, URL absoluta descargable. Si el archivo se subió en Omnifox es una URL firmada que caduca en pocas horas (máximo 6 h): descárgala enseguida.
reply_to ID externo del mensaje citado (si cita uno tuyo, el id que enviaste).
agent Quién envía: {"type":"human",…}, {"type":"ai",…} (agente de IA) o {"type":"system","id":null,"name":<nombre del flujo o null>}.
assigned_agent Asignado de la conversación: la persona; si no hay, el agente de IA; si no, null.
metadata Siempre un objeto ({} si está vacío). Contenido informativo, no garantizado.
sent_at ISO-8601 con zona horaria.

5.5 Respuesta esperada y reintentos

  • Responde 2xx en menos de 30 s y encola el trabajo pesado.
  • Opcional: devuelve {"id":"..."} (o message_id / external_id). Ese ID queda como ID externo del mensaje y lo usarás en los acuses (sección 4).
  • 5xx o error de red: hasta 3 intentos, con esperas de 1 s y 2 s, con el mismo cuerpo, firma y X-Omnifox-Delivery.
  • 4xx: rechazo definitivo, sin reintento; el mensaje queda fallido. El agente puede pulsar "Reintentar": es una entrega nueva con el mismo message_id.

6. Eventos de conversación

Llegan a la misma URL saliente, con la misma firma y encabezados (más X-Omnifox-Event), solo para conversaciones de ese canal. Cada evento se puede apagar en Eventos a enviar; por defecto están todos activos. Los mensajes se envían siempre.

Evento Cuándo changes
conversation.created Se abre una conversación nueva status: {from: null, to}
conversation.assigned Se asigna o transfiere a una persona y/o equipo (transferencia = from distinto de null) assigned_agent y/o team
conversation.unassigned Se quita la persona y/o el equipo igual, con to: null
conversation.pending / snoozed / resolved / closed Cambia el estado (incluye el cierre automático por inactividad) status: {from, to}
conversation.reopened Vuelve a abierta status: {from, to: "open"}
conversation.priority_changed Cambia la prioridad (urgent, high, medium, low, none) priority: {from, to}
conversation.tag_added / tag_removed Se pone o quita una etiqueta {} más tag: {id, name}
conversation.ai_handoff La IA deja la conversación a una persona o equipo ai_agent, ai_paused, más reason (handoff, human_takeover…)
conversation.ai_paused La IA se pausa sin traspaso igual que ai_handoff
conversation.ai_resumed Se reanuda la IA ai_agent: {from: null, to}, ai_paused: {from: true, to: false}
conversation.read Una persona leyó la conversación (sección 7) is_unread: {from: true, to: false}

No hay un status_changed genérico: cualquier evento cuyo changes tenga status es un cambio de estado.

6.1 Cuerpo

{
  "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 }
    }
  }
}
Campo Contenido
event_id UUID único, igual en todos los reintentos: deduplica por él.
sequence Orden por conversación (1, 2, 3…). Puede tener huecos o venir null; en ese caso usa occurred_at.
actor Quién hizo el cambio: type human, ai o system, y source user, ai, api, workflow o system.
status, priority, assigned_agent, team Estado después del cambio.
changes Qué cambió, siempre {campo: {from, to}}.
Extras tag (etiquetas), reason (IA), last_read_message_id, last_read_external_id, read_at y read_via (lectura).

Un mismo cambio puede generar varios eventos: por ejemplo, un traspaso de la IA a un equipo envía conversation.assigned y conversation.ai_handoff.

6.2 Entrega, reintentos y orden

  • Se envían en cola (normalmente en segundos); la acción del agente nunca espera a tu sistema.
  • Tiempo de espera de 15 s por intento. 2xx = entregado (el cuerpo de tu respuesta se ignora).
  • 4xx = definitivo. 5xx, error de red o tiempo agotado: hasta 5 intentos, con esperas de 30 s, 2 min, 10 min y 30 min. En cada reintento cambian el timestamp y la firma, pero no X-Omnifox-Delivery ni event_id.
  • Un mensaje puede llegar antes que un evento ocurrido un poco antes (los mensajes salen al instante y los eventos en cola). Ordena los eventos con sequence y los mensajes con sent_at.
  • Guarda los event_id procesados (7 días alcanza) e ignora los repetidos.

7. Evento conversation.read

Se envía cuando una persona deja la conversación leída (el contador de no leídos pasa a 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 (abrió el chat, o lo tenía abierto cuando llegó el mensaje) o reply (respondió).
  • last_read_external_id es el id del último mensaje que tu usuario envió: puedes marcar como leídos todos sus mensajes hasta ese.
  • Como máximo un conversation.read cada 10 s por conversación. Si no había nada sin leer, no se envía.
  • No se envía cuando "lee" la IA ni cuando se marca leída por API. Si un administrador abre un chat ajeno y el espacio de trabajo está configurado para no marcarlo como leído, tampoco.

8. Mapeo de campos

Si tu sistema no puede enviar el formato de 3.3, configura en la pantalla qué ruta de tu JSON llena cada campo de Omnifox. Es solo de entrada, la firma se verifica sobre tu JSON original y lo mapeado tiene prioridad sobre el campo estándar. Detalles y ejemplo en Canal personalizado: mapeo de campos. No hay mapeo de salida: el cuerpo saliente es siempre el de 5.4.

9. Limitaciones

Funcionalidad Estado
Ventana de 24 horas No aplica (es una regla de Meta).
Agente de IA Sí, si el canal tiene uno asignado; sale con agent.type = "ai".
Confirmaciones de lectura Sí, en los dos sentidos. La lectura de Omnifox es por conversación, no por mensaje.
Indicador "escribiendo…" No.
Edición o borrado de mensajes, reacciones No.
Varias URLs salientes No, una por canal.
Varios mensajes por solicitud No (varios adjuntos sí).
Base64 o multipart No, solo URL.
Protección contra repetición Solo si envías X-Omnifox-Timestamp.

10. Ejemplos de código

10.1 Enviar un mensaje (bash + openssl)

#!/usr/bin/env bash
set -euo pipefail

URL="https://omnifox.io/api/webhooks/custom/{TOKEN}"
SECRET="{SECRET}"

# Construye el cuerpo UNA vez y firma exactamente esos bytes.
BODY='{"id":"msg-1001","text":"Hola, quiero información","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"

Usa printf '%s' (no echo, que agrega un salto de línea) y --data-binary (no -d). El acuse de lectura usa la misma URL y firma con BODY='{"type":"status","status":"read","message_id":"mysys-3780"}'.

10.2 Enviar un mensaje (Node 18+)

import crypto from 'node:crypto';

const body = JSON.stringify({ id: 'msg-1001', text: 'Hola', 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, // exactamente el mismo texto que firmaste
});
console.log(res.status, await res.json());

10.3 Receptor mínimo (Node + Express)

const express = require('express');
const crypto = require('crypto');

const SECRET = process.env.OMNIFOX_SECRET;
const seen = new Set(); // event_id procesados; en producción usa Redis o tu base de datos
const app = express();

// Cuerpo CRUDO: con express.json() se pierden los bytes exactos que se firmaron.
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':
      // Entrega body.content al usuario body.recipient y devuelve tu ID para los acuses.
      return res.json({ id: `mysys-${body.message_id}` });
    case 'conversation.read':
      console.log('leído hasta', 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 Verificar y enviar en PHP

<?php
// Receptor
$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'] ?? '')]);

// Emisor: firma el mismo texto que envías
$body = json_encode(['id' => 'msg-1', 'text' => 'Hola', 'contact' => ['id' => 'user-42', 'name' => 'Ana']]);
$ts   = (string) time();
$sig  = hash_hmac('sha256', $ts . '.' . $body, $secret);
// POST $body con Content-Type: application/json, X-Omnifox-Timestamp: $ts y X-Omnifox-Signature: $sig

11. Lista de verificación

  • Tienes la URL con token y la clave secreta actual.
  • Cada POST es un objeto JSON con contact.id estable por usuario y un id único por mensaje.
  • Firmas el cuerpo crudo exacto, idealmente con X-Omnifox-Timestamp y el reloj sincronizado.
  • Reintentas con el mismo id ante 5xx o error de red.
  • Los adjuntos usan URLs públicas y permanentes.
  • Si asignas, revisas assignment y assignment_error en la respuesta.
  • Decidiste si unir con contactos existentes y creaste en Omnifox los campos personalizados que vas a enviar.
  • El receptor verifica sha256= sobre ts + "." + cuerpo, responde 2xx en menos de 30 s (y 2xx al health_check), despacha por event, deduplica por event_id y ordena los eventos por sequence.
  • Descargas content.media_url enseguida.
  • Devuelves un id al recibir cada mensaje y lo usas para los acuses delivered y read.

12. Problemas frecuentes

Síntoma Causa probable
401 Missing signature Falta X-Omnifox-Signature.
401 stale X-Omnifox-Timestamp Reloj desfasado más de 5 min, o timestamp en milisegundos.
403 Invalid signature Clave equivocada (¿se regeneró?), JSON re-serializado después de firmar, echo con salto de línea o curl -d, timestamp enviado pero no firmado (o al revés), o firma en base64.
404 Unknown channel / Channel not found Token mal copiado, canal eliminado o desactivado.
422 contact.id Falta el ID del usuario, o el mapeo no lo encuentra.
200 con duplicate:true Ese id ya se había recibido.
skipped_already_assigned La conversación ya tenía persona o equipo.
team_not_found / assignee_not_found El equipo o agente no existe en el espacio de trabajo del canal. El mensaje sí se guardó.
phone_in_use Ese teléfono es de otro contacto; no se movió.
custom_field_unknown No existe un campo personalizado de contacto con ese nombre interno.
Todos los mensajes en el mismo contacto Envías el mismo contact.id para todos.
El canal no se guarda al pulsar Continuar Tu URL saliente no respondió 2xx al health_check en 5 s.
Respuestas fallidas en la bandeja Falta la URL saliente o tu receptor devolvió 4xx (por ejemplo, rechazó la firma).
content.media_url da 403 al rato La URL firmada caducó.
Duplicados en tu receptor Reintentos o "Reintentar" manual: deduplica por event_id.
No llega un evento Está apagado en Eventos a enviar, no hay URL saliente o tu receptor devolvió 4xx.
Acuse con 404 El message_id no es el que devolvió tu receptor ni el de Omnifox, o es de otro canal.
No llega conversation.read Ya estaba leída, la leyó la IA o un token de API, o pasaron menos de 10 s desde el anterior.
¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp