O que o número faz 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 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
idna URL é o do número: o UUID da Luna (oiddeGET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Número de outro cliente, ou que não existe, responde o mesmo404. - 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 é
429comRetry-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 é
422comerror: "meta_rejected". O campometatraz o que aconteceu, o que fazer e o erro original dela. Falha da Meta (erro de servidor ou de rede) não vira422. - 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.
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())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.
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.
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())200JSON{
"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.
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())201JSON{
"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.
{
"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"
}
}