# O que o número faz na Meta

Fonte: https://lunahia.com.br/docs/numero-na-meta

Cada número conectado tem, na Meta, um perfil que o contato vê, uma lista de quem foi bloqueado e códigos que abrem uma conversa. A Luna deixa você mexer nos três pela API, com o mesmo token do seu cliente, sem que ele precise abrir o painel da Meta.

A [referência da API](https://lunahia.com.br/docs/referencia) traz cada rota e cada campo. Este guia explica o que a referência não cabe em poucas linhas: o que a Meta recusa, o que não vale em coexistência e o que ainda está a confirmar.

## O que vale para todas as rotas

- O `id` na URL é o do número: o UUID da Luna (o `id` de `GET /v1/numbers`) ou o id da Meta (`metaPhoneNumberId`). Número de outro cliente, ou que não existe, responde o mesmo `404`.
- Cada chamada gasta **uma** unidade do limite de gestão da Meta para a conta de negócio do número: 200 por hora, o mesmo balde da conexão e dos templates. Esgotado, a resposta é `429` com `Retry-After`. É um limite técnico da Meta, igual para todos.
- Número desconectado da Luna responde `409` (`number_disconnected`). Conta suspensa recusa o que cria ou muda; apagar, desbloquear e ler seguem abertos.
- Quando a Meta recusa o pedido (campo longo demais, fora da janela de 24 horas, autorização vencida), a resposta é `422` com `error: "meta_rejected"`. O campo `meta` traz o que aconteceu, o que fazer e o erro original dela. Falha da Meta (erro de servidor ou de rede) não vira `422`.
- Nenhuma destas rotas aceita a chave de um cliente final: use a chave da sua conta.

## Perfil do negócio

`GET /v1/numbers/{id}/profile` lê, e `PATCH` muda, o que o contato vê no WhatsApp: `about` (o recado curto), `address`, `description`, `email`, `websites`, `vertical` (o ramo, no vocabulário da Meta, sem lista fechada aqui) e a foto. A leitura devolve também `profilePictureUrl`, que é da Meta e pode expirar: baixe o arquivo se precisar guardá-lo.

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/profile" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "about": "Atendimento de segunda a sexta",
  "websites": [
    "https://example.com"
  ]
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/profile', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "about": "Atendimento de segunda a sexta",
    "websites": [
      "https://example.com"
    ]
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.patch(
    "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/profile",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "about": "Atendimento de segunda a sexta",
        "websites": [
            "https://example.com",
        ],
    },
    timeout=10,
)
print(res.status_code, res.json())
```

O `PATCH` troca só os campos que você mandar. `websites` aceita até dois e a lista inteira substitui a que existe. Para trocar a foto, mande `profilePictureHandle`, o handle de um arquivo subido pelo envio resumível da Meta: o mesmo handle que `POST /v1/template-assets` devolve serve, **o que está a confirmar na documentação da Meta**. Os limites de tamanho dos campos (139 caracteres no recado, 256 no endereço, 512 na descrição, 128 no e-mail) também estão a confirmar: a Luna só poupa a chamada que a Meta recusaria, e a Meta é a juíza.

## Nome de exibição

O nome de exibição é o nome que o contato vê no topo da conversa, e a Meta o revisa. Ele não está no `profile`: está em `GET /v1/numbers/{id}` e em cada item de `GET /v1/numbers`. `displayName` é o nome em uso. `displayNameStatus` é o estado da revisão, em minúsculas: `approved`, `pending_review`, `declined`, `expired` ou `none`; novos valores podem aparecer, então não trate a lista como fechada. `pendingDisplayName` é o nome pedido que ainda não é o nome em uso (em revisão, recusado, ou aprovado à espera do novo registro). Os três são nulos até a Luna ler o número pela primeira vez, o que acontece em até cerca de uma hora. **A Meta não informa o motivo de uma recusa nessa consulta**, e a Luna não devolve um: o negócio vê o motivo no WhatsApp Manager, no gerenciador da Meta.

Para pedir a mudança, mande `displayName` no `PATCH /v1/numbers/{id}/profile`, sozinho ou junto de outros campos do perfil. A resposta é `202`: o pedido foi aceito pela Meta e está em revisão, com `displayNameStatus: "pending_review"` e `pendingDisplayName` com o nome pedido. A Meta aceita até 10 mudanças de nome a cada 30 dias e recusa o pedido fora das regras dela, que volta como `422` com o erro original. Quando a revisão termina, o evento `number.display_name_reviewed` avisa. **Um nome aprovado só passa a valer depois que o número é registrado de novo** (`POST /{PHONE_NUMBER_ID}/register` na Meta), em até 14 dias da aprovação; passado o prazo, é preciso pedir de novo. A Luna ainda não oferece esse novo registro por rota: se o nome aprovado não aparecer em `displayName`, fale com o suporte.

> **Número em coexistência não tem perfil pela API.** A Meta lista o perfil comercial entre o que deixa de funcionar quando o número continua no aplicativo do celular. A Luna recusa antes, com `409` e `error: "not_available_in_coexistence"`, sem gastar a chamada de gestão. Quem precisa mudar o perfil faz isso no aplicativo WhatsApp Business do celular do negócio.

## Bloquear usuários

`POST /v1/numbers/{id}/blocked-users` bloqueia, `GET` lista e `DELETE /v1/numbers/{id}/blocked-users/{user}` desbloqueia. Cada usuário é um **telefone** (só dígitos, como em `to`) ou um **BSUID** (como o evento `message.received` o traz em `user_id`). Até 50 por chamada. O **BSUID pai** (`XX.ENT.…`) não bloqueia: a Luna recusa com `400` e diz a posição, sem repetir o valor. Essa regra vem do plano do produto e está a confirmar na documentação da Meta.

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/blocked-users" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "users": [
    "5511900000000"
  ]
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/blocked-users', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "users": [
      "5511900000000"
    ]
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/blocked-users",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "users": [
            "5511900000000",
        ],
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Resposta `200`

```json
{
  "done": [{ "input": "5511900000000", "waId": "5511900000000", "userId": null, "reasons": [] }],
  "failed": []
}
```

A resposta separa o que a Meta aceitou (`done`) do que ela recusou (`failed`, com `reasons`, o texto dela). **A Meta só deixa bloquear quem escreveu ao número nas últimas 24 horas**, e a Luna não confere isso antes: quem conhece a janela é a Meta, e o motivo volta por usuário. A lista (`GET`) usa `limit` e `cursor`, e o `nextCursor` é o da Meta.

## QR code e link curto

`POST /v1/numbers/{id}/qr-codes` cria um código que abre uma conversa com o número, com `prefilledMessage` (até 140 caracteres, a confirmar na documentação da Meta) já escrita. Devolve o `code`, o `link` curto (wa.me) e, se você mandou `imageFormat` (`PNG` ou `SVG`), o `imageUrl`. `GET` lista os que existem e `DELETE /v1/numbers/{id}/qr-codes/{code}` apaga: quem ainda tem o QR impresso deixa de abrir a conversa.

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/qr-codes" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefilledMessage": "Oi, quero um orçamento",
  "imageFormat": "PNG"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/qr-codes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "prefilledMessage": "Oi, quero um orçamento",
    "imageFormat": "PNG"
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/qr-codes",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "prefilledMessage": "Oi, quero um orçamento",
        "imageFormat": "PNG",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Resposta `201`

```json
{
  "code": "4O4YGZEG3RIVE1",
  "prefilledMessage": "Oi, quero um orçamento",
  "link": "https://wa.me/message/4O4YGZEG3RIVE1",
  "imageUrl": "https://example.com/qr.png"
}
```

A Luna não guarda nada: o código, o link e a imagem vivem na Meta. O `imageUrl` é da Meta e pode expirar, então baixe o arquivo na hora se for imprimir. Nenhuma rota devolve quantas vezes o código foi lido.

## Quando o contato pede para parar de receber marketing

A Meta avisa pelo campo `user_preferences` que o usuário mudou uma preferência, hoje a de mensagens de marketing. A Luna entrega o aviso como o evento `contact.preferences_changed`, com o contato (`wa_id`, `user_id`, `username`, `profile_name`) e `preference` (`category`, `value`, `detail`, como a Meta mandou). **A Luna não bloqueia nenhum envio por causa dele**: o seu sistema guarda o pedido e para de mandar marketing a quem pediu. Veja o evento em [Receber eventos](https://lunahia.com.br/docs/receber-eventos).

O evento

```json
{
  "version": "2026-11-10",
  "event_id": "4236ccfb21e7cec359d1e1b5b5f3f8e65cb3e8a8db0fc86e4d95da037796e97c",
  "event_type": "contact.preferences_changed",
  "occurred_at": "2026-11-04T16:45:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "contact": {
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "profile_name": "Maria Souza"
  },
  "preference": {
    "category": "marketing_messages",
    "value": "stop",
    "detail": "User requested to stop marketing messages"
  }
}
```

> **O aviso só existe se o campo `user_preferences` estiver assinado no app da Meta.** Essa assinatura é feita no painel da Meta, e não por esta API. A forma exata do corpo que a Meta manda no campo está a confirmar na documentação dela, e a Luna lê com tolerância.
