Migrar do Chatwoot não é apenas exportar uma lista de contatos. Uma operação de atendimento também contém conversas, mensagens, notas internas, anexos, caixas de entrada, agentes, equipes, etiquetas, atributos personalizados, automações, webhooks e credenciais mantidas por provedores externos.
Por isso, “migrar sem perder dados” não deve ser tratado como promessa absoluta. O objetivo profissional é reduzir o risco, provar o que foi transferido e manter um caminho de retorno. Para isso, a migração precisa de inventário, ensaio, critérios de aceite e reconciliação.
Este guia apresenta um processo para avaliar a mudança do Chatwoot para o NooviChat ou outra plataforma. O método serve tanto para Chatwoot Cloud quanto para instalações self-hosted, mas a rota técnica muda conforme o acesso disponível, as versões e o destino.
O que significa migrar do Chatwoot sem perder dados?
Uma migração controlada preserva as informações definidas no escopo e comprova o resultado com contagens, amostras e testes. Ela não presume que todos os objetos de duas plataformas possuem a mesma estrutura.
Antes de escolher uma ferramenta ou fornecedor, transforme “todos os dados” em uma lista objetiva:
- contatos e identificadores;
- etiquetas e atributos personalizados;
- caixas de entrada e associações de contato;
- conversas, status, responsáveis e equipes;
- mensagens públicas e notas internas;
- anexos e metadados dos arquivos;
- automações, macros e respostas salvas;
- webhooks e integrações;
- agentes, permissões e configurações;
- credenciais e autorizações de canais.
Cada item precisa de quatro respostas: como extrair, como transformar, como importar e como validar. Se uma classe não tiver resposta, ela é uma pendência do projeto, não algo que deve ser escondido em uma promessa genérica.
Comece pelo cenário de origem
O método depende de como o Chatwoot está operando hoje.
Chatwoot Cloud ou ambiente sem acesso ao banco
Quando a empresa não controla banco e armazenamento, a migração tende a usar exportações disponíveis e APIs autorizadas. A documentação oficial oferece endpoints para listar contatos, conversas, mensagens e caixas de entrada, mas isso não equivale a um exportador completo pronto para qualquer destino.
A extração precisa respeitar paginação, permissões do token, limites de uso e relacionamentos entre entidades. Também deve registrar falhas e permitir retomada sem duplicar o que já foi processado.
Chatwoot self-hosted sob controle da empresa
No self-hosted, pode existir acesso ao PostgreSQL, ao storage, às variáveis de ambiente e às customizações. A documentação oficial de backup trata esses componentes separadamente. Isso é importante: um arquivo de banco, sozinho, não representa necessariamente os anexos nem toda a configuração operacional.
Ter acesso ao backup amplia as opções, mas não autoriza presumir compatibilidade direta com outro produto, fork ou versão. Schema, migrations, extensões, armazenamento e código podem divergir.
Instalação customizada ou muito defasada
Customizações e diferenças de versão aumentam o risco. Registre versão da aplicação, versão do PostgreSQL, storage, jobs, integrações e alterações locais. Um ensaio em ambiente isolado passa a ser obrigatório para descobrir incompatibilidades antes do corte.
Faça um inventário antes de exportar
O inventário cria o baseline usado na validação final. Salve a data e o horário da coleta e registre, quando disponível:
| Classe | Baseline recomendado |
|---|---|
| Contatos | total, contatos com e sem email/telefone, duplicidades |
| Conversas | total por inbox, status, período e responsável |
| Mensagens | total por tipo, primeira e última data, notas internas |
| Anexos | quantidade, bytes, tipos MIME e arquivos indisponíveis |
| Inboxes | tipo de canal, estado e responsável pela credencial |
| Agentes/equipes | usuários ativos, papéis e associações |
| Automações | regra, gatilho, ação e dependência externa |
| Webhooks | endpoint, eventos, assinatura e consumidor |
Não dependa apenas de uma contagem global. Migrações podem parecer completas enquanto perdem um canal antigo, notas internas ou mensagens de um período específico.
Também classifique o que precisa ser:
- preservado com fidelidade, como documentos que suportam atendimento ou obrigação legal;
- recriado funcionalmente, como regras e integrações;
- arquivado para consulta, quando o destino não oferece importação equivalente;
- descartado de forma aprovada, conforme política de retenção e base legal.
O que a exportação de contatos realmente cobre
A API oficial do Chatwoot documenta uma listagem paginada de contatos resolvidos — registros com identificador, email ou telefone. Isso exige cuidado com paginação e com contatos que não atendam a esses critérios.
O projeto também possui fluxo de exportação CSV de contatos. No código oficial consultado, as colunas padrão incluem ID, nome, email, telefone e etiquetas, com possibilidade de colunas adicionais válidas conforme a solicitação e a versão.
O ponto decisivo é o limite de escopo:
Um CSV de contatos não é um backup de conversas, mensagens, anexos, canais ou configurações.
Use o CSV para inventário, saneamento ou uma parte da carga. Se o projeto precisa preservar histórico, planeje outra rota para conversas e mensagens.
Migração por API: quando usar e como controlar
A rota por API costuma fazer sentido quando não existe acesso ao banco, o destino não aceita restauração ou as estruturas precisam ser transformadas.
Respeite a ordem das entidades
Uma sequência conceitual pode ser:
- atributos, etiquetas e estruturas auxiliares;
- contatos;
- caixas de entrada ou mapeamentos de canal;
- associações entre contatos e inboxes;
- conversas;
- mensagens e notas internas;
- anexos;
- responsáveis, equipes e estados compatíveis.
A ordem real depende das APIs e do modelo do destino. Não reutilize um ID de origem como se ele fosse válido no destino. Crie uma tabela de correspondência entre IDs antigos e novos.
Trate paginação e retomada
A extração deve salvar cursor ou página processada, resposta, erro e horário. A importação precisa ser idempotente: repetir um lote não pode criar contatos e conversas duplicados silenciosamente.
Ao final, execute uma segunda varredura para conferir alterações que aconteceram durante o processamento.
Diferencie leitura de restauração histórica
A documentação do Chatwoot oferece endpoints para listar conversas e mensagens. Isso comprova que o histórico pode ser lido dentro das permissões e da paginação documentadas.
Não comprova que outro sistema aceite recriar exatamente:
- IDs originais;
- timestamps de criação;
- remetentes históricos;
- status de entrega e leitura;
- eventos de sistema;
- vínculos com canais;
- URLs ou chaves originais de anexos.
Se o destino não preservar um campo, decida se ele será transformado, guardado em metadado ou mantido em arquivo somente leitura.
Migração por backup self-hosted: banco não é tudo
A documentação oficial de backup do Chatwoot separa quatro áreas: PostgreSQL, storage, variáveis de configuração e customizações de código.
Banco de dados
O banco contém relacionamentos essenciais, mas sua restauração depende de compatibilidade de versão, schema, migrations e aplicação. Restauração direta deve ser ensaiada e aprovada tecnicamente.
Storage e anexos
Anexos podem estar em armazenamento local ou serviço de objetos. Quando o storage é local, a documentação recomenda copiar a pasta correspondente; em S3, GCS ou serviços similares, é necessário proteger ou copiar os objetos conforme o provedor.
Um backup do PostgreSQL sem o storage pode manter referências para arquivos que não existem mais. Valide os bytes, não apenas as linhas do banco.
Configuração e customizações
Variáveis de ambiente, chaves, email transacional, storage e serviços conectados fazem parte do funcionamento. Customizações locais também precisam de inventário separado. Copiar configuração sem revisão pode expor segredos ou apontar o novo ambiente para serviços errados; trate credenciais por fluxo seguro.
Por que um fork não garante restore direto
Dois sistemas compartilharem origem no Chatwoot não prova que seus bancos sejam intercambiáveis. Versões, migrations, módulos e estruturas podem ter evoluído de forma diferente.
A formulação segura é: um restore pode ser avaliado em staging quando a combinação de versões, banco, storage e código tiver sido validada. Não é correto prometer “basta restaurar o banco”.
Conversas e anexos exigem validação própria
O histórico é uma cadeia de relacionamentos. Um contato pode estar associado a uma inbox; a conversa pertence a uma conta e a um canal; mensagens podem possuir remetente, tipo, privacidade e anexos.
Monte amostras que incluam:
- conversa antiga, recente e ainda aberta;
- contato com mais de uma inbox;
- mensagem pública e nota interna;
- anexos de imagem, documento, áudio e vídeo;
- mensagens enviadas por agente e recebidas pelo canal;
- conversa com atribuição, equipe, etiquetas e atributos;
- registro com caracteres especiais e campos vazios.
Para anexos, confira pelo menos:
- quantidade esperada e encontrada;
- tamanho do arquivo;
- tipo MIME;
- possibilidade de download;
- vínculo com a mensagem correta;
- hash de uma amostra ou do acervo, quando viável.
Uma URL responder não garante que o arquivo seja o mesmo. Uma linha existir não garante que o objeto esteja no storage.
Canais não são apenas dados do Chatwoot
WhatsApp, Instagram, Facebook, email, SMS, voz e canais de API possuem regras, credenciais e dependências diferentes. A própria documentação do Chatwoot mostra diferenças de janela de envio, anexos, status e capacidade por canal.
Durante a migração, separe:
- dados internos da inbox;
- número, conta ou identidade externa;
- token e autorização do provedor;
- endpoint de webhook;
- templates e políticas do canal;
- DNS, SMTP ou credenciais relacionadas;
- período permitido para corte e testes.
Não presuma que copiar uma tabela mantém o WhatsApp ou outro canal conectado. Reconexões podem exigir ação no provedor, novas credenciais ou validação de propriedade.
No caso do WhatsApp, a migração não elimina políticas da Meta, consentimento, LGPD ou regras de templates e janelas. Nenhum projeto de migração deve prometer anti-ban, envio irrestrito ou contorno de políticas.
Use webhooks para a janela de transição — não como backup
Quando a extração leva horas ou dias, novos contatos e mensagens podem surgir depois do primeiro lote. Webhooks podem ajudar a capturar alterações durante essa janela.
Um fluxo controlado é:
- registrar o baseline;
- iniciar captura de eventos novos;
- fazer a exportação principal;
- importar e validar em staging;
- aplicar os deltas capturados;
- definir horário de corte;
- executar varredura final e reconciliação.
Webhooks não substituem backup nem backfill. Eles começam a observar eventos após sua configuração, podem exigir retry e idempotência e não devem ser tratados como prova de entrega exatamente uma vez. Mantenha uma varredura final pela fonte.
Ensaie antes do corte
O ensaio deve usar uma cópia isolada e representativa, sem conectar acidentalmente canais de produção. Ele serve para medir tempo, descobrir incompatibilidades e testar scripts de retomada.
Critérios de aceite mínimos
Defina os critérios antes de executar:
- contagem de contatos por segmento dentro do esperado;
- atributos e etiquetas mapeados;
- conversas por inbox e período reconciliadas;
- mensagens e notas internas amostradas;
- anexos disponíveis e associados corretamente;
- agentes, equipes e permissões revisados;
- automações recriadas e testadas;
- integrações e webhooks observáveis;
- busca, filtros e relatórios avaliados;
- canais testados com casos controlados;
- erros documentados e tratados.
“Parece funcionar” não é critério de aceite. Registre números, amostras e responsáveis.
Planeje corte, rollback e retenção
Escolha uma janela de menor impacto e comunique quem decide avançar ou voltar. Antes do corte:
- gere um backup final da origem;
- registre o horário e os identificadores de fronteira;
- interrompa mudanças que possam comprometer a consistência, quando aplicável;
- confirme saúde do destino;
- valide credenciais por fluxo seguro;
- deixe o rollback executável.
Depois do corte, mantenha a origem preservada ou em modo somente leitura pelo período definido pela empresa, pelo contrato e pelas obrigações legais. Não apague dados apenas porque a primeira validação passou.
Defina RPO e RTO coerentes com a operação, mas não prometa zero perda ou zero indisponibilidade sem arquitetura e testes que sustentem isso.
Onde o NooviChat entra na migração
O NooviChat não é open-source. É uma distribuição privada/licenciada baseada em fork modificado do Chatwoot, comercializada por licença/acesso à imagem Docker.
As documentações públicas do NooviChat apresentam APIs para contatos, conversas, mensagens, inboxes e webhooks. Essas superfícies permitem planejar inventário e integração, mas não constituem garantia de importação automática, compatibilidade integral de banco ou preservação universal de IDs, datas, anexos e canais.
A licença comercial do NooviChat é contratual e própria da distribuição. Ela não é a Chatwoot Enterprise License, não implica afiliação ou endosso da Chatwoot Inc. e não substitui avisos, atribuições ou licenças aplicáveis ao código de origem e a terceiros.
Antes de contratar uma migração para o NooviChat, confirme no escopo vigente:
- versão e cenário de origem suportados;
- método avaliado: API, backup ou serviço assistido;
- tratamento de banco e storage;
- classes de dados incluídas e excluídas;
- remapeamento de IDs e timestamps;
- canais que exigirão reconexão;
- ambiente de ensaio;
- critérios de aceite e rollback;
- responsabilidade por infraestrutura, credenciais e serviços externos.
A origem comum pode facilitar o entendimento técnico, mas a compatibilidade precisa ser demonstrada no cenário real.