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

# Números de WhatsApp e Arquitetura Multi-Tenant no Pilot Status

> Gerencie múltiplos números de WhatsApp e construa um SaaS multi-tenant com o Pilot Status. Cada número é isolado, com sua própria API, webhooks e histórico de mensagens.

No Pilot Status, cada número de telefone conectado ao WhatsApp é representado como um **número** — a unidade central em torno da qual todo o seu projeto é organizado. Seja para conectar uma única linha comercial ou gerenciar centenas de contas de clientes, os números são como você identifica, configura e endereça as conexões de WhatsApp nas suas chamadas de API, webhooks e no painel.

<Frame caption="O seletor de número ativo no cabeçalho — toda página por número (Chat, Templates, Logs, API Keys…) segue o número selecionado aqui.">
  <img src="https://mintcdn.com/iaxp/9B6Q9GKDGLZJcBEh/images/dashboard/number-selector.png?fit=max&auto=format&n=9B6Q9GKDGLZJcBEh&q=85&s=ad8d1fe91fa555449c16a610f4161274" alt="Seletor de número ativo no cabeçalho do painel" width="716" height="317" data-path="images/dashboard/number-selector.png" />
</Frame>

## O que é um Número?

Um número representa um número de telefone conectado ao WhatsApp dentro do seu projeto Pilot Status. Quando você conecta um número de telefone — seja escaneando um QR code (API Não Oficial) ou vinculando suas credenciais WABA (API Oficial) — o Pilot Status cria um objeto de número e atribui a ele um identificador único.

Cada número é totalmente isolado de todos os outros números do seu projeto:

* **Histórico de mensagens separado** — Conversas e logs de um número nunca são misturados com os de outro.
* **Webhooks independentes** — Você configura URLs de webhook por número, para que cada linha possa rotear eventos para um endpoint diferente.
* **Logs dedicados** — Status de conexão, erros e atividade são rastreados individualmente.
* **Sua própria chave de API** — Cada número tem uma chave `ps_` com escopo de número; requisições feitas com essa chave atuam sobre esse número.

## Projetos Multi-Número

Seu plano Pilot Status define o número máximo de números de WhatsApp que você pode conectar simultaneamente. Dentro desse limite, você pode conectar quantos números precisar e gerenciar todos eles a partir de um único painel e API.

Executar múltiplos números em um único projeto é útil para diversos cenários:

<CardGroup cols={3}>
  <Card title="Distribuição de Carga" icon="arrow-right-arrow-left">
    Distribua altos volumes de mensagens entre vários números para se manter dentro dos limites de taxa do WhatsApp e manter uma alta vazão.
  </Card>

  <Card title="Linhas de Marca Separadas" icon="tag">
    Mantenha marcas ou linhas de produto distintas em seus próprios números, cada um com seu próprio histórico de mensagens e identidade.
  </Card>

  <Card title="Roteamento por Departamento" icon="sitemap">
    Dê às suas equipes de vendas, suporte e operações números individuais para que as conversas permaneçam organizadas e rastreáveis.
  </Card>
</CardGroup>

## SaaS Multi-Tenant

Se você está construindo um produto SaaS sobre o Pilot Status, o modelo multi-tenant permite que cada um dos seus clientes conecte seu próprio número de WhatsApp sob o seu único projeto Pilot Status. Você não precisa criar uma conta Pilot Status separada para cada cliente — você gerencia toda a frota a partir de um só lugar.

No seu painel e API, você vê todos os números conectados de todos os seus clientes. Você pode inspecionar o histórico de mensagens, configurar webhooks e disparar envios para qualquer número de cliente. Os dados de cada cliente permanecem isolados dos dados de todos os outros clientes.

Para enviar uma mensagem em nome de um cliente específico, use a **chave de API com escopo de número** desse número no cabeçalho `x-api-key` — a própria chave seleciona qual conexão de WhatsApp faz o envio:

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_customer_number_key" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello from your app!", "destinationNumber": "+5511999999999" }'
```

O Pilot Status roteia a mensagem automaticamente através da conexão de WhatsApp correta. Seus clientes nunca interagem diretamente com o Pilot Status — eles veem apenas o seu produto.

## Identificadores de Número

Cada número tem um ID único (ex.: `cmm0abc123`) que aparece nos payloads de webhook (`numberId`) e nos endpoints de gerenciamento. Há duas formas de encontrar o ID de um número:

<Tabs>
  <Tab title="Painel">
    Navegue até **Painel → Números**. O ID de cada número conectado é exibido no painel de detalhes do número. Você pode copiá-lo diretamente da interface.
  </Tab>

  <Tab title="API">
    Envie uma requisição `GET` para o endpoint de números com sua chave de **escopo de tenant** para recuperar todos os números conectados no seu projeto, incluindo seus IDs, status e tipo de conexão.

    ```bash theme={null}
    curl "https://pilotstatus.com.br/v1/numbers" \
      -H "x-api-key: ps_your_tenant_key"
    ```

    A resposta retorna um array de objetos de número, cada um contendo o campo `id` que você usa nas chamadas de gerenciamento e na correlação de webhooks.
  </Tab>
</Tabs>

<Info>
  Cada plano inclui um número fixo de números conectados, e você pode comprar números extras como um adicional recorrente. Se o seu projeto exigir um limite maior, entre em contato com o Pilot Status para discutir um plano personalizado.
</Info>