# What the number does at Meta

Fonte: https://lunahia.com.br/en/docs/number-on-meta

Each connected number has, at Meta, a profile the contact sees, a list of who was blocked and codes that open a conversation. Luna lets you handle the three through the API, with your customer’s own token, without them having to open Meta’s dashboard.

The [API reference](https://lunahia.com.br/en/docs/reference) carries every route and field. This guide explains what the reference cannot fit in a few lines: what Meta refuses, what does not work in coexistence and what is still to be confirmed.

## What holds for every route

- The `id` in the URL is the number’s: Luna’s UUID (the `id` from `GET /v1/numbers`) or Meta’s id (`metaPhoneNumberId`). Another customer’s number, or one that does not exist, answers the same `404`.
- Each call spends **one** unit of Meta’s management limit for the number’s business account: 200 per hour, the same bucket as connecting and templates. When it runs out, the answer is `429` with `Retry-After`. It is a technical Meta limit, the same for everyone.
- A number disconnected from Luna answers `409` (`number_disconnected`). A suspended account refuses what creates or changes; deleting, unblocking and reading stay open.
- When Meta refuses the request (field too long, outside the 24-hour window, expired authorization), the answer is `422` with `error: "meta_rejected"`. The `meta` field carries what happened, what to do and its original error. A Meta failure (server or network error) does not become `422`.
- None of these routes accepts an end customer’s key: use your account key.

## Business profile

`GET /v1/numbers/{id}/profile` reads, and `PATCH` changes, what the contact sees on WhatsApp: `about` (the short text), `address`, `description`, `email`, `websites`, `vertical` (the line of business, in Meta’s vocabulary, with no closed list here) and the picture. The read also returns `profilePictureUrl`, which is Meta’s and can expire: download the file if you need to keep it.

```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())
```

The `PATCH` changes only the fields you send. `websites` takes up to two and the whole list replaces the one that exists. To change the picture, send `profilePictureHandle`, the handle of a file uploaded through Meta’s resumable upload: the same handle `POST /v1/template-assets` returns works, **which is still to be confirmed in Meta’s documentation**. The field size limits (139 characters on the about text, 256 on the address, 512 on the description, 128 on the email) are also still to be confirmed: Luna only saves the call Meta would refuse, and Meta is the judge.

## Display name

The display name is the name the contact sees at the top of the conversation, and Meta reviews it. It is not in `profile`: it is in `GET /v1/numbers/{id}` and in every item of `GET /v1/numbers`. `displayName` is the name in use. `displayNameStatus` is the state of the review, in lowercase: `approved`, `pending_review`, `declined`, `expired` or `none`; new values can appear, so do not treat the list as closed. `pendingDisplayName` is the requested name that is not yet the name in use (under review, declined, or approved and waiting for the new registration). All three are null until Luna reads the number for the first time, which happens within about an hour. **Meta does not report the reason for a refusal in that query**, and Luna does not return one: the business sees the reason in the WhatsApp Manager, in Meta’s manager.

To request the change, send `displayName` in `PATCH /v1/numbers/{id}/profile`, alone or together with other profile fields. The answer is `202`: Meta accepted the request and it is under review, with `displayNameStatus: "pending_review"` and `pendingDisplayName` carrying the requested name. Meta accepts up to 10 name changes every 30 days and refuses a request outside its rules, which comes back as `422` with the original error. When the review ends, the `number.display_name_reviewed` event announces it. **An approved name only takes effect after the number is registered again** (`POST /{PHONE_NUMBER_ID}/register` at Meta), within 14 days of the approval; after that, you must ask again. Luna does not yet offer this new registration through a route: if the approved name does not show up in `displayName`, contact support.

> **A number in coexistence has no profile through the API.** Meta lists the business profile among what stops working when the number stays in the phone app. Luna refuses first, with `409` and `error: "not_available_in_coexistence"`, without spending the management call. Whoever needs to change the profile does it in the business’s WhatsApp Business app on the phone.

## Block users

`POST /v1/numbers/{id}/blocked-users` blocks, `GET` lists and `DELETE /v1/numbers/{id}/blocked-users/{user}` unblocks. Each user is a **phone number** (digits only, as in `to`) or a **BSUID** (as the `message.received` event carries it in `user_id`). Up to 50 per call. The **parent BSUID** (`XX.ENT.…`) does not block: Luna refuses with `400` and says the position, without repeating the value. That rule comes from the product plan and is still to be confirmed in Meta’s documentation.

```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())
```

`200` response

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

The response separates what Meta accepted (`done`) from what it refused (`failed`, with `reasons`, its text). **Meta only lets you block people who wrote to the number in the last 24 hours**, and Luna does not check that beforehand: Meta is the one that knows the window, and the reason comes back per user. The list (`GET`) uses `limit` and `cursor`, and `nextCursor` is Meta’s.

## QR code and short link

`POST /v1/numbers/{id}/qr-codes` creates a code that opens a conversation with the number, with `prefilledMessage` (up to 140 characters, to be confirmed in Meta’s documentation) already written. It returns the `code`, the short `link` (wa.me) and, if you sent `imageFormat` (`PNG` or `SVG`), the `imageUrl`. `GET` lists the ones that exist and `DELETE /v1/numbers/{id}/qr-codes/{code}` deletes: whoever still has the QR printed stops opening the conversation.

```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())
```

`201` response

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

Luna keeps nothing: the code, the link and the image live at Meta. The `imageUrl` is Meta’s and can expire, so download the file right away if you are going to print it. No route returns how many times the code was read.

## When the contact asks to stop receiving marketing

Meta tells you through the `user_preferences` field that the user changed a preference, today the one about marketing messages. Luna delivers the notice as the `contact.preferences_changed` event, with the contact (`wa_id`, `user_id`, `username`, `profile_name`) and `preference` (`category`, `value`, `detail`, as Meta sent them). **Luna does not block any send because of it**: your system keeps the request and stops sending marketing to whoever asked. See the event in [Receive events](https://lunahia.com.br/en/docs/receive-events).

The event

```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"
  }
}
```

> **The notice only exists if the `user_preferences` field is subscribed on the Meta app.** That subscription is made in Meta’s dashboard, not through this API. The exact shape of the body Meta sends on the field is still to be confirmed in its documentation, and Luna reads it tolerantly.
