LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Messages

Use with AI

Send messages and read what came in and went out. Sending is asynchronous: the answer is 202 and delivery happens at the pace Meta allows.

List messages

GET/v1/messages

The record of what came in and what went out, newest first. Each message carries the number, the customer label, the conversation and, when it failed, the error summary. Filters: phoneNumberId, externalId, conversationId, waId, userId, wamid, direction, status, since and until. A parameter the route does not know answers 400. format=csv answers text/csv, with the same filters.

Authentication
API key
Required scope
messages:read

Query parameters

  • limitintegeroptional
    Quantas mensagens trazer. Padrão 50, máximo 100. Com format=csv o padrão e o máximo são 1000. Mais que 100 sem format=csv responde 400.minimum 1 · maximum 1000
  • formatstringoptional
    json (o padrão) ou csv. O csv vem em text/csv, uma linha por mensagem, com os mesmos filtros e a mesma ordem; a próxima página vem no cabeçalho X-Luna-Next-Cursor (ausente na última) e vai em cursor. Colunas: id, direction, wamid, type, bodyText, status, waId, userId, displayNumber, numberId, externalId, conversationId, errorCode, errorMessage, createdAt.Values: json csv
  • phoneNumberIdstringoptional
    O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • externalIdstringoptional
    O rótulo que você deu ao seu cliente (externalId): só as mensagens dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia.1 to 128 characters
  • conversationIdstring (uuid)optional
  • waIdstringoptional
    O telefone do interlocutor (waId), só com dígitos: só as mensagens da conversa dele. Igualdade exata, e o celular do Brasil vale com e sem o nono dígito; um waId sem conversa devolve lista vazia.1 to 64 characters
  • userIdstringoptional
    O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só as mensagens da conversa dele. Igualdade exata; um userId sem conversa devolve lista vazia.1 to 200 characters
  • directionstringoptional
    inbound: só o que chegou. outbound: só o que você enviou.Values: inbound outbound
  • statusstringoptional
    O status da mensagem, como a Meta o informa e como o campo status o devolve (por exemplo sent, delivered, read, failed). Igualdade exata, e um valor que nenhuma mensagem tem devolve lista vazia. Vale só para mensagem enviada, que é a que tem status.1 to 32 characters
  • sincestring (date-time) | string (date)optional
    Só as mensagens criadas neste instante ou depois (ISO 8601: 2026-11-03T00:00:00.000Z, 2026-11-03T00:00:00-03:00, ou a data 2026-11-03, que vale meia-noite UTC).
  • untilstring (date-time) | string (date)optional
    Só as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until).
  • wamidstringoptional
    O identificador da mensagem na Meta, o mesmo que os eventos de webhook trazem em wamid. Devolve só a mensagem com esse wamid, e a lista vem vazia quando ele não é seu ou não existe.1 to 512 characters
  • cursorstringoptional
    up to 256 characters

Responses

