Guia técnico de integração do canal personalizado

Referência para desenvolvedores: assinatura HMAC, formato das mensagens de entrada e saída, eventos de conversa, confirmações de leitura, erros e exemplos de código.

Oct 04, 2026

Guia para o desenvolvedor que conecta um sistema externo ao Omnifox pelo canal personalizado (Custom Channel). Se o canal ainda não foi criado, comece por Canal personalizado: o que é e como configurar.

Os exemplos usam marcadores: {TOKEN} (parte final da URL de entrada), {SECRET} (chave secreta do canal), {API_TOKEN}, {WORKSPACE_ID} e https://seu-sistema.com/omnifox (sua URL de saída). Nunca cole chaves reais em tickets nem em logs.

Índice

  1. Resumo
  2. Obter a URL e a chave
  3. Entrada: seu sistema → Omnifox
  4. Confirmações de entregue e lido (seu sistema → Omnifox)
  5. Saída: Omnifox → seu sistema
  6. Eventos de conversa
  7. Evento conversation.read
  8. Mapeamento de campos
  9. Limitações
  10. Exemplos de código
  11. Lista de verificação
  12. Problemas frequentes

1. Resumo

  • Entrada: POST https://omnifox.io/api/webhooks/custom/{TOKEN} com um JSON e o cabeçalho X-Omnifox-Signature = HMAC-SHA256 em hexadecimal do corpo bruto com a chave secreta. Opcional (recomendado): X-Omnifox-Timestamp, e então se assina "{ts}.{corpo}".
  • Cada mensagem identifica o usuário com contact.id (o ID dele no seu sistema). Sem ele, o Omnifox responde 422. Cada contact.id diferente é um contato diferente, com sua própria conversa.
  • Saída: o Omnifox faz POST para a sua URL com X-Omnifox-Signature: sha256=… calculada sobre "{ts}.{corpo}" e X-Omnifox-Timestamp. O corpo é fixo e inclui recipient (seu contact.id), content, agent (quem responde) e assigned_agent.
  • Seu sistema responde 2xx. Em caso de 5xx ou tempo esgotado, o Omnifox tenta de novo; um 4xx é definitivo.
  • Uma única chave secreta para os dois sentidos.
  • Eventos de conversa (atribuída, transferida, fechada, reaberta, repasse da IA, lida…) chegam à mesma URL de saída, com event_id para deduplicar e sequence para ordenar.
  • Confirmações de leitura nos dois sentidos: seu sistema informa entregue ou lido das nossas mensagens, e o Omnifox avisa com conversation.read quando uma pessoa lê o chat.

2. Obter a URL e a chave

Pela tela

Em Canais → Conectar novo canal → Custom Channel (ou editando o canal) você encontra a URL do webhook de entrada (com um token de 32 caracteres que não muda ao editar) e a Chave secreta. O botão Regenerar cria uma chave nova: depois é preciso salvar o canal e atualizá-la no seu sistema.

Ao salvar, se houver URL de saída, o Omnifox envia {"event":"health_check","type":"health_check"} assinado igual a uma saída real, com 5 s de espera. Seu receptor precisa responder 2xx ou o canal não é salvo.

Pela API

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

{
  "workspace_id": {WORKSPACE_ID},
  "type": "custom",
  "name": "Meu sistema externo",
  "settings": { "outbound_webhook_url": "https://seu-sistema.com/omnifox" }
}
  • O token é criado em Chaves API e precisa da permissão de gerenciar canais nesse espaço de trabalho.
  • credentials.signing_secret é opcional: se você não enviar, o Omnifox gera uma.
  • settings.match_contacts_by_phone e settings.match_contacts_by_email (booleanos, padrão false) ativam a união com contatos existentes (veja 3.6).
  • A resposta 201 traz data.id, data.webhook_url (a URL com token) e data.signing_secret. É a única vez que a chave é devolvida: guarde-a.
  • outbound_webhook_url precisa ser http(s); caso contrário, 422. Se o plano não inclui canais personalizados: 402.
  • Não há endpoint para editar o canal pela API: as mudanças são feitas na tela.

