Uma instância representa uma conexão WhatsApp que sua integração administra. Em projetos com mais de um número, nomeie cada instância de forma reconhecível e armazene o ID junto à finalidade, ao ambiente e à equipe responsável. Isso reduz o risco de uma automação chamar o número errado.
- 01Escolha o ambiente correto
- 02Localize o ID da instância
- 03Use o ID na rota da API
- 04Confira estado e destinatário
Planeje a separação
Antes de criar novas instâncias, decida se elas representam equipes, operações, marcas ou ambientes de teste. Separe as credenciais e configurações de acordo com o que o produto e seu plano permitem. Cada ambiente Cloud tem URL, API e banco próprios; não confunda vários ambientes Cloud com várias instâncias dentro de um ambiente.
Nas chamadas, o identificador da instância aparece no caminho, por exemplo /v1/instances/{id}/messages/text. Associe esse ID à sua configuração no servidor, não a um valor digitado livremente pelo usuário final.
Confira limites e capacidade
O número de instâncias incluído depende do plano StackZap Cloud contratado e pode mudar. Confira o valor atual em stackzap.com.br/#planos antes de dimensionar uma operação. Para self-hosted, a capacidade também depende dos recursos e da configuração que você opera.
Mantenha monitoramento de estado por instância e trate connection.update quando esse evento estiver habilitado na sua versão. Se uma sessão cair, reconecte a instância identificada, sem recriar as demais. Veja a documentação técnica para os endpoints de criação, consulta e conexão.
Separe ambientes de instâncias
Uma instalação StackZap Cloud e uma instância de WhatsApp são conceitos diferentes. Cada ambiente Cloud tem sua própria URL, API e banco provisionados; dentro dele, sua aplicação pode administrar instâncias conforme os recursos e limites do plano. Uma instância representa uma conexão vinculada a uma conta. Um segundo ambiente não é automaticamente um segundo número dentro do mesmo banco, e uma segunda instância não cria necessariamente outro ambiente isolado.
Desenhe essa topologia antes de ampliar. Uma empresa pode ter ambientes separados para produção e homologação e, dentro do ambiente de produção, instâncias para atendimento e operações diferentes. Essa escolha afeta credenciais, monitoramento, webhooks, backups e permissões. Confirme no painel e na página de planos os limites aplicáveis; valores comerciais podem mudar.
Crie nomes e cadastro previsíveis
Use nomes que indiquem finalidade e estágio, como suporte-producao ou pedidos-homologacao. Evite nomes iguais e dados pessoais. Mantenha no seu sistema um cadastro com ID da instância, ambiente, finalidade, estado, equipe responsável e data de criação. Não use o nome como chave primária: a aplicação deve usar o ID retornado pela API.
Armazene esse mapeamento em configuração protegida. Uma tela administrativa pode selecionar apenas instâncias autorizadas ao usuário atual; não aceite um ID arbitrário enviado pelo navegador sem validar que pertence à conta e à finalidade. Para agentes de IA, defina instâncias permitidas em cada ferramenta.
Encaminhe cada operação ao ID correto
Como o identificador aparece no caminho do endpoint, crie um cliente que receba a instância como objeto validado, em vez de concatenar qualquer string fornecida pelo usuário. Antes do envio, verifique estado e ambiente; antes de processar webhook, identifique qual instância originou o evento, se o payload informa isso. Associe também a chamada ao tenant ou negócio correto para evitar vazamento cruzado.
Uma configuração centralizada reduz erros como misturar URL de homologação e ID de produção. Armazene os dados como pares coerentes: URL base, API Key e IDs daquele ambiente. Nunca escolha automaticamente “a primeira instância” de uma lista sem regra explícita, pois a ordenação pode mudar.
Planeje eventos e observabilidade por conexão
Se cada instância pode desconectar independentemente, acompanhe o estado por ID e alerte a equipe responsável por aquele número. Uma métrica agregada pode esconder que uma conexão crítica caiu enquanto outras continuam ativas. Inclua ambiente e instância nos logs, mas não a chave ou o conteúdo das conversas.
Webhooks podem servir vários números. Confirme como o contrato identifica a origem e valide a assinatura em cada entrega. Use ID de entrega para deduplicar e encaminhe eventos apenas para a partição correspondente. Um callback compartilhado pode ser conveniente, mas precisa de autorização e isolamento corretos.
Considere limites e capacidade
Cada número adicional exige operação: pareamento, monitoramento, atendimento, gestão de credenciais e tratamento de indisponibilidade. Não crie instâncias como resposta automática para falhas de conexão. Consulte o limite comercial do plano Cloud na página atual e avalie o que o self-hosted consegue suportar com os recursos que você opera. Para crescer, estime concorrência e volume diário em vez de olhar apenas para quantidade de números.
Defina o que ocorre quando o plano ou capacidade chega ao limite: bloquear novas criações, solicitar mudança de plano ou usar outro ambiente. A interface deve explicar a condição e não iniciar provisionamentos repetidos por cliques sucessivos.
Desative com segurança
Antes de remover uma conexão, identifique consumidores de webhook, filas pendentes, regras no Chatwoot e integrações que guardam o ID. Pause operações, retenha apenas dados permitidos pela política aplicável, desconecte pelo procedimento e remova a configuração dos serviços que não devem mais acessá-la. Não apague histórico necessário para explicar uma entrega antiga.
Quando uma equipe muda, revise permissões e responsáveis, não apenas o nome. Se um número for transferido, trate a mudança como operação planejada e valide novo pareamento e callbacks.
Checklist multi-instância
- Separação entre ambientes e números está documentada.
- IDs são armazenados, validados e associados à finalidade.
- Usuários e agentes só acessam instâncias autorizadas.
- URL, API Key e ID pertencem ao mesmo ambiente.
- Estado e alertas são acompanhados por instância.
- Webhooks identificam origem e deduplicam entregas.
- Limites e volume foram verificados antes de crescer.
- Desativação considera filas, callbacks e integrações dependentes.
Faça provisionamento rastreável
Se sua aplicação cria instâncias via API, associe a criação a um registro de negócio antes de chamar o endpoint. Guarde a solicitação, o ambiente escolhido e o resultado retornado; não crie outra instância só porque a interface demorou para atualizar. Timeout durante provisionamento pode deixar o resultado incerto. Consulte a lista ou mecanismo de busca documentado antes de tentar novamente.
Use um processo de aprovação para criar números em produção. Valide finalidade, responsável e cota disponível, e proteja a ação contra cliques repetidos. Em sistemas multi-tenant, garanta que um cliente não consiga selecionar ID de instância pertencente a outro. Registre quem pediu a criação e quem aprovou, sem guardar credenciais nos metadados.
Teste isolamento e rotas
Em homologação, crie pelo menos duas instâncias de teste e confirme que cada uma usa o ID correto nas chamadas, recebe os eventos correspondentes e mantém configuração separada. Isso encontra bugs de fallback para “instância padrão” e cache compartilhado incorreto. Use dados sintéticos e números sob controle da equipe.
Se um webhook atende várias instâncias, valide a relação entre evento e ambiente antes de encaminhar para CRM ou fila. Uma entrega autenticada não deve poder selecionar tenant arbitrário por campo livre. Mantenha o roteamento no servidor e valide o ID contra cadastro autorizado.
Migre carga com cautela
Ao dividir uma operação entre números, defina a regra de roteamento e como preservar continuidade de conversas. O usuário deve saber qual canal está recebendo sua mensagem. Evite alternar números silenciosamente a cada falha; isso pode fragmentar histórico e gerar respostas duplicadas. Uma migração deve informar equipes, atualizar referências e validar integrações antes de desativar a conexão antiga.
Se alterar o ambiente Cloud que hospeda uma instância, confirme se é necessário recadastrar URL, API Key, callback e webhooks. Não copie um ID de instância entre ambientes presumindo que ele exista no destino. Trate cada ambiente como escopo próprio.
Aplique permissões por função
Atendimento pode precisar consultar estado e responder, enquanto apenas administradores autorizados criam ou removem instâncias. Limite ações no backend e mantenha auditoria de alterações. Proteja endpoints que listam recursos para que não retornem números ou nomes a todos os usuários da aplicação. Ao exportar lista para diagnóstico, remova dados pessoais e IDs não necessários.
Revisão operacional periódica
Revise a lista de instâncias por responsável, finalidade, ambiente, estado e última atividade. Identifique conexões sem dono ou que não têm integração ativa. Antes de remover, consulte dependências, fila e histórico. Uma revisão trimestral ou associada a mudanças de equipe ajuda a reduzir credenciais abandonadas e chamadas roteadas ao número errado.
Exemplo de cadastro por ambiente
Uma estrutura interna pode guardar environment_key, instance_id, finalidade, equipe e status, enquanto URL e API Key ficam num cofre separado. A aplicação resolve o ambiente autorizado no servidor e busca os outros dados. Isso permite trocar uma credencial sem reescrever cadastro de clientes e reduz o risco de um operador copiar a URL errada.
Não coloque o segredo como coluna de texto acessível a relatórios nem exporte a tabela completa para uma planilha. Se a interface mostra uma instância, apresente nome, finalidade, status e últimos caracteres do ID quando útil. Para suporte, envie o ID completo somente por canal privado e quando necessário.
Faça uma simulação antes de adicionar números
Desenhe o fluxo com instância de teste: qual evento escolhe o número, como o usuário percebe a identidade do canal e como uma resposta volta ao time. Simule desconexão de uma instância enquanto outra está ativa. Confirme que a falha não pausa nem redireciona mensagens da conexão saudável. Esse ensaio encontra configuração global que deveria ser específica por instância.
Dimensione por uso, não só por número
Duas instâncias podem ter volumes muito diferentes. Meça mensagens, mídia, horários de pico, fila e quantidade de operadores para cada conexão. A separação lógica não garante isolamento de capacidade dentro do mesmo ambiente; consulte limites publicados e observe métricas reais. Planeje que uma automação com alta atividade não impeça o atendimento de outro número.
Defina alertas por conexão e um responsável de backup. Se um canal crítico cair, a equipe precisa saber qual instância está afetada e qual negócio depende dela. Use nomes lógicos nos painéis e IDs técnicos nos logs. Evite uma lista sem descrição que leve o operador a reconectar o número errado.
Crie um plano para transferência de canal
Quando mudar o número que atende uma finalidade, atualize links, mensagens informativas, integrações e documentação interna. Preserve a associação das conversas existentes conforme os recursos dos produtos e não suponha que o histórico será transferido junto com o pareamento. Faça um período de transição controlado e avise usuários sobre o canal correto.
Depois da troca, acompanhe por um período se mensagens continuam chegando ao canal antigo. Use métricas e IDs para identificar tráfego residual, sem manter dois workers ativos enviando em paralelo. Atualize links públicos, QR codes impressos e instruções de atendimento, além da configuração da API. Quando a conexão antiga não tiver mais dependências, desative-a pelo procedimento documentado e registre a conclusão.
Antes de criar uma instância, confirme a disponibilidade no plano e o responsável pelo canal. Instâncias sem propósito definido geram custo de suporte e aumentam a superfície de credenciais. Revise periodicamente a lista e arquive configurações antigas com retenção compatível com a necessidade de auditoria.
Inclua a finalidade de cada conexão no inventário e revise a lista quando uma equipe muda de responsabilidade. Isso evita que a API continue enviando por um número que já não representa o canal esperado.
Evite um roteador de instâncias implícito
A regra que escolhe o número deve ser explícita e verificável. Use finalidade, tenant ou equipe configurados no servidor; não escolha com base na posição de uma lista ou no último ID usado. Antes de enviar, registre a decisão de roteamento e confirme que o destino pertence ao ambiente autorizado. Em caso de ambiguidade, interrompa a operação e peça seleção humana em vez de enviar para um número arbitrário.
Ao criar um novo canal, revise se políticas de atendimento, horários, mensagens automáticas e responsáveis também precisam ser duplicados. A conexão de API é apenas uma parte do canal; sem essas regras, mensagens podem chegar a uma caixa sem equipe para responder.
Quando uma equipe precisa de ambientes para vários clientes, defina também quem pode administrar cada instância no portal e como a transferência de responsabilidade acontece. Não deixe o ID técnico circular em canais públicos nem associe a instância a um tenant usando somente o nome exibido.