200Success.
  • dataarray<object>required
  • data[].idstring (uuid)required
  • data[].directionstringrequired
  • data[].wamidstring | nullrequired
  • data[].typestring | nullrequired
    O tipo da mensagem: text, image, template e os demais. Nulo só em mensagem enviada antes de a plataforma passar a gravar o tipo na saída.
  • data[].bodyTextstring | nullrequired
    O texto da mensagem. Em mensagem enviada, só vem preenchido quando ela é do tipo text: para os outros tipos o corpo não é reescrito como texto e o campo é nulo.
  • data[].contentobject | nullrequired
    O que a mensagem carrega além do texto, nos dois sentidos. Recebida: mídia com legenda, botão ou item clicado, localização, contatos, reação, citação, anúncio de origem e nome de perfil, com os nomes de campo da Meta, os mesmos do evento message.received. Enviada: o que você mandou, de volta: template (nome, idioma e valores das variáveis), sent_interactive (corpo, botões ou itens, endereço do botão de URL), media (legenda e nome do arquivo, sem o link), location, reaction, contacts e context. Nulo em mensagem de texto enviada (o texto está em bodyText), e em mensagem anterior à plataforma guardar o conteúdo.
  • data[].content.profile_namestring | nullrequired
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • data[].content.mediaobject | nullrequired
    O arquivo que o interlocutor mandou. O tipo (imagem, vídeo, áudio, documento, figurinha) está em type. Os bytes saem por GET /v1/messages/{id}/media, e o identificador e a URL da Meta não são entregues: você não tem o token que os abre.
  • data[].content.media.mime_typestring | nullrequired
    O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu.
  • data[].content.media.sha256string | nullrequired
    O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type.
  • data[].content.media.captionstring | nullrequired
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • data[].content.media.filenamestring | nullrequired
    O nome do arquivo. Só documento tem.
  • data[].content.media.voiceboolean | nullrequired
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • data[].content.media.animatedboolean | nullrequired
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • data[].content.interactiveobject | nullrequired
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • data[].content.interactive.typestring | nullrequired
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • data[].content.interactive.idstring | nullrequired
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • data[].content.interactive.titlestring | nullrequired
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • data[].content.interactive.descriptionstring | nullrequired
    A descrição do item da lista. Nula nos demais.
  • data[].content.interactive.namestring | nullrequired
    O nome do Flow. Só em nfm_reply.
  • data[].content.interactive.response_jsonstring | nullrequired
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • data[].content.buttonobject | nullrequired
    O clique num botão de resposta rápida de um template.
  • data[].content.button.payloadstring | nullrequired
    O payload que você definiu no botão de resposta rápida do template.
  • data[].content.button.textstring | nullrequired
    O texto do botão.
  • data[].content.locationobject | nullrequired
    A localização que o interlocutor compartilhou.
  • data[].content.location.latitudenumber | nullrequired
    A latitude, em graus decimais.
  • data[].content.location.longitudenumber | nullrequired
    A longitude, em graus decimais.
  • data[].content.location.namestring | nullrequired
    O nome do lugar, quando o interlocutor escolheu um.
  • data[].content.location.addressstring | nullrequired
    O endereço, quando há.
  • data[].content.location.urlstring | nullrequired
    O endereço web do lugar, quando há.
  • data[].content.contactsarray<object> | nullrequired
    Os cartões de contato que o interlocutor compartilhou.
  • data[].content.contacts[].nameobject | nullrequired
    O nome do contato, nos campos da Meta.
  • data[].content.contacts[].name.formatted_namestring | nullrequired
  • data[].content.contacts[].name.first_namestring | nullrequired
  • data[].content.contacts[].name.last_namestring | nullrequired
  • data[].content.contacts[].name.middle_namestring | nullrequired
  • data[].content.contacts[].name.prefixstring | nullrequired
  • data[].content.contacts[].name.suffixstring | nullrequired
  • data[].content.contacts[].phonesarray<object> | nullrequired
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • data[].content.contacts[].phones[].phonestring | nullrequired
  • data[].content.contacts[].phones[].wa_idstring | nullrequired
  • data[].content.contacts[].phones[].typestring | nullrequired
  • data[].content.contacts[].emailsarray<object> | nullrequired
    Os e-mails do contato.
  • data[].content.contacts[].emails[].emailstring | nullrequired
  • data[].content.contacts[].emails[].typestring | nullrequired
  • data[].content.contacts[].orgobject | nullrequired
    A organização do contato.
  • data[].content.contacts[].org.companystring | nullrequired
  • data[].content.contacts[].org.departmentstring | nullrequired
  • data[].content.contacts[].org.titlestring | nullrequired
  • data[].content.reactionobject | nullrequired
    A reação a uma mensagem, ou a retirada dela.
  • data[].content.reaction.wamidstring | nullrequired
    O wamid da mensagem que recebeu a reação.
  • data[].content.reaction.emojistring | nullrequired
    O emoji. Nulo quando o interlocutor retirou a reação.
  • data[].content.contextobject | nullrequired
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • data[].content.context.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor citou ao responder.
  • data[].content.context.fromstring | nullrequired
    Quem enviou a mensagem citada.
  • data[].content.context.forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada.
  • data[].content.context.frequently_forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • data[].content.referralobject | nullrequired
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • data[].content.referral.source_typestring | nullrequired
    A origem do clique, como ad ou post.
  • data[].content.referral.source_idstring | nullrequired
    O identificador do anúncio ou da publicação na Meta.
  • data[].content.referral.source_urlstring | nullrequired
    O endereço do anúncio ou da publicação.
  • data[].content.referral.headlinestring | nullrequired
    O título do anúncio.
  • data[].content.referral.bodystring | nullrequired
    O texto do anúncio.
  • data[].content.referral.media_typestring | nullrequired
    O tipo da mídia do anúncio, como image ou video.
  • data[].content.referral.ctwa_clidstring | nullrequired
    O identificador do clique, para atribuição de conversão.
  • data[].content.unsupportedobject | nullrequired
    Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso".
  • data[].content.unsupported.codeinteger | nullrequired
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • data[].content.unsupported.titlestring | nullrequired
    O título do erro, como a Meta o mandou.
  • data[].content.unsupported.detailsstring | nullrequired
    O detalhe do erro, como a Meta o mandou.
  • data[].content.editobject | nullrequired
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • data[].content.edit.wamidstring | nullrequired
    O wamid da mensagem que foi editada.
  • data[].content.edit.typestring | nullrequired
    O tipo do conteúdo novo, como text.
  • data[].content.edit.textstring | nullrequired
    O texto novo, quando o conteúdo novo é texto.
  • data[].content.revokeobject | nullrequired
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • data[].content.revoke.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor apagou para todos.
  • data[].content.orderobject | nullrequired
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • data[].content.order.catalog_idstring | nullrequired
    O catálogo de onde veio o pedido.
  • data[].content.order.textstring | nullrequired
    O texto que o interlocutor escreveu junto com o pedido.
  • data[].content.order.itemsarray<object> | nullrequired
    Os itens do pedido.
  • data[].content.order.items[].product_retailer_idstring | nullrequired
    O identificador do produto no seu catálogo.
  • data[].content.order.items[].quantitystring | nullrequired
    A quantidade pedida, como a Meta mandou.
  • data[].content.order.items[].item_pricestring | nullrequired
    O preço unitário, como a Meta mandou.
  • data[].content.order.items[].currencystring | nullrequired
    A moeda do preço.
  • data[].content.templateobject | nullrequired
    O template que você enviou, com os valores que preencheram as variáveis.
  • data[].content.template.namestring | nullrequired
    O nome do template que você enviou.
  • data[].content.template.languagestring | nullrequired
    O idioma do template, no código da Meta (por exemplo pt_BR).
  • data[].content.template.variablesarray<object> | nullrequired
    Os valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.
  • data[].content.template.variables[].componentstringrequired
    Onde a variável entra: header, body ou button.
  • data[].content.template.variables[].namestring | nullrequired
    O nome da variável, quando o template usa variáveis nomeadas. Nulo nas posicionais, em que a ordem na lista é a posição.
  • data[].content.template.variables[].valuestringrequired
    O valor que você mandou. Parâmetro de imagem, vídeo ou documento não aparece: o link do arquivo não é devolvido.
  • data[].content.sent_interactiveobject | nullrequired
    A mensagem interativa que você enviou: o texto, os botões ou itens que o seu cliente viu, e o endereço do botão de URL.
  • data[].content.sent_interactive.typestring | nullrequired
    O tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.
  • data[].content.sent_interactive.headerstring | nullrequired
    O texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.
  • data[].content.sent_interactive.bodystring | nullrequired
    O texto do corpo.
  • data[].content.sent_interactive.footerstring | nullrequired
    O texto do rodapé.
  • data[].content.sent_interactive.buttonsarray<object> | nullrequired
    Os botões de resposta (id e título). Só em type button.
  • data[].content.sent_interactive.buttons[].idstring | nullrequired
  • data[].content.sent_interactive.buttons[].titlestring | nullrequired
  • data[].content.sent_interactive.itemsarray<object> | nullrequired
    Os itens da lista, de todas as seções (id, título e descrição). Só em type list.
  • data[].content.sent_interactive.items[].idstring | nullrequired
  • data[].content.sent_interactive.items[].titlestring | nullrequired
  • data[].content.sent_interactive.items[].descriptionstring | nullrequired
  • data[].content.sent_interactive.ctaobject | nullrequired
    O botão de chamada: o rótulo e, no cta_url, o endereço que ele abre. No flow, só o rótulo.
  • data[].content.sent_interactive.cta.textstring | nullrequired
  • data[].content.sent_interactive.cta.urlstring | nullrequired
  • data[].content.sent_interactive.catalog_idstring | nullrequired
    O catálogo de onde vêm os produtos. Só em type product e product_list.
  • data[].content.sent_interactive.productsarray<object> | nullrequired
    Os produtos enviados, com o título da seção a que pertencem (nulo no product, que não tem seção). Só em type product e product_list.
  • data[].content.sent_interactive.products[].sectionstring | nullrequired
  • data[].content.sent_interactive.products[].product_retailer_idstring | nullrequired
  • data[].callbackDatastring | nullrequired
    A etiqueta que você mandou em callbackData ao enviar a mensagem (de 1 a 512 caracteres), devolvida como veio. Nulo quando o envio não trouxe etiqueta e em mensagem recebida.
  • data[].statusstring | nullrequired
  • data[].pricingobject | nullrequired
    O custo que a Meta aplicou à mensagem enviada, com os nomes dela: type e category juntos. Nulo enquanto a Meta não o informou, e em mensagem recebida. Não é a fatura da Meta.
  • data[].pricing.billableboolean | nullrequired
    Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.
  • data[].pricing.pricing_modelstring | nullrequired
    O modelo de preço da Meta, como ela informou (hoje PMP ou CBP).
  • data[].pricing.typestring | nullrequired
    O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.
  • data[].pricing.categorystring | nullrequired
    A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.
  • data[].waIdstring | nullrequired
    O telefone do interlocutor (wa_id da Meta). Nulo quando a mensagem não tem conversa resolvida e quando o interlocutor escreveu só com BSUID, caso em que userId o identifica.
  • data[].userIdstring | nullrequired
    O BSUID do interlocutor, como a Meta o mandou. Nulo quando a Meta nunca o mandou para esta conversa.
  • data[].parentUserIdstring | nullrequired
    O BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais.
  • data[].usernamestring | nullrequired
    O nome de usuário do interlocutor, quando ele adotou um. Nulo no demais.
  • data[].displayNumberstring | nullrequired
  • data[].numberIdstring (uuid) | nullrequired
    O número da Luna por onde a mensagem passou, o mesmo id de GET /v1/numbers. Nulo quando a mensagem não tem número resolvido.
  • data[].externalIdstring | nullrequired
    O seu rótulo para o cliente dono do número (externalId do número). Nulo quando o número não tem rótulo.
  • data[].conversationIdstring (uuid) | nullrequired
    A conversa da mensagem, o mesmo id de GET /v1/conversations. Nulo quando não há conversa resolvida.
  • data[].errorSummaryobject | nullrequired
    Por que a mensagem falhou, quando falhou: o último erro, na mesma taxonomia de GET /v1/messages/{id}, sem o corpo original da Meta (ele continua só no detalhe, em erros). Nulo quando a mensagem não teve erro.
  • data[].errorSummary.codigonumber | nullrequired
    O código do erro da Meta, quando ela mandou um.
  • data[].errorSummary.mensagemstringrequired
    O que aconteceu, em português.
  • data[].errorSummary.acaoRecomendadastringrequired
    O que fazer a respeito, em português.
  • data[].createdAtstringrequired
  • nextCursorstring | nullrequired
    Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Send a text message

