A automação confiável separa quatro responsabilidades: canal, orquestração, sistema de registro e atendimento humano. Quando tudo fica em um único fluxo visual, uma falha pequena pode duplicar mensagens ou apagar contexto.
Arquitetura recomendada
- Relya recebe ou envia. Cuida da conexão, fila, mídia e eventos.
- Webhook entra na orquestração. n8n, Make ou backend próprio valida e coloca o evento em uma fila.
- CRM guarda o estado de negócio. Cliente, oportunidade, ticket, responsável e próxima ação.
- Motor de regras decide. Pode ser código, automação ou IA, com limites.
- API envia a resposta. Cada ação usa chave de idempotência.
- Status volta por webhook. O CRM registra envio, entrega, leitura ou falha.
O CRM deve continuar sendo a fonte da verdade comercial. A plataforma de mensagens registra o transporte; a automação coordena; o CRM responde “o que este contato representa para o negócio”.
Entrada: valide antes de agir
O webhook não deve chamar uma IA diretamente. Primeiro valide a assinatura, deduplique pelo x-relya-delivery-id e grave o evento. Depois um worker ou workflow executa as ações.
Se o CRM estiver lento, o webhook ainda responde rápido. Se o workflow falhar, o evento permanece para nova tentativa. Se houver pico, a fila absorve sem derrubar a entrada.
Normalize o contato. Um mesmo telefone pode chegar com variações de formatação. Guarde o valor original para auditoria, mas derive uma chave interna consistente. Nunca una contatos apenas por nome.
Estado da conversa e contexto
Uma automação precisa saber se a pessoa está aguardando orçamento, enviando documento, pedindo suporte ou falando com um atendente. Guarde estado explícito, com validade e responsável.
| Campo | Exemplo | Por que existe |
|---|---|---|
conversation_state | awaiting_document | Evita interpretar toda mensagem do zero. |
human_owner | equipe_comercial | Define quem pode assumir. |
bot_muted_until | data/hora | Impede o robô de interromper o humano. |
last_inbound_id | ID do evento | Ajuda a evitar reprocessamento. |
business_action_id | orcamento-9842 | Vira chave de idempotência do envio. |
Contexto não significa guardar tudo para sempre. Defina retenção, acesso e finalidade. Para IA, envie apenas o trecho necessário e não exponha credenciais nem documentos sem necessidade.
Saída: uma resposta não é uma entrega
Ao decidir responder, monte a mensagem, gere uma chave ligada à ação e chame a API. Um exemplo de texto:
POST https://relya.com.br/send/text
token: SUA_CREDENCIAL
idempotency-key: ticket-9842-resposta-1
content-type: application/json
{
"number": "5521999999999",
"text": "Recebemos o documento. Vou encaminhar para análise."
}Registre a resposta inicial como enfileirada. Atualize o CRM somente com os eventos reais. Se o transporte falhar, mostre isso para a operação em vez de considerar o atendimento concluído.
Handoff humano sem disputa com o robô
O pior desenho é humano e automação responderem ao mesmo tempo. Crie um estado de posse:
- quando um atendente assume, marque
human_active; - enquanto ativo, eventos entram no CRM, mas não geram resposta automática;
- o atendente encerra ou define um tempo de devolução;
- mensagens críticas podem acionar humano e manter o bot mudo;
- toda mudança de posse entra na auditoria.
IA deve ter limites operacionais. Cobrança, cancelamento, alteração contratual, emergência e dado sensível podem exigir aprovação humana. A regra precisa estar no fluxo, não só no prompt.
Exemplo de fluxo no n8n
- Webhook: recebe o evento com corpo bruto e cabeçalhos.
- Code: valida HMAC e timestamp.
- Banco: tenta inserir o delivery ID único.
- Respond to Webhook: devolve
204depois da persistência. - Switch: separa mensagem, status e conexão.
- CRM: busca ou cria contato/ticket.
- IF: verifica posse humana e política.
- Regra/IA: propõe a ação dentro dos limites.
- HTTP Request: chama a Relya com idempotência.
- Log: grava request sanitizado, resposta e correlação.
n8n e Make são exemplos de orquestradores; a Relya não é afiliada a essas marcas. O mesmo desenho funciona em código com fila e workers.
Checklist antes de ativar
- Webhook com HMAC, timestamp e deduplicação.
- Fila entre entrada e processamento demorado.
- CRM definido como fonte da verdade comercial.
- Estados de conversa explícitos e com validade.
- Handoff humano que realmente silencia a automação.
- Idempotência em todas as ações de saída.
- Status final atualizado por evento.
- Alarmes para desconexão, backlog e falha repetida.
- Teste com mídia, mensagens rápidas, reordenação e duplicação.
- Boas práticas de contato e pedido de saída.
Antes de montar o workflow, leia como receber eventos com segurança e a política operacional recomendada.
Escopo
Este artigo descreve um padrão de arquitetura, não uma integração nativa exclusiva. Recursos de ferramentas de terceiros devem ser confirmados nas respectivas documentações.