Conectar um Canal Personalizado (Custom Channel via webhook)

O Canal Personalizado (aparece no seletor de tipo como Custom Channel) é a "porta de escape" para conectar qualquer sistema próprio ou legado que a Omnifox ainda não suporte nativamente: um CRM interno, um chat proprietário, um sistema de tickets sob medida. Funciona com duas URLs: uma que a Omnifox te dá para receber mensagens, e outra que você informa para a Omnifox enviar as mensagens de saída.

Requisitos

• Um sistema externo capaz de receber requisições HTTP POST com JSON e expor um endpoint próprio
• Um nome descritivo para o canal (por exemplo "CRM interno" ou "Sistema legado")

Passos para conectar

1. Na Omnifox, vá em Canais → Conectar novo canal e escolha Custom Channel.
2. Salve o canal para que a Omnifox gere a Incoming Webhook URL e uma Secret Key (ambas somente leitura, com botão de copiar).
3. Preencha a Outgoing Webhook URL: o endereço do seu sistema para onde a Omnifox vai enviar as mensagens de saída.
4. Configure seu sistema externo para enviar as mensagens recebidas (JSON) para a Incoming Webhook URL da Omnifox.
5. Opcional: configure os Field Mappings (veja o artigo dedicado ao mapeamento de campos) se o seu payload não usar os nomes padrão.

Configuração

• Incoming Webhook URL: recebe JSON do seu sistema; usada para criar mensagens recebidas no Inbox.
• Outgoing Webhook URL: para onde a Omnifox faz POST quando um atendente responde.
• Secret Key: assina cada requisição de saída com HMAC-SHA256 (headers X-Omnifox-Signature, X-Omnifox-Timestamp, X-Omnifox-Channel-Type, X-Omnifox-Delivery).

Exemplo

Um sistema interno de tickets recebe um pedido de suporte e envia via POST ao webhook da Omnifox {"text": "preciso de ajuda", "sender": "João", "id": "tk_123"}. Essa mensagem aparece no Inbox; quando um atendente responde, a Omnifox faz POST para sua Outgoing Webhook URL com o corpo padrão (message_id, conversation_id, recipient, content, etc.).

Dicas

• Sempre verifique a assinatura HMAC no seu sistema antes de processar uma requisição: isso impede que terceiros injetem mensagens falsas.
• Se seu sistema retornar 4xx, a Omnifox trata como erro fatal (sem retry); em 5xx ou timeout, ela tenta novamente até 3 vezes com backoff.

Solução de problemas

• As mensagens de saída não chegam: verifique se sua Outgoing Webhook URL responde com 2xx em até 30 segundos.
• Mensagens recebidas não aparecem no Inbox: confirme que está postando para a Incoming Webhook URL exata fornecida pela Omnifox, com Content-Type application/json.