POST/v1/messages

Accepts the message, returns 202 with its identifier, and delivers it to Meta asynchronously. With a test key, the message does NOT go to Meta: Luna returns the 202 and delivers the simulated states sent, delivered and read to your webhook, with test: true. The optional Idempotency-Key header (1 to 255 visible characters, no space) makes repeating the request return the original message; empty or malformed answers 400.

Authentication
API key
Required scope
messages:write

Request body

application/json · required

The body is one of these shapes (pick one):

Shape 1: type = "text"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringoptional
    Sempre text. Pode ser omitido: um corpo sem type é interpretado como texto, para não quebrar quem integrou antes dos demais tipos existirem.default: "text"Values: text
  • textobjectrequired
  • text.bodystringrequired
    O texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API.1 to 4096 characters
  • text.preview_urlbooleanoptional
    Se a Meta deve buscar a primeira URL do texto para montar uma prévia. Desligado por padrão: ligado, ele dispara uma requisição de saída a partir de conteúdo que o negócio final escreveu, com latência e comportamento que não são da plataforma.
Shape 2: type = "image"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre image.Values: image
  • imageobjectrequired
  • image.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • image.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • image.captionstringoptional
    A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.up to 1024 characters
Shape 3: type = "video"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre video.Values: video
  • videoobjectrequired
  • video.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • video.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • video.captionstringoptional
    A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.up to 1024 characters
Shape 4: type = "audio"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre audio.Values: audio
  • audioobjectrequired
  • audio.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • audio.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • audio.voicebooleanoptional
    true para enviar como mensagem de voz (a bolinha de áudio do WhatsApp, com a forma de onda), e não como arquivo de áudio. A Meta exige um arquivo .ogg com codec OPUS, e a Luna não converte áudio: com link, um arquivo de outro tipo reconhecido (por exemplo .mp3) é recusado com 400. Com id, a Luna não vê o tipo do arquivo, e a conferência é da Meta.
Shape 5: type = "document"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre document.Values: document
  • documentobjectrequired
  • document.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • document.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • document.captionstringoptional
    A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.up to 1024 characters
  • document.filenamestringoptional
    O nome com que o arquivo aparece para quem recebe. Sem ele, quem recebe vê o nome que a Meta derivar da origem.1 to 240 characters
Shape 6: type = "sticker"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre sticker.Values: sticker
  • stickerobjectrequired
  • sticker.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • sticker.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
Shape 7: type = "location"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre location.Values: location
  • locationobjectrequired
  • location.latitudenumberrequired
    A latitude em graus decimais, entre -90 e 90.minimum -90 · maximum 90
  • location.longitudenumberrequired
    A longitude em graus decimais, entre -180 e 180.minimum -180 · maximum 180
  • location.namestringoptional
    O nome do lugar, exibido acima do endereço.up to 1000 characters
  • location.addressstringoptional
    O endereço do lugar, exibido abaixo do nome.up to 1000 characters
