Pular para o conteúdo principal
Uma sessão representa um número conectado ou de teste. As operações da Messaging API endereçam uma sessão pelo seu identificador estável session. Os valores tipados de status público são CONNECTING, CONNECTED e DISCONNECTED. Equipes ativas podem conectar pelo Console ou criar um QuickLink compartilhável. O financiamento do número é verificado quando o pareamento começa. Criar um link não reserva serviço pago nem dispensa os requisitos de acesso da Meta Cloud API e dos números de teste.

​
Adicionar um número no Console

Abra um projeto, vá em Números e selecione Novo número. O fluxo de configuração, que pode ser fechado, oferece quatro caminhos:
  • Criar um número de teste grátis leva cerca de 10 segundos e adiciona um número simulado para desenvolvimento e testes automatizados. Ele não se conecta ao WhatsApp.
  • Vincular um número real agora leva cerca de 2 minutos. O Console cria um QuickLink e abre o fluxo de pareamento hospedado. Escaneie o código QR ou digite um código de pareamento no celular, confirme a conexão e o número aparece na lista.
  • Enviar um QuickLink leva cerca de 2 minutos e abre uma revisão das configurações daquele link: tipo de conexão, métodos de pareamento, tratamento do telefone e sincronização do histórico. Gere o link hospedado e depois copie, compartilhe ou mostre o link como código QR. O link continua ativo até ser usado ou cancelado, conecta um número ao projeto selecionado, e o Console mostra quando ele é aberto, vinculado e conectado. Consulte QuickLink.
  • Importar sessões existentes leva cerca de 10 minutos e mostra orientações específicas para o estado de autenticação do Baileys e do whatsmeow.
Em uma equipe Free, os caminhos de número real mostram Requer Pay-As-You-Go quando a equipe já usou a sua cota de números reais. Enviar um QuickLink para um número real sempre mostra esse aviso. Um convite para mudar de plano abaixo das opções abre a Cobrança. Vincular um número real agora e os números de teste continuam disponíveis dentro da cota. Fechar a janela durante o pareamento dentro do Console cancela essa conexão pendente. Fechar a janela depois de enviar um QuickLink não invalida o link; ele continua utilizável até conectar um número ou até você cancelá-lo. Gerar um novo link cria um convite separado. A coluna Conexão mostra um ícone ao lado de Conectado, Conectando, Parado ou Erro, com um motivo quando é preciso agir. Números conectados e em conexão oferecem Parar conexão. Um número parado pelo Console oferece Iniciar conexão. Um runtime com falha oferece Reiniciar conexão, e um número real desvinculado orienta você a vinculá-lo de novo. A propriedade no Inspector fica na coluna separada Responsável e não altera a saúde da conexão. A coluna Saúde fica ao lado de Conexão e mostra como o número está enviando: a sua faixa, a sua pontuação, de um máximo de 100, e quantas ocorrências de segurança estão abertas. As duas colunas significam coisas diferentes. Conexão indica se o número está online; Saúde indica se ele está enviando como uma pessoa envia. Um número que ainda não enviou o suficiente não mostra pontuação, e um número sem medição do BanSafe, como um número de teste, mostra Indisponível. A coluna abrange todos os números medidos do projeto, não só a primeira página da tabela. Selecione um número para ver as ocorrências dele ou abra Proteção para ver o projeto inteiro. Consulte Proteção. A coluna Dispositivo mostra como cada número chega ao WhatsApp. Um ícone mostra o sistema operacional do celular: Android, iOS ou Meta para números hospedados pela Meta. O rótulo ao lado mostra o tipo de conta: Um número vinculado informa o sistema operacional quando se conecta. Até lá, a coluna mostra um ícone vazio. Filtre a coluna por tipo de conta. Os detalhes do número mostram as mesmas informações em Dispositivo. A tabela mantém o nome do número e o telefone ou o ID da sessão na primeira coluna, a mais larga. Abra o cabeçalho de qualquer coluna para ordenar ou filtrar por essa propriedade. Arraste a borda de um cabeçalho para redimensioná-lo; o Console lembra a largura naquele navegador. Filtros e Ordenar também ficam ao lado das ações da tabela. Adicione mais de uma regra; cada filtro e cada ordenação aparece como uma etiqueta editável na barra de ferramentas. As etiquetas de ordenação numeradas mostram qual propriedade é aplicada primeiro. Digite um filtro de texto e pressione Enter ou selecione Aplicar. A tabela e as colunas continuam visíveis quando nenhuma linha corresponde. Adicionado em usa o seletor de intervalo de datas, e Responsável permite escolher um membro da equipe ou Sem responsável. Por padrão, as colunas ocupam a largura disponível da página. Depois de redimensionar, selecione Ajustar colunas para restaurar esse layout. Responsável mostra o avatar e o nome do usuário; Cliente mostra um ícone de cliente e o nome. Tipo usa um ícone simples e um rótulo. As ações em Mais também ficam disponíveis quando você clica com o botão direito na linha. Use essas ações para gerenciar o número, abrir o uso, os logs da API ou o cliente dele, copiar o número de telefone ou o ID do número, ou controlar a conexão. Você pode remover um número de teste pelo Console. Para um número de produção, selecione Ajuda para exclusão e entre em contato com o suporte; o Console não remove o número. Ações que precisam de um número de telefone ou de um cliente aparecem apenas quando esses dados existem. Selecionar um número abre a página dele. Use Números / número selecionado no topo para buscar outro número ou voltar para Todos os números. O seletor mantém o número no projeto ao qual ele pertence. Os controles comuns do número usam abas horizontais: Visão geral, Conexões, Segurança, Financiamento, Chamadas e Configurações. As abas disponíveis dependem dos recursos do número. Cada aba tem uma URL compartilhável. Financiamento está disponível para números reais; os números de teste mantêm os controles de configuração e remoção que já tinham. Iniciar conexão, Parar conexão ou Reiniciar conexão aparece no cabeçalho da página do número, de acordo com o estado da conexão. A ação continua disponível enquanto você troca de aba. Conexões contém as conexões vinculadas e a saúde da conta, Segurança contém a saúde e as ocorrências, e Financiamento contém o plano, o limite e a prioridade. Abra Configurações para ajustar a configuração, transferir o número para outro cliente e obter ajuda para exclusão.

​
Uso do número

Escolha Ver uso no menu da linha de um número de produção para conferir as cobranças e o uso medido dele. A lista de toda a equipe abre o projeto ao qual o número pertence e mantém o número selecionado quando você abre o gráfico de um produto. O progresso mensal de chamadas efetuadas e do limite de crédito usa o mês UTC atual. Números de teste não têm essa ação. Consulte Uso e créditos.

​
Orçamentos de gastos do número

Proprietários e administradores de equipes Pay-As-You-Go abrem o menu da linha de um número real e selecionam Orçamento para abrir a aba Financiamento com o formulário de limite e prioridade em foco. A mesma ação funciona na lista de números de toda a equipe e abre o projeto do próprio número. Selecione Salvar alterações para salvar os dois valores. Proprietários e administradores também podem definir valores iniciais ao criar um número real. Números de teste não têm essa ação. Consulte orçamentos de gastos para ver os limites mensais, as reservas e o serviço já pago.

​
Importação de sessões

Para importar uma sessão do Baileys:
  1. Interrompa as gravações no estado de autenticação do Baileys.
  2. Reserve o destino pelo QuickLink e depois solicite a chave de transferência com POST /platform/sessions/{sessionId}/handoff-keys.
  3. Sele o SignalStoreSnapshot com a chave retornada e calcule o hash SHA-256 do snapshot.
  4. Envie o envelope selado e o hash para POST /platform/sessions/{sessionId}/handoff-import.
  5. Mantenha o Baileys offline até a Polymorfa informar que o número importado está conectado.
Para o whatsmeow, mantenha o armazenamento de dispositivos offline e tire um único snapshot consistente do banco de dados com o registro do dispositivo e as tabelas do Signal. Use o caminho de migração assistida para esse snapshot; o Console não aceita envio do banco de dados bruto. Mantenha o armazenamento original sem alterações até a Polymorfa confirmar que o número importado está conectado.
Não execute a cópia de origem e a cópia importada ao mesmo tempo. Dispositivos vinculados concorrentes podem invalidar a sessão.

​
Métodos de conexão

Uma resposta 202 ao logout aceita a solicitação; ela não confirma que a desvinculação terminou. Um evento de desconexão descreve o estado da conexão, não um logout concluído. GET /platform/sessions/{sessionId}/me, GET /messaging/{session}/profile e o webhook session.connected descrevem a conta conectada com dois campos: Conecte um número real com POST /messaging/quicklinks e depois abra ou compartilhe a URL retornada. As credenciais precisam de acesso de pareamento direto ao número para obter um código QR bruto ou um código de pareamento em /messaging/{session}/pair/*; solicitações sem esse acesso retornam 403. Consulte QuickLink para ver o fluxo completo.

​
Ações em lote e planos de número

Use POST /platform/sessions/stop ou POST /platform/sessions/delete para um lote de 1 a 100 IDs de sessão em sessionIds. Adicione projectId para limitar a solicitação de uma chave de equipe a um projeto. Tokens de projeto ficam limitados ao próprio projeto. Para mudar o plano de um número, solicite uma cotação com POST /platform/sessions/{sessionId}/tier-quotes, revise a cobrança e o momento em que ela passa a valer e depois confirme o quoteId retornado com PATCH /platform/sessions/{sessionId}. Consulte Cobrança. Crie números de teste pelo QuickLink com configuration.testing. Cada sessão listada inclui status e statusReason, que pode ser nulo. Use os dois campos ao apresentar a saúde da conexão; statusReason distingue parada manual, logout, restrição temporária, tempo esgotado e falha do runtime. Leia a Saúde atual de um número, a origem da estimativa e as ocorrências registradas com GET /platform/bansafe/health/{session}. Consulte BanSafe.

​
Números de teste

Criar um número de teste exige projectId. name é opcional. country aceita um dos 243 códigos de país ISO alfa-2 compatíveis com o WhatsApp e tem US como padrão. No seletor do Console, busque pelo nome do país, pelo nome curto ou pelo código de chamada. O ID do número gerado é uma string decimal opaca, no mesmo formato dos outros números. Use testMode, e não um prefixo do ID, para identificar um número de teste. Números de teste não iniciam uma conexão real com o WhatsApp. Consulte métodos da API de conexão para ver os esquemas estritos de solicitação e de resultado.

​
Próximos passos

Números

Veja os métodos de pareamento e de ciclo de vida.

Sandbox

Troque mensagens entre números de teste.

Webhooks

Assine os eventos de sessão.

Equipes e contas

Consulte as operações de conta e de projeto.

​
Configuração

O inspetor do número mostra a configuração efetiva, a origem de cada valor e se o runtime já aplicou a alteração mais recente. Os padrões da equipe e do projeto valem apenas para campos sem substituição na sessão. Leia a sessão e depois envie o configuration.revisions.session dela como revision:
Envie as atualizações para PUT /platform/sessions/{sessionId}. Uma redefinição remove a substituição explícita; ela não a troca pelo padrão de hoje. Revisões desatualizadas retornam um conflito, para que edições simultâneas não sobrescrevam umas às outras. Gerencie os padrões da equipe com GET ou PUT /platform/session-configuration. Inclua projectId para gerenciar os padrões do projeto. Use a revisão correspondente da equipe ou do projeto obtida na última leitura. Leituras de configuração rejeitam parâmetros de consulta desconhecidos com 400 em vez de ignorá-los. O histórico continua limitado pelo consentimento do destinatário. O HMS fica desativado a menos que seja autorizado separadamente; a configuração sozinha não pode ativar o armazenamento nem alterar uma região autorizada ou uma concessão de retenção. A aplicação no runtime é assíncrona: uma alteração salva pode ficar pending até o runtime conectado confirmar o recebimento. A criação direta foi descontinuada. Solicitações antigas de criação retornam 410 com resource_gone; use o QuickLink para novas reservas. Reconectar, atualizar, desconectar e excluir continuam funcionando em sessões existentes. As configurações de observação também ficam em configuration.observation: presenceMode, typingMode, quickReplyMode e labelMode. Os três primeiros aceitam off, events ou cache; o de etiquetas também aceita project. Elas valem para Dispositivos vinculados. A Meta Cloud API e os números de teste rejeitam configurações explícitas de observação que não conseguem aplicar. Alterações de observação exigem acesso de observação; alterações de etiquetas também exigem acesso de gerenciamento de etiquetas. Os endpoints antigos de escrita da política de observação retornam um erro de migração. Os endpoints de leitura continuam disponíveis. Uma substituição de sessão que excede o teto de observação do projeto retorna 400; reduza o modo solicitado ou atualize primeiro os padrões do projeto.

​
Tempo pago restante

A tabela de números e a página do número mostram o tempo restante na janela cobrada de 24 horas de cada número. A contagem regressiva continua enquanto o número está parado ou desconectado. Período pago encerrado significa que o tempo comprado terminou; Sem período pago significa que o número não tem janela cobrada. Números de teste não exibem contagem regressiva paga. Para as regras de financiamento e renovação, consulte Cobrança. A ação Orçamento de um número abre a aba Financiamento em /sessions/<numberId>?tab=funding, para que você volte direto a essa aba. Links existentes com number e panel=limits continuam funcionando. Links de números atribuídos a clientes abrem a mesma página do número. Os limites e a prioridade do projeto continuam em Uso → Controles de financiamento.