Sessões
Crie, pareie, inspecione, inicie, pare e reinicie sessões e gerencie a exclusão de números.
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.
Hybrid Link e as opções de conexão da Meta Cloud API aparecem, cada uma, somente quando a equipe pode usá-las. Caso contrário, o Console mostra o motivo: Sem configuração para esta equipe, Não disponível para esta equipe ou A Polymorfa desativou esta opção. Quando a Meta Cloud API não está disponível, um QuickLink compartilhado oferece somente Dispositivos vinculados. Se o Console não conseguir verificar a disponibilidade, as duas opções ficam indisponíveis até você abrir a janela novamente.
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:
| Rótulo | Tipo de conta |
|---|---|
| Normal | App WhatsApp, vinculado como dispositivo |
| WABA | App WhatsApp Business, vinculado como dispositivo |
| Cloud | Meta Cloud API |
| Coex | Meta Cloud API, com o app WhatsApp Business ainda ativo no celular |
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 e Configurações. As abas disponíveis dependem dos recursos do número. Configurações lista as seções Geral, Chamadas, Armazenamento de mensagens, Catálogos, Cliente e a ação de excluir ou remover. Cada aba e seção tem uma URL compartilhável. Conexões e Financiamento estão disponíveis 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:
- Interrompa as gravações no estado de autenticação do Baileys.
- Reserve o destino pelo QuickLink e depois solicite a chave de transferência com API Get handoff keys.
- Sele o
SignalStoreSnapshotcom a chave retornada e calcule o hash SHA-256 do snapshot. - Envie o envelope selado e o hash para API Import handoff state.
- 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.
Métodos de conexão#
| Ação | Método e caminho |
|---|---|
| Listar sessões | API List sessions |
| Criar um link de onboarding | API Create quick link |
| Ler ou atualizar uma sessão | GET ou API Update session |
| Iniciar | API Start session |
| Parar | API Stop session |
| Reiniciar | API Restart session |
| Desvincular (logout) | API Logout session |
| Remover | API Delete session |
| Ler a conta conectada | API Get session account |
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.
API Get session account, API Get profile e o webhook session.connected descrevem a conta conectada com dois campos:
phonePlatform | Significado |
|---|---|
android | O WhatsApp ou o WhatsApp Business roda em um celular Android. |
ios | O WhatsApp ou o WhatsApp Business roda em um iPhone. |
meta_cloud | A Meta hospeda o número pela Cloud API. |
unknown | O celular não informou uma plataforma reconhecida. |
accountType | Rótulo no Console | Significado |
|---|---|---|
whatsapp_app | Normal | App WhatsApp, conectado como dispositivo vinculado. |
business_app | WABA | App WhatsApp Business, conectado como dispositivo vinculado. |
meta_cloud | Cloud | Meta Cloud API. |
meta_coexistence | Coex | Meta Cloud API, com o app WhatsApp Business ainda ativo no celular. |
Conecte um número real com API Create quick link 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 API Stop sessions ou API Delete sessions 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 API Quote session tier change, revise a cobrança e o momento em que ela passa a valer e depois confirme o quoteId retornado com API Set session tier override. 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 API Get ban safe health. 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#
Veja os métodos de pareamento e de ciclo de vida.
SandboxTroque mensagens entre números de teste.
WebhooksAssine os eventos de sessão.
Equipes e contasConsulte 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:
{
"revision": 2,
"configuration": {
"set": { "historySync": { "mode": "deliver" } },
"reset": ["historySync.requestFull"]
}
}Envie as atualizações para API Update session. 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 API Update session configuration defaults. 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.