Shape 8: type = "contacts"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre contacts.Values: contacts
  • contactsarray<object>required
    Os cartões de contato a enviar. Ao menos um, no máximo vinte.1 to 20 items
  • contacts[].nameobjectrequired
  • contacts[].name.formatted_namestringrequired
    O nome como ele aparece no cartão.1 to 512 characters
  • contacts[].name.first_namestringoptional
    O primeiro nome.up to 256 characters
  • contacts[].name.last_namestringoptional
    O sobrenome.up to 256 characters
  • contacts[].name.middle_namestringoptional
    O nome do meio.up to 256 characters
  • contacts[].name.prefixstringoptional
    O prefixo, como Dr. ou Sra.up to 64 characters
  • contacts[].name.suffixstringoptional
    O sufixo, como Jr. ou Neto.up to 64 characters
  • contacts[].birthdaystringoptional
    A data de nascimento em AAAA-MM-DD./^\d{4}-\d{2}-\d{2}$/
  • contacts[].orgobjectoptional
    Os dados profissionais do contato.
  • contacts[].org.companystringoptional
    A empresa.up to 256 characters
  • contacts[].org.departmentstringoptional
    O departamento.up to 256 characters
  • contacts[].org.titlestringoptional
    O cargo.up to 256 characters
  • contacts[].phonesarray<object>optional
    Os telefones do contato.up to 20 items
  • contacts[].phones[].phonestringoptional
    O telefone, como ele deve aparecer.up to 64 characters
  • contacts[].phones[].typestringoptional
    O rótulo do telefone, como CELL ou WORK.up to 64 characters
  • contacts[].phones[].wa_idstringoptional
    O identificador do contato no WhatsApp, se conhecido.up to 64 characters
  • contacts[].emailsarray<object>optional
    Os e-mails do contato.up to 20 items
  • contacts[].emails[].emailstringoptional
    O endereço de e-mail.up to 320 characters
  • contacts[].emails[].typestringoptional
    O rótulo do e-mail, como HOME ou WORK.up to 64 characters
  • contacts[].addressesarray<object>optional
    Os endereços do contato.up to 20 items
  • contacts[].addresses[].streetstringoptional
    O logradouro e o número.up to 512 characters
  • contacts[].addresses[].citystringoptional
    A cidade.up to 256 characters
  • contacts[].addresses[].statestringoptional
    O estado.up to 256 characters
  • contacts[].addresses[].zipstringoptional
    O CEP.up to 64 characters
  • contacts[].addresses[].countrystringoptional
    O país.up to 256 characters
  • contacts[].addresses[].country_codestringoptional
    O código do país em duas letras.up to 8 characters
  • contacts[].addresses[].typestringoptional
    O rótulo do endereço, como HOME ou WORK.up to 64 characters
  • contacts[].urlsarray<object>optional
    As páginas do contato.up to 20 items
  • contacts[].urls[].urlstringoptional
    O endereço na web.up to 2048 characters
  • contacts[].urls[].typestringoptional
    O rótulo da URL, como HOME ou WORK.up to 64 characters
Shape 9: type = "reaction"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre reaction.Values: reaction
  • reactionobjectrequired
  • reaction.message_idstringrequired
    A mensagem que recebe a reação: o wamid que a Meta atribuiu ou o id da Luna (UUID), que a Luna troca pelo wamid. O content da mensagem enviada mostra o wamid.1 to 256 characters
  • reaction.emojistringrequired
    O emoji da reação. Mande vazio para remover uma reação que já tinha sido posta.up to 16 characters
