Canal personalizado: mapeamento de campos

Use o mapeamento de campos para que o Omnifox entenda o JSON do seu sistema sem alterá-lo. Vale apenas para mensagens de entrada.

Jul 11, 2026

O mapeamento de campos do canal personalizado serve para quando o seu sistema não consegue enviar as mensagens no formato padrão do Omnifox. Em vez de alterar o seu sistema, você indica ao Omnifox em que parte do seu JSON está cada dado.

Nota: o mapeamento é somente de entrada (mensagens que chegam do seu sistema). O que o Omnifox envia para a sua URL de saída tem sempre o mesmo formato, descrito no Guia técnico de integração: o seu sistema precisa se adaptar a ele.

Quando você precisa dele

  • Não precisa se o seu sistema já envia contact.id, text, id e, quando for o caso, media ou attachments com esses nomes.
  • Precisa se o seu sistema já gera um JSON próprio que você não pode mudar, por exemplo {"data":{"user":{"uid":"..."}}}.

Como configurar

  1. Abra o canal em Canais e edite-o (ou configure ao criá-lo).
  2. Em Mapeamento de campos, clique em Adicionar.
  3. À esquerda, escreva o caminho do dado no seu JSON, com pontos: data.user.id. Para listas, use o número da posição: items.0.url. Você pode começar o caminho com $. se preferir.
  4. À direita, escolha o campo do Omnifox que esse dado preenche.
  5. Repita para cada dado e clique em Continuar para salvar.

Campos do Omnifox disponíveis

Campo do Omnifox Para que serve
ID do contato (obrigatório) O ID do usuário no seu sistema. Se não chegar direto nem mapeado, a mensagem é recusada.
Nome, telefone, e-mail e URL da foto do contato Dados do contato.
Texto da mensagem O texto.
Tipo de mensagem text, image, video, audio ou file.
ID da mensagem (deduplicação) Evita duplicados se o seu sistema reenviar a mesma mensagem.
URL, legenda, tipo MIME e nome do arquivo de mídia Um anexo. Se você mapear algum deles, a lista attachments da mensagem é ignorada.
Lista de anexos Uma lista completa de anexos.
Equipe (id ou nome) e Agente (id ou e-mail) Para quem vai uma conversa nova ou sem atribuição.
Campo personalizado: nome Aparece um para cada campo personalizado de contato criado no seu espaço de trabalho.

Regras

  • O que você mapeia tem prioridade sobre um campo com o nome padrão.
  • Se o caminho não existir em uma mensagem específica, essa linha simplesmente não faz nada.
  • A assinatura da mensagem é sempre verificada sobre o seu JSON original; o mapeamento é aplicado depois.
  • Os caminhos são simples: não aceitam curingas, filtros nem transformações.

Exemplo

Seu sistema envia:

{"data":{"user":{"uid":"user-M","nombre":"Mario"},"msg":{"mid":"m-1","cuerpo":"Olá","foto":"https://cdn.example.com/a.jpg"}}}

Com estas linhas:

Caminho no seu JSON Campo do Omnifox
data.user.uid ID do contato
data.user.nombre Nome do contato
data.msg.cuerpo Texto da mensagem
data.msg.mid ID da mensagem
data.msg.foto URL da mídia

O Omnifox cria o contato user-M com o nome "Mario" e uma mensagem de imagem com a legenda "Olá".

Problemas frequentes

  • Erro de contact.id obrigatório: o caminho do ID do contato não corresponde ao seu JSON. Confira maiúsculas, pontos e níveis.
  • A mensagem chega sem texto ou sem imagem: o caminho desse dado está escrito errado ou aponta para outro nível.
  • Meu sistema espera outro formato nas respostas: não existe mapeamento de saída; adapte o seu receptor ao formato fixo do Omnifox.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp