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.
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
- Como funciona
- Antes de começar
- Criar o canal passo a passo
- Unir com contatos existentes: quando ativar
- O que acontece quando o canal está ativo
- O que o canal personalizado não faz
- 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
- Vá em Configurações → Canais → Conectar novo canal e escolha Custom Channel.
- Digite o Nome do canal.
- 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.
- 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. - 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.
- 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).
- 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.
- 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. - 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
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.