Shape 10: type = "interactive"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre interactive.Values: interactive
  • interactiveobjectrequired
    A mensagem interativa: botões de resposta (button), lista de opções (list), botão com URL (cta_url), pedido de localização (location_request_message), pedido de endereço (address_message), carrossel de mídia (carousel), Flow (flow), um produto do catálogo (product) ou uma lista de produtos do catálogo (product_list).
  • interactive.typestringoptional
    Sempre button.Values: button
  • interactive.headerobjectoptional
    O cabeçalho, exibido acima do corpo.
  • interactive.header.typestringrequired
    O que o cabeçalho carrega.Values: text image video document
  • interactive.header.textstringoptional
    O texto do cabeçalho, quando type é text.up to 60 characters
  • interactive.header.imageobjectoptional
    A imagem do cabeçalho, quando type é image.
  • interactive.header.image.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • interactive.header.image.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • interactive.header.videoobjectoptional
    O vídeo do cabeçalho, quando type é video.
  • interactive.header.video.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • interactive.header.video.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • interactive.header.documentobjectoptional
    O documento do cabeçalho, quando type é document.
  • interactive.header.document.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • interactive.header.document.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • interactive.header.document.filenamestringoptional
    up to 240 characters
  • interactive.bodyobjectoptional
    O corpo da mensagem interativa.
  • interactive.body.textstringrequired
    O texto do corpo.1 to 1024 characters
  • interactive.footerobjectoptional
    O rodapé, exibido abaixo dos botões.
  • interactive.footer.textstringrequired
    O texto do rodapé.up to 60 characters
  • interactive.actionobjectoptional
  • interactive.action.buttonsarray<object>required
    Os botões de resposta. De um a três, o teto da Cloud API.1 to 3 items
  • interactive.action.buttons[].typestringrequired
    Sempre reply.Values: reply
  • interactive.action.buttons[].replyobjectrequired
  • interactive.action.buttons[].reply.idstringrequired
    O identificador que volta no webhook quando o botão é tocado.1 to 256 characters
  • interactive.action.buttons[].reply.titlestringrequired
    O rótulo do botão. Limite de 20 caracteres.1 to 20 characters
  • interactive.action.buttonstringrequired
    O rótulo do botão que abre a lista. Limite de 20 caracteres.1 to 20 characters
  • interactive.action.sectionsarray<object>required
    As seções da lista. De uma a dez, o teto da Cloud API.1 to 10 items
  • interactive.action.sections[].titlestringoptional
    O título da seção.up to 24 characters
  • interactive.action.sections[].rowsarray<object>required
    As linhas da seção. De uma a dez.1 to 10 items
  • interactive.action.sections[].rows[].idstringrequired
    O identificador que volta no webhook quando a linha é escolhida.1 to 200 characters
  • interactive.action.sections[].rows[].titlestringrequired
    O título da linha.1 to 24 characters
  • interactive.action.sections[].rows[].descriptionstringoptional
    A descrição da linha.up to 72 characters
  • interactive.action.namestringoptional
    Sempre cta_url.default: "cta_url"Values: cta_url
  • interactive.action.parametersobjectrequired
  • interactive.action.parameters.display_textstringrequired
    O rótulo do botão. Limite de 20 caracteres.1 to 20 characters
  • interactive.action.parameters.urlstring (uri)required
    O endereço que o botão abre.up to 2048 characters
  • interactive.action.parameters.countrystringoptional
    O país do endereço, em duas letras (ISO 3166). O padrão é BR./^[A-Za-z]{2}$/ · default: "BR"
  • interactive.action.parameters.valuesobjectoptional
    Os campos do endereço já preenchidos, com os nomes que a Meta define para o país.
  • interactive.action.parameters.saved_addressesarray<object>optional
    Endereços salvos que o usuário pode escolher, no máximo vinte.up to 20 items
  • interactive.action.parameters.saved_addresses[].idstringrequired
    O identificador do endereço salvo.1 to 128 characters
  • interactive.action.parameters.saved_addresses[].valueobjectrequired
    Os campos do endereço salvo.
  • interactive.action.parameters.validation_errorsobjectoptional
    Mensagens de erro por campo, para quando você devolve o formulário depois de uma validação.
  • interactive.action.cardsarray<object>required
    Os cartões, de dois a dez.2 to 10 items
  • interactive.action.cards[].card_indexintegerrequired
    A posição do cartão, de 0 a 9. Não repita.minimum 0 · maximum 9
  • interactive.action.cards[].typestringoptional
    Sempre cta_url.default: "cta_url"Values: cta_url
  • interactive.action.cards[].headerobjectrequired
    A mídia do cartão.
  • interactive.action.cards[].header.typestringrequired
    O que o cartão mostra.Values: image video
  • interactive.action.cards[].header.imageobjectoptional
    A imagem do cartão, quando type é image.
  • interactive.action.cards[].header.image.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • interactive.action.cards[].header.image.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • interactive.action.cards[].header.videoobjectoptional
    O vídeo do cartão, quando type é video.
  • interactive.action.cards[].header.video.idstringoptional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 to 128 characters
  • interactive.action.cards[].header.video.linkstring (uri)optional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.up to 2048 characters
  • interactive.action.cards[].bodyobjectoptional
    O texto do cartão.
  • interactive.action.cards[].body.textstringrequired
    O texto do cartão. Limite de 160 caracteres.1 to 160 characters
  • interactive.action.cards[].actionobjectrequired
  • interactive.action.cards[].action.namestringoptional
    Sempre cta_url.default: "cta_url"Values: cta_url
  • interactive.action.cards[].action.parametersobjectrequired
  • interactive.action.cards[].action.parameters.display_textstringrequired
    O rótulo do botão. Limite de 20 caracteres.1 to 20 characters
  • interactive.action.cards[].action.parameters.urlstring (uri)required
    O endereço que o botão abre.up to 2048 characters
  • interactive.action.parameters.flow_message_versionstringoptional
    A versão do formato da mensagem de Flow. O padrão é 3, a corrente na Meta.1 to 8 characters · default: "3"
  • interactive.action.parameters.flow_idstringoptional
    O identificador do Flow. Use este OU flow_name.1 to 64 characters
  • interactive.action.parameters.flow_namestringoptional
    O nome do Flow. Use este OU flow_id.1 to 200 characters
  • interactive.action.parameters.flow_ctastringrequired
    O rótulo do botão que abre o Flow. A Meta limita o tamanho (o limite exato está a confirmar na doc da Meta).1 to 40 characters
  • interactive.action.parameters.flow_tokenstringoptional
    O que você quer receber de volta na resposta do Flow, para ligá-la a este envio.up to 256 characters
  • interactive.action.parameters.flow_actionstringoptional
    navigate (padrão da Meta) ou data_exchange.1 to 32 characters
  • interactive.action.parameters.flow_action_payloadobjectoptional
    A tela e os dados de abertura, quando flow_action é navigate.
  • interactive.action.parameters.flow_action_payload.screenstringrequired
    A tela do Flow que abre primeiro.1 to 200 characters
  • interactive.action.parameters.flow_action_payload.dataobjectoptional
    Os dados que o Flow recebe nessa tela.
  • interactive.action.parameters.modestringoptional
    draft para testar um Flow ainda não publicado, ou published (padrão da Meta).1 to 16 characters
  • interactive.action.catalog_idstringrequired
    O identificador do catálogo na conta de negócio do número (catalog_id da Meta).1 to 64 characters
  • interactive.action.product_retailer_idstringrequired
    O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta).1 to 256 characters
  • interactive.action.sections[].product_itemsarray<object>required
    Os produtos da seção.1 to 30 items
  • interactive.action.sections[].product_items[].product_retailer_idstringrequired
    O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta).1 to 256 characters
Shape 11: type = "template"
  • fromstringrequired
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • tostringoptional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringoptional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectoptional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringrequired
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 to 256 characters
  • callbackDatastringoptional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 to 512 characters
  • typingMsintegeroptional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.minimum 1 · maximum 25000
  • typestringrequired
    Sempre template.Values: template
  • templateobjectrequired
  • template.namestringrequired
    O nome do template já aprovado pela Meta.1 to 512 characters
  • template.languageobjectrequired
  • template.language.codestringrequired
    O código do idioma do template, como pt_BR. Ele precisa bater com o aprovado.2 to 16 characters
  • template.componentsarray<object>optional
    Os componentes que preenchem as variáveis do template.up to 32 items
  • template.components[].typestringrequired
    Qual parte do template este componente preenche.Values: header body button
  • template.components[].sub_typestringoptional
    O subtipo, exigido pela Cloud API quando type é button.up to 64 characters
  • template.components[].indexstringoptional
    A posição do botão, exigida pela Cloud API quando type é button.up to 8 characters
  • template.components[].parametersarray<object>optional
    Os valores das variáveis desta parte, na forma que a Cloud API define.up to 64 items

Responses

