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.
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
- Resumo
- Obter a URL e a chave
- Entrada: seu sistema → Omnifox
- Confirmações de entregue e lido (seu sistema → Omnifox)
- Saída: Omnifox → seu sistema
- Eventos de conversa
- Evento
conversation.read - Mapeamento de campos
- Limitações
- Exemplos de código
- Lista de verificação
- Problemas frequentes
1. Resumo
- Entrada:
POST https://omnifox.io/api/webhooks/custom/{TOKEN}com um JSON e o cabeçalhoX-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. Cadacontact.iddiferente é um contato diferente, com sua própria conversa. - Saída: o Omnifox faz
POSTpara a sua URL comX-Omnifox-Signature: sha256=…calculada sobre"{ts}.{corpo}"eX-Omnifox-Timestamp. O corpo é fixo e incluirecipient(seucontact.id),content,agent(quem responde) eassigned_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_idpara deduplicar esequencepara ordenar. - Confirmações de leitura nos dois sentidos: seu sistema informa entregue ou lido das nossas mensagens, e o Omnifox avisa com
conversation.readquando 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_phoneesettings.match_contacts_by_email(booleanos, padrãofalse) ativam a união com contatos existentes (veja 3.6).- A resposta
201trazdata.id,data.webhook_url(a URL com token) edata.signing_secret. É a única vez que a chave é devolvida: guarde-a. outbound_webhook_urlprecisa serhttp(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 poridprotege 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
textvira a legenda do primeiro; os demais levam a própriacaption. - 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→ otypegeral (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.idnovo, 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.idpara um já existente.
- Desativadas: é criado um contato próprio. Se o telefone já pertence a outro contato, o novo é criado sem telefone e a resposta avisa
- Mensagens seguintes: o contato é atualizado quando
phone,email,nameouavatar_urlchegam com um valor diferente. O que chega vazio não apaga nada. As mudanças aparecem emcontact_updated.- Telefone inválido → aviso
phone_invalid; telefone de outro contato → não muda, avisophone_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.
- Telefone inválido → aviso
- Campos personalizados:
contact.custom_fieldsgrava 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_warningscomo{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"eassignment_error(team_not_foundouassignee_not_found). Um tipo impossível (por exemploteam_id: "abc") é 422. - Se atribuir:
"assignment":"assigned"eassigned_tocomteameagent(agentpode sernullse 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:
readnão volta paradelivered, efailedsó é 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"}]}, comresult=updated,unchangedounot_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":"..."}(oumessage_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-Deliverynemevent_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
sequencee as mensagens porsent_at. - Guarde os
event_idprocessados (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) oureply(respondeu).last_read_external_idé oidda última mensagem que o seu usuário enviou: você pode marcar como lidas todas as mensagens dele até essa.- No máximo um
conversation.reada 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.idestável por usuário e umidúnico por mensagem. - Você assina o corpo bruto exato, de preferência com
X-Omnifox-Timestampe o relógio sincronizado. - Você reenvia com o mesmo
idem caso de 5xx ou erro de rede. - Os anexos usam URLs públicas e permanentes.
- Se atribuir, você confere
assignmenteassignment_errorna resposta. - Você decidiu se vai unir com contatos existentes e criou no Omnifox os campos personalizados que vai enviar.
- O receptor verifica
sha256=sobrets + "." + corpo, responde 2xx em menos de 30 s (e 2xx aohealth_check), despacha porevent, deduplica porevent_ide ordena os eventos porsequence. - Você baixa
content.media_urlimediatamente. - Você devolve um
idao receber cada mensagem e o usa nas confirmaçõesdeliverederead.
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. |
Artigos relacionados
-
Códigos de erro do WhatsApp (Meta): o que significam e o que fazer
Tabela com os códigos de erro da Meta mais comuns ao enviar pelo WhatsApp (131026, 131047, 131049, 130497, 141006, 131031, 131056, 132000, 190, 368…) e como resolver cada um.
-
Como conectar o Telegram
Conecte um bot do Telegram à sua caixa de entrada do Omnifox em minutos usando o BotFather.
-
Comentários do Instagram e do Facebook: responder e moderar pelo Omnifox
Veja e responda os comentários das suas publicações e anúncios do Facebook e do Instagram, em público ou no privado, e configure respostas automáticas.
-
Enviar e receber vídeos em cada canal: formatos e tamanhos máximos
Quais vídeos você pode enviar e receber pelo WhatsApp, Instagram, Messenger, Telegram, chat do site e e-mail, com os tamanhos máximos reais e o que fazer com um vídeo pesado.
-
Conectar o WhatsApp escaneando um código QR
Vincule seu WhatsApp ao Omnifox em um minuto, como no WhatsApp Web. Ideal para testar: tem limites, não permite campanhas e não é a API oficial.