Nota: https://omnifox.io/api/webhooks/custom/{ID_DO_CANAL} também funciona, mas recomendamos a URL com token, que identifica o canal sem ambiguidade.

3. Entrada: seu sistema → Omnifox

3.1 Requisição

Método POST
URL https://omnifox.io/api/webhooks/custom/{TOKEN}
Content-Type application/json. O corpo precisa ser um objeto JSON com uma única mensagem.
X-Omnifox-Signature Obrigatório. Assinatura (3.2). Também é aceita como parâmetro ?signature=.
X-Omnifox-Timestamp Opcional. Segundos Unix. Se vier, muda o que é assinado e protege contra repetições.
Processamento Síncrono: quando você recebe o 200, a mensagem já está na caixa de entrada.

3.2 Assinatura

sem timestamp:  assinatura = hex( HMAC_SHA256( chave = SECRET, mensagem = corpo_bruto ) )
com timestamp:  assinatura = hex( HMAC_SHA256( chave = SECRET, mensagem = ts + "." + corpo_bruto ) )
                (ts = valor exato de X-Omnifox-Timestamp; diferença máxima ±300 s)
  • Hexadecimal, em maiúsculas ou minúsculas, com ou sem o prefixo sha256=. Base64 não é aceito.
  • Assine os mesmos bytes que você envia. Não serialize o JSON de novo depois de assinar.
  • Recomendamos enviar X-Omnifox-Timestamp: assim uma requisição capturada não pode ser repetida mais tarde. Sem timestamp ela é aceita, mas só a deduplicação por id protege você.

3.3 Corpo

{
  "id": "msg-1001",
  "type": "text",
  "text": "Olá, quero informações",
  "contact": {
    "id": "user-42",
    "name": "Ana Pereira",
    "phone": "+5511912345678",
    "email": "[email protected]",
    "avatar_url": "https://cdn.example.com/ana.jpg",
    "custom_fields": { "plano_atual": "pro" }
  },
  "team": "Vendas",
  "assignee_email": "[email protected]"
}
Campo Tipo Obrig. Descrição
contact.id string Sim ID do usuário no seu sistema (máx. 191 caracteres). Aliases aceitos: sender_id, user_id ou sender.id.
contact.name string Não Nome. Alias: sender como texto.
contact.phone string Não Só é salvo se tiver de 6 a 20 dígitos, com + opcional (os espaços são ignorados).
contact.email string Não E-mail válido; caso contrário, 422.
contact.avatar_url string Não URL http(s) absoluta; caso contrário, 422.
contact.custom_fields objeto Não {"nome_interno": valor} para campos personalizados de contato que já existem no Omnifox.
team_id / team inteiro / string Não Equipe a atribuir (3.7). team é o nome, sem diferenciar maiúsculas.
assignee_id / assignee_email inteiro / string Não Agente a atribuir (3.7).
id string Recomendado ID da mensagem no seu sistema (máx. 180). Serve para deduplicar. Alias: message_id. Se faltar, não há deduplicação.
text string Sim, se não houver anexos Texto da mensagem. Sem texto e sem anexos → 422.
type string Não text, image/photo/sticker, video, audio/voice, file/document. Com anexos, se faltar, é deduzido.
media objeto Não Um anexo: url (obrigatória, pública), caption, mime_type, filename.
attachments objeto ou lista Não Um ou vários anexos com a mesma forma (mais type). Tem prioridade sobre media.

Conversão de tipos: números e booleanos são convertidos em texto ("id": 777 → "777"). null e "" contam como ausentes. Um objeto ou uma lista onde se espera texto → 422 com o detalhe do campo. Os espaços nas extremidades são removidos.

Não existe na entrada: threads ou conversas externas (o Omnifox decide a conversa por contato e canal), resposta citando uma mensagem, data da mensagem (usa-se a hora do recebimento), reações, base64 ou multipart, nem várias mensagens por requisição (uma lista no corpo → 422).

3.4 Respostas