202Accepted: the request was recorded and will be processed.
  • idstring (uuid)required
    O identificador da mensagem na Luna. Ele existe antes de a Meta responder.
  • statusstringrequired
    Sempre queued: a mensagem foi aceita e está na fila de saída.Values: queued
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
Service window closedJSON
{
  "error": "window_closed",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A janela de atendimento desta conversa está fechada. Só é possível enviar mensagem livre até 24 horas depois da última mensagem do contato.",
  "fechadaEm": "2026-10-06T12:00:00.000Z",
  "acaoRecomendada": "Para falar com este contato agora, envie um template aprovado. A mensagem livre volta a ser aceita quando o contato responder, porque é a resposta dele que abre a janela. Se este contato escreveu há pouco e a janela devia estar aberta, confira o campo to: use o telefone do evento recebido (wa_id).",
  "detalheTecnico": "A Luna já acha a conversa do celular brasileiro com e sem o nono dígito, mas qualquer outra diferença no telefone não encontra a conversa. Se o contato escreveu sem telefone (só com BSUID, o identificador de usuário), envie com recipient igual ao user_id do evento, e não com to."
}
Template that is not approved yetJSON
{
  "error": "template_not_approved",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "O template lembrete_consulta (pt_BR) está PENDING, e a Meta só entrega template APPROVED. Se está em análise, espere: o evento template.status chega no seu webhook, e GET /v1/templates/{id} mostra o estado atual. Se foi rejeitado, pausado ou desativado, corrija o template (PATCH /v1/templates/{id}) ou crie outro (POST /v1/templates).",
  "templateStatus": "PENDING"
}
Idempotency-Key used with another bodyJSON
{
  "error": "idempotency_key_reused",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "Esta Idempotency-Key já foi usada com outro corpo. Nada foi enviado. Use uma chave nova para uma mensagem nova, e reenvie o mesmo corpo para repetir a original."
}
Number disconnected from LunaJSON
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Send queue fullJSON
{
  "error": "queue_full",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A fila de envio deste número está cheia. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Mark a message as read

POST/v1/messages/{id}/read

Marks a message you received as read on Meta, and returns 200 once it accepts.

Authentication
API key
Required scope
messages:write

Path parameters

  • idstring (uuid)required
    O identificador da mensagem na Luna, como GET /v1/messages o devolve.

Responses

200A Meta aceitou a marcação.

No fields.

400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Number paceJSON
{
  "error": "number_rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "Este número está no limite de chamadas por segundo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Show the typing indicator

POST/v1/messages/{id}/typing

Shows the recipient that you are writing, and returns 200 once Meta accepts.

Authentication
API key
Required scope
messages:write

Path parameters

  • idstring (uuid)required
    O identificador da mensagem na Luna, como GET /v1/messages o devolve.

Responses

200A Meta aceitou o indicador.

No fields.

400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Number paceJSON
{
  "error": "number_rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "Este número está no limite de chamadas por segundo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read one message's state

GET/v1/messages/{id}

Returns the message's current state, the timestamp of each step, and what Meta said whenever it refused something.

Authentication
API key
Required scope
messages:read

Path parameters

  • idstring (uuid)required
    O identificador da mensagem na Luna, como GET /v1/messages o devolve.

Responses

200Success.
  • idstring (uuid)required
    O identificador da mensagem na Luna.
  • wamidstring | nullrequired
    O identificador da mensagem na Meta, o mesmo que os eventos de webhook trazem em wamid. Use-o para ligar um evento recebido a esta mensagem. Nulo enquanto a Meta ainda não aceitou o envio.
  • contentobject | nullrequired
    O que a mensagem carrega além do texto, nos dois sentidos, a mesma forma de content em GET /v1/messages. Na recebida, os nomes de campo da Meta, os mesmos do evento message.received; na enviada, o que você mandou (template, sent_interactive, media sem o link, location, reaction, contacts, context). Nulo em mensagem de texto enviada, e em mensagem recebida antes de a plataforma passar a guardar o conteúdo.
  • content.profile_namestring | nullrequired
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • content.mediaobject | nullrequired
    O arquivo que o interlocutor mandou. O tipo (imagem, vídeo, áudio, documento, figurinha) está em type. Os bytes saem por GET /v1/messages/{id}/media, e o identificador e a URL da Meta não são entregues: você não tem o token que os abre.
  • content.media.mime_typestring | nullrequired
    O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu.
  • content.media.sha256string | nullrequired
    O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type.
  • content.media.captionstring | nullrequired
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • content.media.filenamestring | nullrequired
    O nome do arquivo. Só documento tem.
  • content.media.voiceboolean | nullrequired
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • content.media.animatedboolean | nullrequired
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • content.interactiveobject | nullrequired
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • content.interactive.typestring | nullrequired
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • content.interactive.idstring | nullrequired
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • content.interactive.titlestring | nullrequired
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • content.interactive.descriptionstring | nullrequired
    A descrição do item da lista. Nula nos demais.
  • content.interactive.namestring | nullrequired
    O nome do Flow. Só em nfm_reply.
  • content.interactive.response_jsonstring | nullrequired
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • content.buttonobject | nullrequired
    O clique num botão de resposta rápida de um template.
  • content.button.payloadstring | nullrequired
    O payload que você definiu no botão de resposta rápida do template.
  • content.button.textstring | nullrequired
    O texto do botão.
  • content.locationobject | nullrequired
    A localização que o interlocutor compartilhou.
  • content.location.latitudenumber | nullrequired
    A latitude, em graus decimais.
  • content.location.longitudenumber | nullrequired
    A longitude, em graus decimais.
  • content.location.namestring | nullrequired
    O nome do lugar, quando o interlocutor escolheu um.
  • content.location.addressstring | nullrequired
    O endereço, quando há.
  • content.location.urlstring | nullrequired
    O endereço web do lugar, quando há.
  • content.contactsarray<object> | nullrequired
    Os cartões de contato que o interlocutor compartilhou.
  • content.contacts[].nameobject | nullrequired
    O nome do contato, nos campos da Meta.
  • content.contacts[].name.formatted_namestring | nullrequired
  • content.contacts[].name.first_namestring | nullrequired
  • content.contacts[].name.last_namestring | nullrequired
  • content.contacts[].name.middle_namestring | nullrequired
  • content.contacts[].name.prefixstring | nullrequired
  • content.contacts[].name.suffixstring | nullrequired
  • content.contacts[].phonesarray<object> | nullrequired
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • content.contacts[].phones[].phonestring | nullrequired
  • content.contacts[].phones[].wa_idstring | nullrequired
  • content.contacts[].phones[].typestring | nullrequired
  • content.contacts[].emailsarray<object> | nullrequired
    Os e-mails do contato.
  • content.contacts[].emails[].emailstring | nullrequired
  • content.contacts[].emails[].typestring | nullrequired
  • content.contacts[].orgobject | nullrequired
    A organização do contato.
  • content.contacts[].org.companystring | nullrequired
  • content.contacts[].org.departmentstring | nullrequired
  • content.contacts[].org.titlestring | nullrequired
  • content.reactionobject | nullrequired
    A reação a uma mensagem, ou a retirada dela.
  • content.reaction.wamidstring | nullrequired
    O wamid da mensagem que recebeu a reação.
  • content.reaction.emojistring | nullrequired
    O emoji. Nulo quando o interlocutor retirou a reação.
  • content.contextobject | nullrequired
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • content.context.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor citou ao responder.
  • content.context.fromstring | nullrequired
    Quem enviou a mensagem citada.
  • content.context.forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada.
  • content.context.frequently_forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • content.referralobject | nullrequired
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • content.referral.source_typestring | nullrequired
    A origem do clique, como ad ou post.
  • content.referral.source_idstring | nullrequired
    O identificador do anúncio ou da publicação na Meta.
  • content.referral.source_urlstring | nullrequired
    O endereço do anúncio ou da publicação.
  • content.referral.headlinestring | nullrequired
    O título do anúncio.
  • content.referral.bodystring | nullrequired
    O texto do anúncio.
  • content.referral.media_typestring | nullrequired
    O tipo da mídia do anúncio, como image ou video.
  • content.referral.ctwa_clidstring | nullrequired
    O identificador do clique, para atribuição de conversão.
  • content.unsupportedobject | nullrequired
    Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso".
  • content.unsupported.codeinteger | nullrequired
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • content.unsupported.titlestring | nullrequired
    O título do erro, como a Meta o mandou.
  • content.unsupported.detailsstring | nullrequired
    O detalhe do erro, como a Meta o mandou.
  • content.editobject | nullrequired
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • content.edit.wamidstring | nullrequired
    O wamid da mensagem que foi editada.
  • content.edit.typestring | nullrequired
    O tipo do conteúdo novo, como text.
  • content.edit.textstring | nullrequired
    O texto novo, quando o conteúdo novo é texto.
  • content.revokeobject | nullrequired
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • content.revoke.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor apagou para todos.
  • content.orderobject | nullrequired
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • content.order.catalog_idstring | nullrequired
    O catálogo de onde veio o pedido.
  • content.order.textstring | nullrequired
    O texto que o interlocutor escreveu junto com o pedido.
  • content.order.itemsarray<object> | nullrequired
    Os itens do pedido.
  • content.order.items[].product_retailer_idstring | nullrequired
    O identificador do produto no seu catálogo.
  • content.order.items[].quantitystring | nullrequired
    A quantidade pedida, como a Meta mandou.
  • content.order.items[].item_pricestring | nullrequired
    O preço unitário, como a Meta mandou.
  • content.order.items[].currencystring | nullrequired
    A moeda do preço.
  • content.templateobject | nullrequired
    O template que você enviou, com os valores que preencheram as variáveis.
  • content.template.namestring | nullrequired
    O nome do template que você enviou.
  • content.template.languagestring | nullrequired
    O idioma do template, no código da Meta (por exemplo pt_BR).
  • content.template.variablesarray<object> | nullrequired
    Os valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.
  • content.template.variables[].componentstringrequired
    Onde a variável entra: header, body ou button.
  • content.template.variables[].namestring | nullrequired
    O nome da variável, quando o template usa variáveis nomeadas. Nulo nas posicionais, em que a ordem na lista é a posição.
  • content.template.variables[].valuestringrequired
    O valor que você mandou. Parâmetro de imagem, vídeo ou documento não aparece: o link do arquivo não é devolvido.
  • content.sent_interactiveobject | nullrequired
    A mensagem interativa que você enviou: o texto, os botões ou itens que o seu cliente viu, e o endereço do botão de URL.
  • content.sent_interactive.typestring | nullrequired
    O tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.
  • content.sent_interactive.headerstring | nullrequired
    O texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.
  • content.sent_interactive.bodystring | nullrequired
    O texto do corpo.
  • content.sent_interactive.footerstring | nullrequired
    O texto do rodapé.
  • content.sent_interactive.buttonsarray<object> | nullrequired
    Os botões de resposta (id e título). Só em type button.
  • content.sent_interactive.buttons[].idstring | nullrequired
  • content.sent_interactive.buttons[].titlestring | nullrequired
  • content.sent_interactive.itemsarray<object> | nullrequired
    Os itens da lista, de todas as seções (id, título e descrição). Só em type list.
  • content.sent_interactive.items[].idstring | nullrequired
  • content.sent_interactive.items[].titlestring | nullrequired
  • content.sent_interactive.items[].descriptionstring | nullrequired
  • content.sent_interactive.ctaobject | nullrequired
    O botão de chamada: o rótulo e, no cta_url, o endereço que ele abre. No flow, só o rótulo.
  • content.sent_interactive.cta.textstring | nullrequired
  • content.sent_interactive.cta.urlstring | nullrequired
  • content.sent_interactive.catalog_idstring | nullrequired
    O catálogo de onde vêm os produtos. Só em type product e product_list.
  • content.sent_interactive.productsarray<object> | nullrequired
    Os produtos enviados, com o título da seção a que pertencem (nulo no product, que não tem seção). Só em type product e product_list.
  • content.sent_interactive.products[].sectionstring | nullrequired
  • content.sent_interactive.products[].product_retailer_idstring | nullrequired
  • statusstring | nullrequired
    O estado atual da entrega, como a Meta o reportou por último. Nulo quando nenhum evento de status chegou ainda.
  • criadaEmstring | nullrequired
    Quando a Luna aceitou a mensagem, em ISO-8601 UTC.
  • enviadaEmstring | nullrequired
    Quando a Meta confirmou o envio. Nulo enquanto isso não aconteceu.
  • entregueEmstring | nullrequired
    Quando a mensagem chegou ao aparelho do destinatário. Nulo enquanto isso não aconteceu.
  • lidaEmstring | nullrequired
    Quando o destinatário leu a mensagem. Nulo enquanto isso não aconteceu, e também quando ele desliga a confirmação de leitura.
  • callbackDatastring | nullrequired
    A etiqueta que você mandou em callbackData ao enviar a mensagem (de 1 a 512 caracteres), devolvida como veio. Nulo quando o envio não trouxe etiqueta e em mensagem recebida.
  • pricingobject | nullrequired
    O custo que a Meta aplicou a esta mensagem, com os nomes dela: type e category juntos dizem se a Meta cobra e em que categoria. Vem nulo enquanto a Meta não o informou (ela o manda no estado sent e em um entre delivered e read) e em mensagem recebida. Não é a fatura da Meta, e a Luna não calcula valor em dinheiro: a fonte da verdade é o painel de cobrança dela.
  • pricing.billableboolean | nullrequired
    Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.
  • pricing.pricing_modelstring | nullrequired
    O modelo de preço da Meta, como ela informou (hoje PMP ou CBP).
  • pricing.typestring | nullrequired
    O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.
  • pricing.categorystring | nullrequired
    A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.
  • errosarray<object>required
    O que deu errado, em ordem de acontecimento, e vazio quando nada deu. Reúne o que a Meta recusou na hora do envio e o que ela informou depois por evento de status: você não precisa saber de qual das duas veio cada item.
  • erros[].codigointeger | nullrequired
    O código de erro da Meta, íntegro. Nulo quando não houve resposta da Meta: um tempo esgotado, por exemplo, não tem código.
  • erros[].categoriastringrequired
    A natureza do erro, no vocabulário da Helsen. O valor desconhecido é literal e deliberado: a Meta acrescenta códigos sem aviso, e um código ainda não mapeado chega assim em vez de ser traduzido para uma categoria que não é a dele.Values: parametro_invalido reauth_required recurso_inacessivel orcamento_management throughput_excedido estado_de_produto janela_de_atendimento midia_indisponivel nao_entregavel template_invalido ritmo_por_destinatario terminal transporte contrato desconhecido
  • erros[].mensagemstringrequired
    O que aconteceu, em português. É texto da Helsen, não a tradução da mensagem da Meta.
  • erros[].acaoRecomendadastringrequired
    O que fazer a respeito, em português e em uma frase acionável.
  • erros[].originalany | nullrequired
    O corpo de erro que a Meta devolveu, sem reescrita e sem filtro. É o que o suporte da Meta reconhece, e o fbtrace_id dentro dele é o que faz um chamado avançar. Atenção: ele pode conter o telefone do consumidor final e trechos da conversa, então trate-o com o mesmo cuidado do restante do conteúdo das mensagens antes de repassá-lo a terceiros. É nulo quando não houve resposta da Meta.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Cancel a message in the queue

DELETE/v1/messages/{id}

Cancels a message still in the outbound queue (accepted) and answers 204. It moves to the terminal state canceled, and the message.status event with status canceled reaches your webhook. If the message already went to Meta or has an outcome, it answers 409 message_not_cancelable with the current state.

Authentication
API key
Required scope
messages:write

Path parameters

  • idstring (uuid)required
    O identificador da mensagem na Luna, como POST /v1/messages o devolveu.

Responses

204No content: the operation was done and the response has no body.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
Message that already left the queueJSON
{
  "error": "message_not_cancelable",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "Só uma mensagem que ainda está na fila de saída pode ser cancelada, e esta já saiu para a Meta ou já tem um desfecho. O estado atual vem em status; confira o resultado com GET /v1/messages/{id}.",
  "status": "sent"
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Replay a message's webhook

POST/v1/messages/{id}/replay

Asks for this message's event to be delivered to your endpoint again: the message.received if it was received, or the latest message.status if it was sent, with the same format and the same signature as the original. The response is 202: the request was recorded, and delivery happens asynchronously. A sent message that has no state yet, or that Meta has not accepted yet, answers 400.

Authentication
API key
Required scope
webhooks:write

Path parameters

  • idstring (uuid)required
    O identificador da mensagem na Luna, como GET /v1/messages o devolve.

Responses

202O pedido de reenvio foi registrado. A entrega acontece de forma assíncrona, pelo mesmo caminho de sempre.
  • deliveryIdstring (uuid)required
    O identificador desta entrega. Cada pedido gera um novo: o reenvio é entrega nova, e não reescrita de histórico.
  • requestedAtstringrequired
    Quando o pedido foi registrado, em UTC.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
No active webhook endpointJSON
{
  "error": "no_webhook_endpoint",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Não há endpoint de webhook ativo para entregar este reenvio. Cadastre um em POST /v1/webhooks/endpoints, ou retome um pausado em PATCH /v1/webhooks/endpoints/{id}, e peça de novo."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Simulate a received message

POST/v1/test-mode/inbound-messages

Delivers ONE example message.received to your webhook endpoints, signed and with test: true on the envelope, so you can exercise your code without waiting for a contact to write. The message goes out in about half a second, and nothing is stored or goes through a number of yours or through Meta. It works with the test key and with the regular key.

Authentication
API key
Required scope
messages:write

Request body

application/json · required

  • phoneNumberIdstringoptional
    O phone_number_id que aparece no evento. Texto livre: a Luna não procura o número. Ausente, 123456789012345.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • waIdstringoptional
    O telefone de quem "escreveu", só dígitos. Ausente, 5511900000000./^[1-9]\d{7,14}$/
  • textstringoptional
    O texto da mensagem recebida. Ausente, um texto de exemplo.1 to 4096 characters

Responses

202Accepted: the request was recorded and will be processed.
  • idstring (uuid)required
    O id da mensagem simulada, o mesmo que vai em message.id do evento.
  • wamidstringrequired
    O wamid simulado. Começa com wamid.TESTE_ para nunca se confundir com um da Meta.
  • endpointsintegerrequired
    Quantos dos seus endpoints de webhook vão receber o evento: os ativos, sem filtro de cliente ou de número, que aceitam message.received. Zero quer dizer que nada vai chegar: cadastre um endpoint.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}