LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

What the number does at Meta

Use with AI

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 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.

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"
  ]
}'
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());
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.

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.

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"
  ]
}'
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());
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 responseJSON
{
  "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.

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"
}'
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());
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 responseJSON
{
  "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.

The eventJSON
{
  "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"
  }
}