Caso HTTP Corpo
Salva 200 {"ok":true,"message_id":"3747","message_ids":["3747"],"conversation_id":"629","contact_id":"1607","duplicate":false}
Repetida (mesmo id) 200 Igual, com os IDs da original e "duplicate":true
Falta a assinatura 401 {"code":40100,"message":"Missing signature: …"}
Timestamp inválido ou com mais de 300 s de diferença 401 {"code":40100,"message":"Invalid or stale X-Omnifox-Timestamp …"}
Assinatura incorreta 403 {"code":40300,"message":"Invalid signature"}
Conta do Omnifox suspensa 403 {"code":40300,"message":"The Omnifox account that owns this channel is suspended; …"}
Token desconhecido 404 {"code":40400,"message":"Unknown channel"}
Canal desativado 404 {"code":40400,"message":"Channel not found"}
O corpo não é um objeto JSON 422 {"code":42200,"message":"The body must be a JSON object …","details":{…}}
Corpo inválido 422 {"code":42200,"message":"The message body is not valid.","details":{"contact.id":["Required: …"]}}
Não foi possível salvar 500 {"code":50000,"message":"The message could not be stored. It is safe to retry with the same id."}

Se a mensagem trouxer dados de contato, campos personalizados ou atribuição, a resposta 200 acrescenta:

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

Os IDs são IDs internos do Omnifox (texto). message_ids traz um por mensagem criada (uma por anexo).

Quando tentar de novo: em caso de 5xx ou erro de rede, reenvie com o mesmo id; se já tinha sido salva, você recebe duplicate:true. Em caso de 4xx, corrija a requisição: repeti-la igual não adianta.

