Canal personalizado: o que é e como configurar

Conecte seu próprio sistema (app, plataforma ou CRM sob medida) ao Omnifox com o canal personalizado: como funciona e como configurar passo a passo.

Jul 11, 2026

O canal personalizado (no seletor aparece como Custom Channel) conecta ao Omnifox qualquer sistema próprio que não tenha um conector nativo: seu app, sua plataforma de reservas, um chat interno, um sistema de tickets ou um CRM feito sob medida. As mensagens dos seus usuários chegam à caixa de entrada do Omnifox como as de qualquer outro canal, e as respostas dos seus agentes, do agente de IA ou dos seus fluxos voltam para o seu sistema.

Este artigo explica o que é e como configurá-lo pela tela. Para a parte de programação (formato das mensagens, assinatura, eventos e exemplos de código), compartilhe com seu desenvolvedor o Guia técnico de integração do canal personalizado.

Conteúdo

  1. Como funciona
  2. Antes de começar
  3. Criar o canal passo a passo
  4. Unir com contatos existentes: quando ativar
  5. O que acontece quando o canal está ativo
  6. O que o canal personalizado não faz
  7. Problemas frequentes

1. Como funciona

O canal usa dois endereços web e uma chave:

  • URL do webhook de entrada: gerada pelo Omnifox. Seu sistema envia para ela cada mensagem dos seus usuários.
  • URL do webhook de saída: informada por você. O Omnifox envia para ela as respostas e os avisos do que acontece na conversa (atribuída, fechada, lida…).
  • Chave secreta: uma única chave assina as mensagens nos dois sentidos, para que ninguém possa se passar pelo seu sistema nem pelo Omnifox.

Cada mensagem recebida identifica a pessoa com um ID de contato (o ID desse usuário no seu sistema). Cada ID diferente é um contato diferente no Omnifox, com sua própria conversa.

2. Antes de começar

  • O canal personalizado está incluído nos planos Escala e Exclusivo.
  • Seu sistema precisa conseguir enviar requisições HTTP com JSON e receber as que o Omnifox envia em um endereço público com HTTPS. Normalmente quem configura é o seu desenvolvedor.
  • Escolha um nome claro para o canal, por exemplo App de reservas ou Portal de clientes.

3. Criar o canal passo a passo

  1. Vá em Configurações → Canais → Conectar novo canal e escolha Custom Channel.
  2. Digite o Nome do canal.
  3. Copie a URL do webhook de entrada com o botão de copiar e passe para o seu desenvolvedor. Ela é gerada uma única vez e não muda ao editar o canal. Começa a receber mensagens assim que você salva o canal.
  4. Em URL do webhook de saída, cole o endereço do seu sistema para onde o Omnifox deve enviar as respostas, por exemplo https://seu-sistema.com/omnifox. É opcional, mas sem ela o canal só recebe: as respostas dos agentes e da IA ficam como falhas.
  5. Copie a Chave secreta e entregue ao seu desenvolvedor por um meio seguro. Se ela vazar, clique em Regenerar, salve o canal e atualize a chave no seu sistema: a anterior deixa de funcionar.
  6. Em Unir com contatos existentes, deixe Unir por telefone e Unir por e-mail desativadas, a menos que tenha certeza de que precisa delas (veja a seção 4).
  7. Em Eventos a enviar, escolha quais avisos seu sistema deve receber além das mensagens (que são enviadas sempre): conversa criada, atribuída ou transferida, fechada, reaberta, prioridade alterada, etiqueta adicionada, a IA passou a conversa para uma pessoa, o agente leu a conversa, entre outros. Todos vêm marcados.
  8. Mapeamento de campos (opcional): use apenas se o seu sistema não conseguir enviar o formato padrão do Omnifox. Clique em Adicionar e, em cada linha, escreva à esquerda o caminho do dado no seu JSON (por exemplo data.user.id) e escolha à direita o campo do Omnifox que ele preenche. Detalhes em Canal personalizado: mapeamento de campos.
  9. Clique em Continuar. Se você informou uma URL de saída, o Omnifox envia para ela uma mensagem de teste assinada e espera uma resposta de sucesso (código 2xx) em até 5 segundos. Se o seu sistema não responder corretamente, você verá o erro e o canal não é salvo até que seja corrigido. Se a URL de saída ficou vazia, o canal é salvo diretamente.

Dica: se o seu sistema ainda não está pronto para receber, crie o canal sem URL de saída, teste a entrada de mensagens e adicione a URL depois, editando o canal.

4. Unir com contatos existentes: quando ativar

Essas duas opções definem o que acontece com a primeira mensagem de um ID de contato novo:

  • Desativadas (recomendado): cada usuário do seu sistema cria seu próprio contato no Omnifox. Se o telefone dele já pertence a outro contato, o novo é criado sem telefone para não misturá-los.
  • Unir por telefone: se já existe um contato com esse telefone (por exemplo, porque ele já escreveu antes pelo WhatsApp), o usuário é vinculado a esse contato.
  • Unir por e-mail: se não houve correspondência por telefone, o Omnifox procura um contato com o mesmo e-mail.

Atenção: com essas opções ativadas, duas pessoas diferentes que compartilham telefone ou e-mail (uma família, um escritório, um e-mail genérico como contato@) acabariam no mesmo contato e na mesma conversa. Ative-as somente se, no seu sistema, cada telefone ou e-mail pertencer a uma única pessoa.

5. O que acontece quando o canal está ativo

  • As mensagens dos seus usuários entram na Caixa de entrada com texto, imagens, vídeo, áudio ou arquivos.
  • Tudo funciona como nos outros canais: atribuição por equipes, agente de IA do canal, fluxos e automações, etiquetas e notificações.
  • Seu sistema pode pedir que uma conversa nova vá para uma equipe ou um agente específico, e pode atualizar o nome, telefone, e-mail e campos personalizados do contato.
  • Quando alguém responde, o Omnifox envia a resposta para a sua URL de saída indicando quem respondeu: uma pessoa, o agente de IA ou um fluxo.
  • Seu sistema pode informar quando seu usuário recebeu e leu cada resposta, e a caixa de entrada mostra as marcas de entregue e lido.

6. O que o canal personalizado não faz

  • Não mostra o indicador "digitando…".
  • Não permite editar nem apagar mensagens, nem reações.
  • Aceita uma única URL de saída por canal.
  • Não se aplica a janela de 24 horas do WhatsApp: você pode responder a qualquer momento.

7. Problemas frequentes

  • Ao clicar em Continuar aparece um erro do webhook: sua URL de saída não respondeu com código 2xx em 5 segundos. Verifique se o endereço está correto e é público, ou deixe-o vazio por enquanto.
  • Nenhuma mensagem chega: confirme com seu desenvolvedor que ele usa a URL de entrada exata e a chave secreta atual (se você clicou em Regenerar, a anterior não funciona mais).
  • As respostas aparecem em vermelho como falhas: falta a URL de saída ou o seu sistema está recusando as requisições.
  • Todas as mensagens caem no mesmo contato: seu sistema está enviando o mesmo ID de contato para todos os usuários.
  • Um usuário apareceu dentro de um contato que já existia: alguma opção de Unir com contatos existentes está ativada.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp