LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

O que o número faz na Meta

Usar com IA

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

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())
Resposta 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())
Resposta 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.

O eventoJSON
{
  "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"
  }
}