> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conecte e gerencie Números

> Conecte uma conta do WhatsApp com o QuickLink, verifique o status dela e inicie, pare e configure 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:

```typescript theme={null}
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`:

```typescript theme={null}
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](/pt-br/integrations/quicklink).

## Liste seus Números

```typescript theme={null}
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

```typescript theme={null}
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](/pt-br/sdks/typescript/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](/pt-br/guides/numbers/new-chat-cap).

## 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](/pt-br/guides/numbers/number-capabilities).

O método está incluído na prerelease do SDK publicada depois desta mudança na
API.

## Inicie e pare um Número

```typescript theme={null}
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](/pt-br/sdks/typescript/errors#402-a-equipe-não-pode-pagar).

`platform.sessions.stopMany({ sessionIds })` para até 100 Números de uma vez.

## Reinicie ou desconecte um Número

```typescript theme={null}
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](/pt-br/sdks/typescript/events#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:

```typescript theme={null}
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](/pt-br/console/sessions#configuração).

## Defina o Safe Mode de um Número

```typescript theme={null}
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:

```typescript theme={null}
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](/pt-br/console/billing#change-a-number-tier).

## Exclua um Número de teste

```typescript theme={null}
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](/pt-br/guides/numbers/number-capabilities) para os três
controles de grupo e as regras de substituição de conta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.