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.
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
- Resumen
- Obtener la URL y la clave
- Entrante: tu sistema → Omnifox
- Acuses de entregado y leído (tu sistema → Omnifox)
- Saliente: Omnifox → tu sistema
- Eventos de conversación
- Evento
conversation.read - Mapeo de campos
- Limitaciones
- Ejemplos de código
- Lista de verificación
- Problemas frecuentes
1. Resumen
- Entrante:
POST https://omnifox.io/api/webhooks/custom/{TOKEN}con un JSON y el encabezadoX-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. Cadacontact.iddistinto es un contacto distinto, con su propia conversación. - Saliente: Omnifox hace
POSTa tu URL conX-Omnifox-Signature: sha256=…calculada sobre"{ts}.{cuerpo}"yX-Omnifox-Timestamp. El cuerpo es fijo e incluyerecipient(tucontact.id),content,agent(quién responde) yassigned_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_idpara deduplicar ysequencepara ordenar. - Acuses de lectura en los dos sentidos: tu sistema informa entregado o leído de nuestros mensajes, y Omnifox avisa con
conversation.readcuando 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_secretes opcional: si no lo envías, Omnifox genera uno.settings.match_contacts_by_phoneysettings.match_contacts_by_email(booleanos, por defectofalse) activan la unión con contactos existentes (ver 3.6).- La respuesta
201traedata.id,data.webhook_url(la URL con token) ydata.signing_secret. Es la única vez que se devuelve la clave: guárdala. outbound_webhook_urldebe serhttp(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 porid.
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
textva como leyenda del primero; los demás llevan su propiocaption. - 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→ eltypegeneral (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.idnuevo, 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.idse 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.ida uno existente.
- 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
- Mensajes siguientes: el contacto se actualiza cuando
phone,email,nameoavatar_urlllegan con un valor distinto. Lo que llega vacío no borra nada. Los cambios se listan encontact_updated.- Teléfono inválido → aviso
phone_invalid; teléfono de otro contacto → no se cambia, avisophone_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.
- Teléfono inválido → aviso
- Campos personalizados:
contact.custom_fieldsescribe 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_warningscomo{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"yassignment_error(team_not_foundoassignee_not_found). Un tipo imposible (por ejemploteam_id: "abc") sí es 422. - Si asigna:
"assignment":"assigned"yassigned_toconteamyagent(agentpuede sernullsi 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:
readno vuelve adelivered, yfailedsolo 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"}]}, conresult=updated,unchangedonot_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":"..."}(omessage_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-Deliverynievent_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
sequencey los mensajes consent_at. - Guarda los
event_idprocesados (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) oreply(respondió).last_read_external_ides eliddel último mensaje que tu usuario envió: puedes marcar como leídos todos sus mensajes hasta ese.- Como máximo un
conversation.readcada 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.idestable por usuario y unidúnico por mensaje. - Firmas el cuerpo crudo exacto, idealmente con
X-Omnifox-Timestampy el reloj sincronizado. - Reintentas con el mismo
idante 5xx o error de red. - Los adjuntos usan URLs públicas y permanentes.
- Si asignas, revisas
assignmentyassignment_erroren la respuesta. - Decidiste si unir con contactos existentes y creaste en Omnifox los campos personalizados que vas a enviar.
- El receptor verifica
sha256=sobrets + "." + cuerpo, responde 2xx en menos de 30 s (y 2xx alhealth_check), despacha porevent, deduplica porevent_idy ordena los eventos porsequence. - Descargas
content.media_urlenseguida. - Devuelves un
idal recibir cada mensaje y lo usas para los acusesdeliveredyread.
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. |
Artículos relacionados
-
Cómo conectar Telegram
Conecta un bot de Telegram a tu bandeja de Omnifox en pocos minutos usando BotFather.
-
Guía completa del Webchat (chat para tu sitio web)
El Webchat a fondo, en 32 capítulos: instalarlo, apariencia, idiomas, formulario, departamentos, horario, disparadores, IA, la bandeja, identificación segura y API de JavaScript, con un sitio real de punta a punta.
-
Códigos de error de WhatsApp (Meta): qué significan y qué hacer
Tabla con los códigos de error de Meta más comunes al enviar por WhatsApp (131026, 131047, 131049, 130497, 141006, 131031, 131056, 132000, 190, 368…) y cómo resolver cada uno.
-
Pasar de WhatsApp por QR a Coexistence o Cloud API
Cuando termines de probar con el código QR, pasa tu número a la conexión oficial: sin topes, con plantillas, difusiones y sin riesgo de bloqueo por volumen.
-
Comentarios de Instagram y Facebook: responder y moderar desde Omnifox
Ve y responde los comentarios de tus publicaciones y anuncios de Facebook e Instagram, en público o en privado, y configura respuestas automáticas.