3.5 Anexos

  • Cada anexo cria uma mensagem. O text vira a legenda do primeiro; os demais levam a própria caption.
  • IDs: o primeiro usa id; os seguintes, id#2, id#3… (a deduplicação funciona para cada um).
  • O Omnifox não baixa o arquivo: guarda a URL e a caixa de entrada o exibe a partir dela. A URL precisa ser pública e permanente.
  • Tipo de cada anexo: o próprio type → o type geral (se houver um único anexo) → mime_type (image/*, video/*, audio/*, outro = arquivo) → extensão da URL.

3.6 Contato e conversa

  • A identidade do usuário é o contact.id: a primeira mensagem cria o contato; as seguintes caem nesse contato e na sua conversa aberta.
  • Primeira mensagem de um contact.id novo, conforme as opções Unir com contatos existentes do canal (desativadas por padrão):
    • Desativadas: é criado um contato próprio. Se o telefone já pertence a outro contato, o novo é criado sem telefone e a resposta avisa phone_in_use. O e-mail é salvo mesmo assim.
    • Unir por telefone: se existe um contato com esse telefone, o contact.id é vinculado a ele.
    • Unir por e-mail: se não houve correspondência por telefone, busca-se por e-mail (exato, sem diferenciar maiúsculas).
    • Risco: pessoas diferentes que compartilham telefone ou e-mail acabariam no mesmo contato. Vincular não mescla contatos: só aponta o contact.id para um já existente.
  • Mensagens seguintes: o contato é atualizado quando phone, email, name ou avatar_url chegam com um valor diferente. O que chega vazio não apaga nada. As mudanças aparecem em contact_updated.
    • Telefone inválido → aviso phone_invalid; telefone de outro contato → não muda, aviso phone_in_use.
    • O nome só é substituído se o atual for o que o seu sistema enviou da última vez. Se alguém o editou no Omnifox, ele é mantido e você recebe name_kept_manual_edit.
    • O e-mail é salvo em minúsculas e pode se repetir entre contatos.
  • Campos personalizados: contact.custom_fields grava em campos de contato já criados no Omnifox (pelo nome interno), com a mesma validação do resto do aplicativo. Nome inexistente → custom_field_unknown (nenhum campo é criado); valor inválido → custom_field_invalid.
  • Os avisos chegam em contact_warnings como {field, code, message} e nunca impedem que a mensagem seja salva.
  • A entrada dispara o de sempre: fluxos, agente de IA do canal, atribuição e notificações.

3.7 Atribuir equipe ou agente

Campo O que faz
team_id ou team Atribui a equipe e aplica sua estratégia de distribuição. Precisa ser uma equipe do espaço de trabalho do canal. Se vierem os dois, vale team_id.
assignee_id ou assignee_email Atribui a esse agente (membro do espaço de trabalho). Se também vier uma equipe, primeiro se atribui a equipe e depois o agente.
  • Só se aplica se a conversa for nova ou não tiver pessoa nem equipe atribuídas. Caso contrário, a resposta traz "assignment":"skipped_already_assigned" e nada muda.
  • A mensagem é sempre salva. Se a equipe ou o agente não existirem: 200 com "assignment":"error" e assignment_error (team_not_found ou assignee_not_found). Um tipo impossível (por exemplo team_id: "abc") é 422.
  • Se atribuir: "assignment":"assigned" e assigned_to com team e agent (agent pode ser null se a estratégia da equipe for compartilhada ou não houver ninguém disponível).
  • Não pausa o agente de IA. Se você não enviar esses campos, o roteamento automático do canal é mantido.

4. Confirmações de entregue e lido (seu sistema → Omnifox)

Use a mesma URL de entrada e a mesma assinatura com este corpo:

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

ou várias de uma 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": "não entregável" } }
] }
Campo Descrição
status delivered, read ou failed.
message_id O ID que o seu receptor devolveu ao receber a mensagem (5.5). O message_id do Omnifox também é aceito. Para evitar ambiguidade, você pode enviar external_id: então só se busca pelo seu ID.
timestamp Opcional: segundos Unix ou ISO-8601.
error Opcional, com failed: {code, message}. É exibido na caixa de entrada.
  • Só são buscadas mensagens de saída desse canal.
  • Nunca retrocede: read não volta para delivered, e failed só é aceito se a mensagem ainda não estava entregue nem lida. Repetir uma confirmação é inofensivo.
  • Resposta: {"ok":true,"updated":1,"results":[{"message_id":"3780","status":"read","result":"updated"}]}, com result = updated, unchanged ou not_found.
  • Se nenhuma foi encontrada: 404 Message not found in this channel. Corpo inválido: 422. Sem assinatura: 401. Assinatura incorreta: 403.

5. Saída: Omnifox → seu sistema

5.1 O que é enviado

As respostas de agentes humanos (caixa de entrada ou API), do agente de IA e dos fluxos ou automações. Notas internas não são enviadas. Sem URL de saída, a mensagem fica com falha e o motivo "falta a URL do webhook de saída".

5.2 Cabeçalhos

Cabeçalho Valor
Content-Type application/json
X-Omnifox-Signature sha256=<hex em minúsculas>
X-Omnifox-Timestamp Segundos Unix
X-Omnifox-Channel-Type custom
X-Omnifox-Delivery UUID desta entrega

5.3 Assinatura

esperada = "sha256=" + hex( HMAC_SHA256( chave = SECRET, mensagem = X-Omnifox-Timestamp + "." + corpo_bruto ) )

Verifique sobre os bytes brutos e compare em tempo constante. O Omnifox não impõe janela de tempo do seu lado; recomendamos recusar mais de 300 s de diferença.

5.4 Corpo (fixo)

{
  "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 Pereira", "phone": null, "email": null },
  "omnifox_contact_id": "1603",
  "type": "text",
  "content": { "text": "Olá, Ana! Como posso ajudar?", "media_url": null, "caption": null, "mime_type": null, "filename": null },
  "reply_to": null,
  "agent": { "type": "human", "id": "28", "name": "Laura Gomes", "avatar_url": null },
  "assigned_agent": { "type": "human", "id": "28", "name": "Laura Gomes", "avatar_url": null },
  "metadata": {},
  "sent_at": "2026-10-03T15:51:30+00:00"
}
Campo Conteúdo
event "message". O teste ao salvar usa "health_check"; os eventos, os nomes da seção 6.
event_id message-<message_id>, estável, para deduplicar.
message_id ID da mensagem no Omnifox. Estável também se o agente clicar em "Tentar novamente".
recipient Seu contact.id: a quem entregar a mensagem.
contact id (= recipient), name, phone, email do contato no Omnifox.
type text, image, video, audio, file, sticker, location, template, interactive…
content.text Texto (em mídias, a legenda).
content.media_url Em mídias, URL absoluta para download. Se o arquivo foi enviado no Omnifox, é uma URL assinada que expira em poucas horas (no máximo 6 h): baixe-a imediatamente.
reply_to ID externo da mensagem citada (se citar uma sua, o id que você enviou).
agent Quem envia: {"type":"human",…}, {"type":"ai",…} (agente de IA) ou {"type":"system","id":null,"name":<nome do fluxo ou null>}.
assigned_agent Responsável pela conversa: a pessoa; se não houver, o agente de IA; senão, null.
metadata Sempre um objeto ({} se vazio). Conteúdo informativo, não garantido.
sent_at ISO-8601 com fuso horário.

5.5 Resposta esperada e novas tentativas

  • Responda 2xx em menos de 30 s e coloque o trabalho pesado em fila.
  • Opcional: devolva {"id":"..."} (ou message_id / external_id). Esse ID fica como ID externo da mensagem e você o usará nas confirmações (seção 4).
  • 5xx ou erro de rede: até 3 tentativas, com esperas de 1 s e 2 s, com o mesmo corpo, assinatura e X-Omnifox-Delivery.
  • 4xx: recusa definitiva, sem nova tentativa; a mensagem fica com falha. O agente pode clicar em "Tentar novamente": é uma entrega nova com o mesmo message_id.

6. Eventos de conversa

Chegam à mesma URL de saída, com a mesma assinatura e os mesmos cabeçalhos (mais X-Omnifox-Event), apenas para conversas desse canal. Cada evento pode ser desativado em Eventos a enviar; por padrão, todos estão ativos. As mensagens são enviadas sempre.

Evento Quando changes
conversation.created Uma conversa nova é aberta status: {from: null, to}
conversation.assigned Atribuída ou transferida a uma pessoa e/ou equipe (transferência = from diferente de null) assigned_agent e/ou team
conversation.unassigned A pessoa e/ou a equipe são removidas igual, com to: null
conversation.pending / snoozed / resolved / closed O status muda (inclui o fechamento automático por inatividade) status: {from, to}
conversation.reopened Volta a aberta status: {from, to: "open"}
conversation.priority_changed A prioridade muda (urgent, high, medium, low, none) priority: {from, to}
conversation.tag_added / tag_removed Uma etiqueta é adicionada ou removida {} mais tag: {id, name}
conversation.ai_handoff A IA passa a conversa para uma pessoa ou equipe ai_agent, ai_paused, mais reason (handoff, human_takeover…)
conversation.ai_paused A IA é pausada sem repasse igual a ai_handoff
conversation.ai_resumed A IA é retomada ai_agent: {from: null, to}, ai_paused: {from: true, to: false}
conversation.read Uma pessoa leu a conversa (seção 7) is_unread: {from: true, to: false}

Não existe um status_changed genérico: qualquer evento cujo changes tenha status é uma mudança de status.

6.1 Corpo

{
  "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 Pereira", "phone": null, "email": null },
  "omnifox_contact_id": "1608",
  "actor": { "type": "human", "id": "28", "name": "Laura Gomes", "avatar_url": null, "source": "user" },
  "status": "open",
  "priority": "none",
  "assigned_agent": { "type": "human", "id": "30", "name": "Carlos Souza", "avatar_url": null },
  "team": null,
  "changes": {
    "assigned_agent": {
      "from": { "type": "human", "id": "29", "name": "Marta Lima", "avatar_url": null },
      "to":   { "type": "human", "id": "30", "name": "Carlos Souza", "avatar_url": null }
    }
  }
}
Campo Conteúdo
event_id UUID único, igual em todas as novas tentativas: deduplique por ele.
sequence Ordem por conversa (1, 2, 3…). Pode ter lacunas ou vir null; nesse caso use occurred_at.
actor Quem fez a mudança: type human, ai ou system, e source user, ai, api, workflow ou system.
status, priority, assigned_agent, team Estado depois da mudança.
changes O que mudou, sempre {campo: {from, to}}.
Extras tag (etiquetas), reason (IA), last_read_message_id, last_read_external_id, read_at e read_via (leitura).

Uma mesma mudança pode gerar vários eventos: por exemplo, um repasse da IA para uma equipe envia conversation.assigned e conversation.ai_handoff.

6.2 Entrega, novas tentativas e ordem

  • São enviados em fila (normalmente em segundos); a ação do agente nunca espera pelo seu sistema.
  • Tempo limite de 15 s por tentativa. 2xx = entregue (o corpo da sua resposta é ignorado).
  • 4xx = definitivo. 5xx, erro de rede ou tempo esgotado: até 5 tentativas, com esperas de 30 s, 2 min, 10 min e 30 min. A cada nova tentativa mudam o timestamp e a assinatura, mas não X-Omnifox-Delivery nem event_id.
  • Uma mensagem pode chegar antes de um evento ocorrido um pouco antes (as mensagens saem na hora e os eventos em fila). Ordene os eventos por sequence e as mensagens por sent_at.
  • Guarde os event_id processados (7 dias bastam) e ignore os repetidos.

7. Evento conversation.read

É enviado quando uma pessoa deixa a conversa lida (o contador de não lidas vai a 0):

{
  "event": "conversation.read",
  "event_id": "47dad59d-f43f-4bd3-9122-d097b962b17c",
  "sequence": 26,
  "recipient": "user-42",
  "actor": { "type": "human", "id": "28", "name": "Laura Gomes", "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 (abriu o chat, ou estava com ele aberto quando a mensagem chegou) ou reply (respondeu).
  • last_read_external_id é o id da última mensagem que o seu usuário enviou: você pode marcar como lidas todas as mensagens dele até essa.
  • No máximo um conversation.read a cada 10 s por conversa. Se não havia nada não lido, nada é enviado.
  • Não é enviado quando a IA "lê" o chat nem quando ele é marcado como lido pela API. Também não é enviado se um administrador abrir um chat de outra pessoa e o espaço de trabalho estiver configurado para não marcá-lo como lido.

8. Mapeamento de campos

Se o seu sistema não consegue enviar o formato de 3.3, configure na tela qual caminho do seu JSON preenche cada campo do Omnifox. É somente de entrada, a assinatura é verificada sobre o seu JSON original e o que é mapeado tem prioridade sobre o campo padrão. Detalhes e exemplo em Canal personalizado: mapeamento de campos. Não existe mapeamento de saída: o corpo de saída é sempre o de 5.4.

9. Limitações

Funcionalidade Situação
Janela de 24 horas Não se aplica (é uma regra da Meta).
Agente de IA Sim, se o canal tiver um atribuído; sai com agent.type = "ai".
Confirmações de leitura Sim, nos dois sentidos. A leitura do Omnifox é por conversa, não por mensagem.
Indicador "digitando…" Não.
Edição ou exclusão de mensagens, reações Não.
Várias URLs de saída Não, uma por canal.
Várias mensagens por requisição Não (vários anexos, sim).
Base64 ou multipart Não, apenas URL.
Proteção contra repetição Só se você enviar X-Omnifox-Timestamp.

10. Exemplos de código

10.1 Enviar uma mensagem (bash + openssl)

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

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

# Monte o corpo UMA vez e assine exatamente esses bytes.
BODY='{"id":"msg-1001","text":"Olá, quero informações","contact":{"id":"user-42","name":"Ana Pereira","phone":"+5511912345678"}}'

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' (não echo, que adiciona uma quebra de linha) e --data-binary (não -d). A confirmação de leitura usa a mesma URL e assinatura com BODY='{"type":"status","status":"read","message_id":"mysys-3780"}'.

10.2 Enviar uma mensagem (Node 18+)

import crypto from 'node:crypto';

const body = JSON.stringify({ id: 'msg-1001', text: 'Olá', contact: { id: 'user-42', name: 'Ana Pereira' } });
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, // exatamente o mesmo texto que você assinou
});
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 processados; em produção use Redis ou o seu banco de dados
const app = express();

// Corpo BRUTO: com express.json() perdem-se os bytes exatos que foram assinados.
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':
      // Entregue body.content ao usuário body.recipient e devolva o seu ID para as confirmações.
      return res.json({ id: `mysys-${body.message_id}` });
    case 'conversation.read':
      console.log('lido até', 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 e enviar em 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'] ?? '')]);

// Emissor: assine o mesmo texto que você envia
$body = json_encode(['id' => 'msg-1', 'text' => 'Olá', 'contact' => ['id' => 'user-42', 'name' => 'Ana']]);
$ts   = (string) time();
$sig  = hash_hmac('sha256', $ts . '.' . $body, $secret);
// POST $body com Content-Type: application/json, X-Omnifox-Timestamp: $ts e X-Omnifox-Signature: $sig

11. Lista de verificação

  • Você tem a URL com token e a chave secreta atual.
  • Cada POST é um objeto JSON com contact.id estável por usuário e um id único por mensagem.
  • Você assina o corpo bruto exato, de preferência com X-Omnifox-Timestamp e o relógio sincronizado.
  • Você reenvia com o mesmo id em caso de 5xx ou erro de rede.
  • Os anexos usam URLs públicas e permanentes.
  • Se atribuir, você confere assignment e assignment_error na resposta.
  • Você decidiu se vai unir com contatos existentes e criou no Omnifox os campos personalizados que vai enviar.
  • O receptor verifica sha256= sobre ts + "." + corpo, responde 2xx em menos de 30 s (e 2xx ao health_check), despacha por event, deduplica por event_id e ordena os eventos por sequence.
  • Você baixa content.media_url imediatamente.
  • Você devolve um id ao receber cada mensagem e o usa nas confirmações delivered e read.

12. Problemas frequentes

Sintoma Causa provável
401 Missing signature Falta X-Omnifox-Signature.
401 stale X-Omnifox-Timestamp Relógio com mais de 5 min de diferença, ou timestamp em milissegundos.
403 Invalid signature Chave errada (foi regenerada?), JSON serializado de novo depois de assinar, echo com quebra de linha ou curl -d, timestamp enviado mas não assinado (ou o contrário), ou assinatura em base64.
404 Unknown channel / Channel not found Token copiado errado, canal excluído ou desativado.
422 contact.id Falta o ID do usuário, ou o mapeamento não o encontra.
200 com duplicate:true Esse id já tinha sido recebido.
skipped_already_assigned A conversa já tinha pessoa ou equipe.
team_not_found / assignee_not_found A equipe ou o agente não existe no espaço de trabalho do canal. A mensagem foi salva.
phone_in_use Esse telefone é de outro contato; não foi movido.
custom_field_unknown Não existe campo personalizado de contato com esse nome interno.
Todas as mensagens no mesmo contato Você está enviando o mesmo contact.id para todos.
O canal não é salvo ao clicar em Continuar Sua URL de saída não respondeu 2xx ao health_check em 5 s.
Respostas com falha na caixa de entrada Falta a URL de saída ou o seu receptor devolveu 4xx (por exemplo, recusou a assinatura).
content.media_url dá 403 depois de um tempo A URL assinada expirou.
Duplicados no seu receptor Novas tentativas ou "Tentar novamente" manual: deduplique por event_id.
Um evento não chega Está desativado em Eventos a enviar, não há URL de saída ou o seu receptor devolveu 4xx.
Confirmação com 404 O message_id não é o que o seu receptor devolveu nem o do Omnifox, ou é de outro canal.
conversation.read não chega Já estava lida, a IA ou um token de API a leu, ou passaram menos de 10 s desde o anterior.
Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp