Conecte e gerencie Números

Um Número é uma conta do WhatsApp conectada. Os métodos de mensagens recebem o ID dele como primeiro argumento.

Tarefa	Permissão
Criar e acompanhar QuickLinks	`quicklink:manage`
Listar e ler Números	`sessions:read`
Iniciar, parar, reiniciar, configurar e mudar de plano	`sessions:manage`

Conecte um Número com o QuickLink

Um QuickLink é uma página hospedada em que o dono da conta vincula o WhatsApp dele. Crie um e envie a URL para a pessoa que está com o celular:

const created = await messaging.quickLinks.create(
  {
    projectId: "<project-id>",
    externalId: "crm-account-42",
    configuration: { methods: ["qr", "pairing"] },
  },
  { idempotencyKey: "connect-crm-account-42" },
);

console.log(created.data.data.url, created.data.data.session);

externalId é a sua própria referência. Ela aparece no novo Número e nos eventos de webhook dele. Com uma credencial de projeto, omita projectId. Acompanhe o progresso até o status ser connected:

const link = await messaging.quickLinks.retrieve("<quicklink-id>");
console.log(link.data.data.status, link.data.data.phone);

O status passa por pending, opened, linked e connected, ou termina como failed ou cancelled. Chame quickLinks.cancel(id) para retirar um link que ainda não conectou. O texto da página, a identidade visual e as URLs de callback são configurações salvas. Leia e altere essas configurações com platform.quickLinkSettings. Veja QuickLink.

Liste seus Números

const numbers = await platform.sessions.list({ projectId: "<project-id>" });

for (const number of numbers.data.data) {
  console.log(number.sessionId, number.phone, number.status, number.testMode);
}

Omita projectId para listar todos os Números da equipe. Mantenha os IDs de Número como strings. Use testMode para diferenciar Números de teste dos reais.

Verifique o status de um Número

const number = await messaging.sessions.retrieve("<number-id>");
console.log(number.data.data.status, number.data.data.statusReason);

O webhook session.status informa as mudanças de status assim que acontecem. Veja Webhooks. Leia a conta do WhatsApp vinculada com messaging.sessions.account("<number-id>"). A leitura da sessão retorna newChatCapping para um número com dispositivo vinculado, com o limite, o uso e o horário de reinício informados pelo WhatsApp. O valor é null até a Polymorfa observar o número. O tipo NewChatCapping do SDK está disponível na versão publicada depois desta mudança na API. Veja Limite de novas conversas do WhatsApp.

Leia os recursos do WhatsApp

platform.sessions.getCapabilities("<number-id>") lê os recursos de configuração e os limites da última sincronização do Número com o WhatsApp. O método exige sessions:read e acesso ao beta de recursos por número. Antes da primeira sincronização, os valores são desconhecidos. Controles de configuração ativados não garantem suporte no cliente nem aceitação pelo servidor. Veja Recursos por número. O método está incluído na prerelease do SDK publicada depois desta mudança na API.

Inicie e pare um Número

await platform.sessions.start(
  "<number-id>",
  { projectId: "<project-id>" },
  { idempotencyKey: "start-support-2026-10-02" },
);

await platform.sessions.stop("<number-id>", { projectId: "<project-id>" });

start confirma que o início foi aceito, não que o Número conectou. Acompanhe o status para ver a conexão. Iniciar um Número pago reserva crédito primeiro. Se a equipe não puder pagar, start lança PolymorfaPaymentRequiredError. Veja Erros. platform.sessions.stopMany({ sessionIds }) para até 100 Números de uma vez.

Reinicie ou desconecte um Número

const restart = await messaging.sessions.restart("<number-id>");
const settled = await platform.operations.wait(restart.data.operationId);
console.log(settled.data.status);

logout desvincula a conta do WhatsApp e retorna uma operação da mesma forma. Veja Aguarde uma operação.

Altere a configuração de um Número

A configuração abrange a sincronização do histórico, o armazenamento hospedado de mensagens e a observação de presença, digitação, etiquetas e respostas rápidas. Leia a revisão atual e envie sua alteração com ela:

const current = await messaging.sessions.retrieve("<number-id>");
const revision = current.data.data.configuration?.revisions.session ?? 0;

await messaging.sessions.update("<number-id>", {
  revision,
  configuration: {
    set: { observation: { presenceMode: "events" } },
    reset: ["historySync"],
  },
});

set substitui um valor para este Número. reset remove a substituição, e o Número volta a seguir os padrões do projeto e da equipe. Uma revisão desatualizada falha com 409 state_conflict. Altere os padrões com platform.sessionConfiguration e project.sessionConfiguration. Veja Configuração da sessão.

Defina o Safe Mode de um Número

const safeMode = await platform.sessions.getSafeMode("<number-id>");
console.log(safeMode.data.data.effective);

await platform.sessions.updateSafeMode("<number-id>", {
  typing: "before_text",
  pacing: "inherit",
});

inherit remove a substituição do Número e usa a configuração do projeto.

Altere o plano de um Número

Uma mudança de plano é uma cotação seguida de uma confirmação:

const quoted = await platform.sessions.quoteTierChange("<number-id>", {
  tierOverride: "pro",
});
const quote = quoted.data.data;
console.log(quote.quote.amountCents, quote.quote.effectiveAtMs);

// After the customer accepts this exact quote:
await platform.sessions.setTierOverride("<number-id>", { quoteId: quote.id });

const result = await platform.sessions.retrieveTierChange("<number-id>", quote.id);
console.log(result.data.data.status);

Mostre a cobrança cotada antes de confirmá-la. amountCents está em créditos e pode ter até seis casas decimais. Uma cotação expira depois de dez minutos. Uma mudança queued ainda não foi aplicada; leia de novo até ela ficar applied ou rejected. Peça uma cotação com tierOverride: null para devolver o Número ao plano do projeto. Veja Cobrança.

Exclua um Número de teste

await platform.sessions.delete("<number-id>");

delete e deleteMany removem apenas Números de teste. Um Número real retorna 409.

Recursos de grupos

As versões do SDK que contêm messaging.groups.getCapabilities(session, groupId) retornam GroupCapabilities pelo envelope de sucesso do cliente Messaging. O método exige groups:read, uma credencial de servidor, participação atual no grupo e o beta de recursos por número. Valores desconhecidos continuam null. A leitura não abre a conversa do grupo. Veja Recursos por número para os três controles de grupo e as regras de substituição de conta.

Comece aqui

Ferramentas e clientes

SDK TypeScript

Conectar números

WhatsApp

Campanhas

Sua equipe

Testes

Ajuda e novidades

Conecte e gerencie Números

Conecte um Número com o QuickLink

Liste seus Números

Verifique o status de um Número

Leia os recursos do WhatsApp

Inicie e pare um Número

Reinicie ou desconecte um Número

Altere a configuração de um Número

Defina o Safe Mode de um Número

Altere o plano de um Número

Exclua um Número de teste

Recursos de grupos

​Conecte um Número com o QuickLink

​Liste seus Números

​Verifique o status de um Número

​Leia os recursos do WhatsApp

​Inicie e pare um Número

​Reinicie ou desconecte um Número

​Altere a configuração de um Número

​Defina o Safe Mode de um Número

​Altere o plano de um Número

​Exclua um Número de teste

​Recursos de grupos

Conecte um Número com o QuickLink

Liste seus Números

Verifique o status de um Número

Leia os recursos do WhatsApp

Inicie e pare um Número

Reinicie ou desconecte um Número

Altere a configuração de um Número

Defina o Safe Mode de um Número

Altere o plano de um Número

Exclua um Número de teste

Recursos de grupos