Messages
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.
Query parameters
limitintegeroptionalQuantas 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 1000formatstringoptionaljson (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:jsoncsvphoneNumberIdstringoptionalO 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_-]+$/externalIdstringoptionalO 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 charactersconversationIdstring (uuid)optionalwaIdstringoptionalO 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 charactersuserIdstringoptionalO 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 charactersdirectionstringoptionalinbound: só o que chegou. outbound: só o que você enviou.Values:inboundoutboundstatusstringoptionalO 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 characterssincestring (date-time) | string (date)optionalSó 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)optionalSó as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until).wamidstringoptionalO 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 characterscursorstringoptionalup to 256 characters
Responses
200Success.
dataarray<object>requireddata[].idstring (uuid)requireddata[].directionstringrequireddata[].wamidstring | nullrequireddata[].typestring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.data[].content.mediaobject | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO 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 | nullrequiredA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.data[].content.media.filenamestring | nullrequiredO nome do arquivo. Só documento tem.data[].content.media.voiceboolean | nullrequiredVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.data[].content.media.animatedboolean | nullrequiredVerdadeiro quando a figurinha é animada. Só figurinha tem.data[].content.interactiveobject | nullrequiredA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.data[].content.interactive.typestring | nullrequiredQual 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 | nullrequiredO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.data[].content.interactive.titlestring | nullrequiredO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.data[].content.interactive.descriptionstring | nullrequiredA descrição do item da lista. Nula nos demais.data[].content.interactive.namestring | nullrequiredO nome do Flow. Só em nfm_reply.data[].content.interactive.response_jsonstring | nullrequiredAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.data[].content.buttonobject | nullrequiredO clique num botão de resposta rápida de um template.data[].content.button.payloadstring | nullrequiredO payload que você definiu no botão de resposta rápida do template.data[].content.button.textstring | nullrequiredO texto do botão.data[].content.locationobject | nullrequiredA localização que o interlocutor compartilhou.data[].content.location.latitudenumber | nullrequiredA latitude, em graus decimais.data[].content.location.longitudenumber | nullrequiredA longitude, em graus decimais.data[].content.location.namestring | nullrequiredO nome do lugar, quando o interlocutor escolheu um.data[].content.location.addressstring | nullrequiredO endereço, quando há.data[].content.location.urlstring | nullrequiredO endereço web do lugar, quando há.data[].content.contactsarray<object> | nullrequiredOs cartões de contato que o interlocutor compartilhou.data[].content.contacts[].nameobject | nullrequiredO nome do contato, nos campos da Meta.data[].content.contacts[].name.formatted_namestring | nullrequireddata[].content.contacts[].name.first_namestring | nullrequireddata[].content.contacts[].name.last_namestring | nullrequireddata[].content.contacts[].name.middle_namestring | nullrequireddata[].content.contacts[].name.prefixstring | nullrequireddata[].content.contacts[].name.suffixstring | nullrequireddata[].content.contacts[].phonesarray<object> | nullrequiredOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.data[].content.contacts[].phones[].phonestring | nullrequireddata[].content.contacts[].phones[].wa_idstring | nullrequireddata[].content.contacts[].phones[].typestring | nullrequireddata[].content.contacts[].emailsarray<object> | nullrequiredOs e-mails do contato.data[].content.contacts[].emails[].emailstring | nullrequireddata[].content.contacts[].emails[].typestring | nullrequireddata[].content.contacts[].orgobject | nullrequiredA organização do contato.data[].content.contacts[].org.companystring | nullrequireddata[].content.contacts[].org.departmentstring | nullrequireddata[].content.contacts[].org.titlestring | nullrequireddata[].content.reactionobject | nullrequiredA reação a uma mensagem, ou a retirada dela.data[].content.reaction.wamidstring | nullrequiredO wamid da mensagem que recebeu a reação.data[].content.reaction.emojistring | nullrequiredO emoji. Nulo quando o interlocutor retirou a reação.data[].content.contextobject | nullrequiredA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.data[].content.context.wamidstring | nullrequiredO wamid da mensagem que o interlocutor citou ao responder.data[].content.context.fromstring | nullrequiredQuem enviou a mensagem citada.data[].content.context.forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada.data[].content.context.frequently_forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada muitas vezes.data[].content.referralobject | nullrequiredO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.data[].content.referral.source_typestring | nullrequiredA origem do clique, como ad ou post.data[].content.referral.source_idstring | nullrequiredO identificador do anúncio ou da publicação na Meta.data[].content.referral.source_urlstring | nullrequiredO endereço do anúncio ou da publicação.data[].content.referral.headlinestring | nullrequiredO título do anúncio.data[].content.referral.bodystring | nullrequiredO texto do anúncio.data[].content.referral.media_typestring | nullrequiredO tipo da mídia do anúncio, como image ou video.data[].content.referral.ctwa_clidstring | nullrequiredO identificador do clique, para atribuição de conversão.data[].content.unsupportedobject | nullrequiredPresente 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 | nullrequiredO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").data[].content.unsupported.titlestring | nullrequiredO título do erro, como a Meta o mandou.data[].content.unsupported.detailsstring | nullrequiredO detalhe do erro, como a Meta o mandou.data[].content.editobject | nullrequiredPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).data[].content.edit.wamidstring | nullrequiredO wamid da mensagem que foi editada.data[].content.edit.typestring | nullrequiredO tipo do conteúdo novo, como text.data[].content.edit.textstring | nullrequiredO texto novo, quando o conteúdo novo é texto.data[].content.revokeobject | nullrequiredPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).data[].content.revoke.wamidstring | nullrequiredO wamid da mensagem que o interlocutor apagou para todos.data[].content.orderobject | nullrequiredO pedido que o interlocutor montou num catálogo e enviou (type é order).data[].content.order.catalog_idstring | nullrequiredO catálogo de onde veio o pedido.data[].content.order.textstring | nullrequiredO texto que o interlocutor escreveu junto com o pedido.data[].content.order.itemsarray<object> | nullrequiredOs itens do pedido.data[].content.order.items[].product_retailer_idstring | nullrequiredO identificador do produto no seu catálogo.data[].content.order.items[].quantitystring | nullrequiredA quantidade pedida, como a Meta mandou.data[].content.order.items[].item_pricestring | nullrequiredO preço unitário, como a Meta mandou.data[].content.order.items[].currencystring | nullrequiredA moeda do preço.data[].content.templateobject | nullrequiredO template que você enviou, com os valores que preencheram as variáveis.data[].content.template.namestring | nullrequiredO nome do template que você enviou.data[].content.template.languagestring | nullrequiredO idioma do template, no código da Meta (por exemplo pt_BR).data[].content.template.variablesarray<object> | nullrequiredOs valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.data[].content.template.variables[].componentstringrequiredOnde a variável entra: header, body ou button.data[].content.template.variables[].namestring | nullrequiredO 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[].valuestringrequiredO 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 | nullrequiredA 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 | nullrequiredO tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.data[].content.sent_interactive.headerstring | nullrequiredO texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.data[].content.sent_interactive.bodystring | nullrequiredO texto do corpo.data[].content.sent_interactive.footerstring | nullrequiredO texto do rodapé.data[].content.sent_interactive.buttonsarray<object> | nullrequiredOs botões de resposta (id e título). Só em type button.data[].content.sent_interactive.buttons[].idstring | nullrequireddata[].content.sent_interactive.buttons[].titlestring | nullrequireddata[].content.sent_interactive.itemsarray<object> | nullrequiredOs itens da lista, de todas as seções (id, título e descrição). Só em type list.data[].content.sent_interactive.items[].idstring | nullrequireddata[].content.sent_interactive.items[].titlestring | nullrequireddata[].content.sent_interactive.items[].descriptionstring | nullrequireddata[].content.sent_interactive.ctaobject | nullrequiredO 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 | nullrequireddata[].content.sent_interactive.cta.urlstring | nullrequireddata[].content.sent_interactive.catalog_idstring | nullrequiredO catálogo de onde vêm os produtos. Só em type product e product_list.data[].content.sent_interactive.productsarray<object> | nullrequiredOs 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 | nullrequireddata[].content.sent_interactive.products[].product_retailer_idstring | nullrequireddata[].callbackDatastring | nullrequiredA 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 | nullrequireddata[].pricingobject | nullrequiredO 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 | nullrequiredSe a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.data[].pricing.pricing_modelstring | nullrequiredO modelo de preço da Meta, como ela informou (hoje PMP ou CBP).data[].pricing.typestring | nullrequiredO tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.data[].pricing.categorystring | nullrequiredA categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.data[].waIdstring | nullrequiredO 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 | nullrequiredO BSUID do interlocutor, como a Meta o mandou. Nulo quando a Meta nunca o mandou para esta conversa.data[].parentUserIdstring | nullrequiredO BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais.data[].usernamestring | nullrequiredO nome de usuário do interlocutor, quando ele adotou um. Nulo no demais.data[].displayNumberstring | nullrequireddata[].numberIdstring (uuid) | nullrequiredO 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 | nullrequiredO 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) | nullrequiredA conversa da mensagem, o mesmo id de GET /v1/conversations. Nulo quando não há conversa resolvida.data[].errorSummaryobject | nullrequiredPor 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 | nullrequiredO código do erro da Meta, quando ela mandou um.data[].errorSummary.mensagemstringrequiredO que aconteceu, em português.data[].errorSummary.acaoRecomendadastringrequiredO que fazer a respeito, em português.data[].createdAtstringrequirednextCursorstring | nullrequiredMande 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Request body
The body is one of these shapes (pick one):
Shape 1: type = "text"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringoptionalSempre 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:texttextobjectrequiredtext.bodystringrequiredO texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API.1 to 4096 characterstext.preview_urlbooleanoptionalSe 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"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre image.Values:imageimageobjectrequiredimage.idstringoptionalO 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 charactersimage.linkstring (uri)optionalA 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 charactersimage.captionstringoptionalA legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.up to 1024 characters
Shape 3: type = "video"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre video.Values:videovideoobjectrequiredvideo.idstringoptionalO 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 charactersvideo.linkstring (uri)optionalA 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 charactersvideo.captionstringoptionalA legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.up to 1024 characters
Shape 4: type = "audio"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre audio.Values:audioaudioobjectrequiredaudio.idstringoptionalO 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 charactersaudio.linkstring (uri)optionalA 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 charactersaudio.voicebooleanoptionaltrue 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"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre document.Values:documentdocumentobjectrequireddocument.idstringoptionalO 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 charactersdocument.linkstring (uri)optionalA 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 charactersdocument.captionstringoptionalA legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.up to 1024 charactersdocument.filenamestringoptionalO 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"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre sticker.Values:stickerstickerobjectrequiredsticker.idstringoptionalO 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 characterssticker.linkstring (uri)optionalA 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"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre location.Values:locationlocationobjectrequiredlocation.latitudenumberrequiredA latitude em graus decimais, entre -90 e 90.minimum -90 · maximum 90location.longitudenumberrequiredA longitude em graus decimais, entre -180 e 180.minimum -180 · maximum 180location.namestringoptionalO nome do lugar, exibido acima do endereço.up to 1000 characterslocation.addressstringoptionalO endereço do lugar, exibido abaixo do nome.up to 1000 characters
Shape 8: type = "contacts"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre contacts.Values:contactscontactsarray<object>requiredOs cartões de contato a enviar. Ao menos um, no máximo vinte.1 to 20 itemscontacts[].nameobjectrequiredcontacts[].name.formatted_namestringrequiredO nome como ele aparece no cartão.1 to 512 characterscontacts[].name.first_namestringoptionalO primeiro nome.up to 256 characterscontacts[].name.last_namestringoptionalO sobrenome.up to 256 characterscontacts[].name.middle_namestringoptionalO nome do meio.up to 256 characterscontacts[].name.prefixstringoptionalO prefixo, como Dr. ou Sra.up to 64 characterscontacts[].name.suffixstringoptionalO sufixo, como Jr. ou Neto.up to 64 characterscontacts[].birthdaystringoptionalA data de nascimento em AAAA-MM-DD./^\d{4}-\d{2}-\d{2}$/contacts[].orgobjectoptionalOs dados profissionais do contato.contacts[].org.companystringoptionalA empresa.up to 256 characterscontacts[].org.departmentstringoptionalO departamento.up to 256 characterscontacts[].org.titlestringoptionalO cargo.up to 256 characterscontacts[].phonesarray<object>optionalOs telefones do contato.up to 20 itemscontacts[].phones[].phonestringoptionalO telefone, como ele deve aparecer.up to 64 characterscontacts[].phones[].typestringoptionalO rótulo do telefone, como CELL ou WORK.up to 64 characterscontacts[].phones[].wa_idstringoptionalO identificador do contato no WhatsApp, se conhecido.up to 64 characterscontacts[].emailsarray<object>optionalOs e-mails do contato.up to 20 itemscontacts[].emails[].emailstringoptionalO endereço de e-mail.up to 320 characterscontacts[].emails[].typestringoptionalO rótulo do e-mail, como HOME ou WORK.up to 64 characterscontacts[].addressesarray<object>optionalOs endereços do contato.up to 20 itemscontacts[].addresses[].streetstringoptionalO logradouro e o número.up to 512 characterscontacts[].addresses[].citystringoptionalA cidade.up to 256 characterscontacts[].addresses[].statestringoptionalO estado.up to 256 characterscontacts[].addresses[].zipstringoptionalO CEP.up to 64 characterscontacts[].addresses[].countrystringoptionalO país.up to 256 characterscontacts[].addresses[].country_codestringoptionalO código do país em duas letras.up to 8 characterscontacts[].addresses[].typestringoptionalO rótulo do endereço, como HOME ou WORK.up to 64 characterscontacts[].urlsarray<object>optionalAs páginas do contato.up to 20 itemscontacts[].urls[].urlstringoptionalO endereço na web.up to 2048 characterscontacts[].urls[].typestringoptionalO rótulo da URL, como HOME ou WORK.up to 64 characters
Shape 9: type = "reaction"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre reaction.Values:reactionreactionobjectrequiredreaction.message_idstringrequiredA 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 charactersreaction.emojistringrequiredO emoji da reação. Mande vazio para remover uma reação que já tinha sido posta.up to 16 characters
Shape 10: type = "interactive"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre interactive.Values:interactiveinteractiveobjectrequiredA 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.typestringoptionalSempre button.Values:buttoninteractive.headerobjectoptionalO cabeçalho, exibido acima do corpo.interactive.header.typestringrequiredO que o cabeçalho carrega.Values:textimagevideodocumentinteractive.header.textstringoptionalO texto do cabeçalho, quando type é text.up to 60 charactersinteractive.header.imageobjectoptionalA imagem do cabeçalho, quando type é image.interactive.header.image.idstringoptionalO 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 charactersinteractive.header.image.linkstring (uri)optionalA 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 charactersinteractive.header.videoobjectoptionalO vídeo do cabeçalho, quando type é video.interactive.header.video.idstringoptionalO 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 charactersinteractive.header.video.linkstring (uri)optionalA 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 charactersinteractive.header.documentobjectoptionalO documento do cabeçalho, quando type é document.interactive.header.document.idstringoptionalO 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 charactersinteractive.header.document.linkstring (uri)optionalA 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 charactersinteractive.header.document.filenamestringoptionalup to 240 charactersinteractive.bodyobjectoptionalO corpo da mensagem interativa.interactive.body.textstringrequiredO texto do corpo.1 to 1024 charactersinteractive.footerobjectoptionalO rodapé, exibido abaixo dos botões.interactive.footer.textstringrequiredO texto do rodapé.up to 60 charactersinteractive.actionobjectoptionalinteractive.action.buttonsarray<object>requiredOs botões de resposta. De um a três, o teto da Cloud API.1 to 3 itemsinteractive.action.buttons[].typestringrequiredSempre reply.Values:replyinteractive.action.buttons[].replyobjectrequiredinteractive.action.buttons[].reply.idstringrequiredO identificador que volta no webhook quando o botão é tocado.1 to 256 charactersinteractive.action.buttons[].reply.titlestringrequiredO rótulo do botão. Limite de 20 caracteres.1 to 20 charactersinteractive.action.buttonstringrequiredO rótulo do botão que abre a lista. Limite de 20 caracteres.1 to 20 charactersinteractive.action.sectionsarray<object>requiredAs seções da lista. De uma a dez, o teto da Cloud API.1 to 10 itemsinteractive.action.sections[].titlestringoptionalO título da seção.up to 24 charactersinteractive.action.sections[].rowsarray<object>requiredAs linhas da seção. De uma a dez.1 to 10 itemsinteractive.action.sections[].rows[].idstringrequiredO identificador que volta no webhook quando a linha é escolhida.1 to 200 charactersinteractive.action.sections[].rows[].titlestringrequiredO título da linha.1 to 24 charactersinteractive.action.sections[].rows[].descriptionstringoptionalA descrição da linha.up to 72 charactersinteractive.action.namestringoptionalSempre cta_url.default: "cta_url"Values:cta_urlinteractive.action.parametersobjectrequiredinteractive.action.parameters.display_textstringrequiredO rótulo do botão. Limite de 20 caracteres.1 to 20 charactersinteractive.action.parameters.urlstring (uri)requiredO endereço que o botão abre.up to 2048 charactersinteractive.action.parameters.countrystringoptionalO país do endereço, em duas letras (ISO 3166). O padrão é BR./^[A-Za-z]{2}$/ · default: "BR"interactive.action.parameters.valuesobjectoptionalOs campos do endereço já preenchidos, com os nomes que a Meta define para o país.interactive.action.parameters.saved_addressesarray<object>optionalEndereços salvos que o usuário pode escolher, no máximo vinte.up to 20 itemsinteractive.action.parameters.saved_addresses[].idstringrequiredO identificador do endereço salvo.1 to 128 charactersinteractive.action.parameters.saved_addresses[].valueobjectrequiredOs campos do endereço salvo.interactive.action.parameters.validation_errorsobjectoptionalMensagens de erro por campo, para quando você devolve o formulário depois de uma validação.interactive.action.cardsarray<object>requiredOs cartões, de dois a dez.2 to 10 itemsinteractive.action.cards[].card_indexintegerrequiredA posição do cartão, de 0 a 9. Não repita.minimum 0 · maximum 9interactive.action.cards[].typestringoptionalSempre cta_url.default: "cta_url"Values:cta_urlinteractive.action.cards[].headerobjectrequiredA mídia do cartão.interactive.action.cards[].header.typestringrequiredO que o cartão mostra.Values:imagevideointeractive.action.cards[].header.imageobjectoptionalA imagem do cartão, quando type é image.interactive.action.cards[].header.image.idstringoptionalO 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 charactersinteractive.action.cards[].header.image.linkstring (uri)optionalA 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 charactersinteractive.action.cards[].header.videoobjectoptionalO vídeo do cartão, quando type é video.interactive.action.cards[].header.video.idstringoptionalO 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 charactersinteractive.action.cards[].header.video.linkstring (uri)optionalA 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 charactersinteractive.action.cards[].bodyobjectoptionalO texto do cartão.interactive.action.cards[].body.textstringrequiredO texto do cartão. Limite de 160 caracteres.1 to 160 charactersinteractive.action.cards[].actionobjectrequiredinteractive.action.cards[].action.namestringoptionalSempre cta_url.default: "cta_url"Values:cta_urlinteractive.action.cards[].action.parametersobjectrequiredinteractive.action.cards[].action.parameters.display_textstringrequiredO rótulo do botão. Limite de 20 caracteres.1 to 20 charactersinteractive.action.cards[].action.parameters.urlstring (uri)requiredO endereço que o botão abre.up to 2048 charactersinteractive.action.parameters.flow_message_versionstringoptionalA 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_idstringoptionalO identificador do Flow. Use este OU flow_name.1 to 64 charactersinteractive.action.parameters.flow_namestringoptionalO nome do Flow. Use este OU flow_id.1 to 200 charactersinteractive.action.parameters.flow_ctastringrequiredO 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 charactersinteractive.action.parameters.flow_tokenstringoptionalO que você quer receber de volta na resposta do Flow, para ligá-la a este envio.up to 256 charactersinteractive.action.parameters.flow_actionstringoptionalnavigate (padrão da Meta) ou data_exchange.1 to 32 charactersinteractive.action.parameters.flow_action_payloadobjectoptionalA tela e os dados de abertura, quando flow_action é navigate.interactive.action.parameters.flow_action_payload.screenstringrequiredA tela do Flow que abre primeiro.1 to 200 charactersinteractive.action.parameters.flow_action_payload.dataobjectoptionalOs dados que o Flow recebe nessa tela.interactive.action.parameters.modestringoptionaldraft para testar um Flow ainda não publicado, ou published (padrão da Meta).1 to 16 charactersinteractive.action.catalog_idstringrequiredO identificador do catálogo na conta de negócio do número (catalog_id da Meta).1 to 64 charactersinteractive.action.product_retailer_idstringrequiredO identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta).1 to 256 charactersinteractive.action.sections[].product_itemsarray<object>requiredOs produtos da seção.1 to 30 itemsinteractive.action.sections[].product_items[].product_retailer_idstringrequiredO 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"
fromstringrequiredO 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_-]+$/tostringoptionalO 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}$/recipientstringoptionalO 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.contextobjectoptionalResponder 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_idstringrequiredA 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 characterscallbackDatastringoptionalUma 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 characterstypingMsintegeroptionalMostra 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 25000typestringrequiredSempre template.Values:templatetemplateobjectrequiredtemplate.namestringrequiredO nome do template já aprovado pela Meta.1 to 512 characterstemplate.languageobjectrequiredtemplate.language.codestringrequiredO código do idioma do template, como pt_BR. Ele precisa bater com o aprovado.2 to 16 characterstemplate.componentsarray<object>optionalOs componentes que preenchem as variáveis do template.up to 32 itemstemplate.components[].typestringrequiredQual parte do template este componente preenche.Values:headerbodybuttontemplate.components[].sub_typestringoptionalO subtipo, exigido pela Cloud API quando type é button.up to 64 characterstemplate.components[].indexstringoptionalA posição do botão, exigida pela Cloud API quando type é button.up to 8 characterstemplate.components[].parametersarray<object>optionalOs 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)requiredO identificador da mensagem na Luna. Ele existe antes de a Meta responder.statusstringrequiredSempre 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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."
}{
"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.
{
"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.
{
"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."
}{
"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"
}{
"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."
}{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"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.
{
"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.
Path parameters
idstring (uuid)requiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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."
}{
"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."
}{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"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.
{
"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.
Path parameters
idstring (uuid)requiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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."
}{
"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."
}{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"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.
{
"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.
Path parameters
idstring (uuid)requiredO identificador da mensagem na Luna, como GET /v1/messages o devolve.
Responses
200Success.
idstring (uuid)requiredO identificador da mensagem na Luna.wamidstring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.content.mediaobject | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO 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 | nullrequiredA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.content.media.filenamestring | nullrequiredO nome do arquivo. Só documento tem.content.media.voiceboolean | nullrequiredVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.content.media.animatedboolean | nullrequiredVerdadeiro quando a figurinha é animada. Só figurinha tem.content.interactiveobject | nullrequiredA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.content.interactive.typestring | nullrequiredQual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).content.interactive.idstring | nullrequiredO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.content.interactive.titlestring | nullrequiredO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.content.interactive.descriptionstring | nullrequiredA descrição do item da lista. Nula nos demais.content.interactive.namestring | nullrequiredO nome do Flow. Só em nfm_reply.content.interactive.response_jsonstring | nullrequiredAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.content.buttonobject | nullrequiredO clique num botão de resposta rápida de um template.content.button.payloadstring | nullrequiredO payload que você definiu no botão de resposta rápida do template.content.button.textstring | nullrequiredO texto do botão.content.locationobject | nullrequiredA localização que o interlocutor compartilhou.content.location.latitudenumber | nullrequiredA latitude, em graus decimais.content.location.longitudenumber | nullrequiredA longitude, em graus decimais.content.location.namestring | nullrequiredO nome do lugar, quando o interlocutor escolheu um.content.location.addressstring | nullrequiredO endereço, quando há.content.location.urlstring | nullrequiredO endereço web do lugar, quando há.content.contactsarray<object> | nullrequiredOs cartões de contato que o interlocutor compartilhou.content.contacts[].nameobject | nullrequiredO nome do contato, nos campos da Meta.content.contacts[].name.formatted_namestring | nullrequiredcontent.contacts[].name.first_namestring | nullrequiredcontent.contacts[].name.last_namestring | nullrequiredcontent.contacts[].name.middle_namestring | nullrequiredcontent.contacts[].name.prefixstring | nullrequiredcontent.contacts[].name.suffixstring | nullrequiredcontent.contacts[].phonesarray<object> | nullrequiredOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.content.contacts[].phones[].phonestring | nullrequiredcontent.contacts[].phones[].wa_idstring | nullrequiredcontent.contacts[].phones[].typestring | nullrequiredcontent.contacts[].emailsarray<object> | nullrequiredOs e-mails do contato.content.contacts[].emails[].emailstring | nullrequiredcontent.contacts[].emails[].typestring | nullrequiredcontent.contacts[].orgobject | nullrequiredA organização do contato.content.contacts[].org.companystring | nullrequiredcontent.contacts[].org.departmentstring | nullrequiredcontent.contacts[].org.titlestring | nullrequiredcontent.reactionobject | nullrequiredA reação a uma mensagem, ou a retirada dela.content.reaction.wamidstring | nullrequiredO wamid da mensagem que recebeu a reação.content.reaction.emojistring | nullrequiredO emoji. Nulo quando o interlocutor retirou a reação.content.contextobject | nullrequiredA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.content.context.wamidstring | nullrequiredO wamid da mensagem que o interlocutor citou ao responder.content.context.fromstring | nullrequiredQuem enviou a mensagem citada.content.context.forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada.content.context.frequently_forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada muitas vezes.content.referralobject | nullrequiredO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.content.referral.source_typestring | nullrequiredA origem do clique, como ad ou post.content.referral.source_idstring | nullrequiredO identificador do anúncio ou da publicação na Meta.content.referral.source_urlstring | nullrequiredO endereço do anúncio ou da publicação.content.referral.headlinestring | nullrequiredO título do anúncio.content.referral.bodystring | nullrequiredO texto do anúncio.content.referral.media_typestring | nullrequiredO tipo da mídia do anúncio, como image ou video.content.referral.ctwa_clidstring | nullrequiredO identificador do clique, para atribuição de conversão.content.unsupportedobject | nullrequiredPresente 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 | nullrequiredO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").content.unsupported.titlestring | nullrequiredO título do erro, como a Meta o mandou.content.unsupported.detailsstring | nullrequiredO detalhe do erro, como a Meta o mandou.content.editobject | nullrequiredPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).content.edit.wamidstring | nullrequiredO wamid da mensagem que foi editada.content.edit.typestring | nullrequiredO tipo do conteúdo novo, como text.content.edit.textstring | nullrequiredO texto novo, quando o conteúdo novo é texto.content.revokeobject | nullrequiredPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).content.revoke.wamidstring | nullrequiredO wamid da mensagem que o interlocutor apagou para todos.content.orderobject | nullrequiredO pedido que o interlocutor montou num catálogo e enviou (type é order).content.order.catalog_idstring | nullrequiredO catálogo de onde veio o pedido.content.order.textstring | nullrequiredO texto que o interlocutor escreveu junto com o pedido.content.order.itemsarray<object> | nullrequiredOs itens do pedido.content.order.items[].product_retailer_idstring | nullrequiredO identificador do produto no seu catálogo.content.order.items[].quantitystring | nullrequiredA quantidade pedida, como a Meta mandou.content.order.items[].item_pricestring | nullrequiredO preço unitário, como a Meta mandou.content.order.items[].currencystring | nullrequiredA moeda do preço.content.templateobject | nullrequiredO template que você enviou, com os valores que preencheram as variáveis.content.template.namestring | nullrequiredO nome do template que você enviou.content.template.languagestring | nullrequiredO idioma do template, no código da Meta (por exemplo pt_BR).content.template.variablesarray<object> | nullrequiredOs valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.content.template.variables[].componentstringrequiredOnde a variável entra: header, body ou button.content.template.variables[].namestring | nullrequiredO 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[].valuestringrequiredO 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 | nullrequiredA 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 | nullrequiredO tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.content.sent_interactive.headerstring | nullrequiredO texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.content.sent_interactive.bodystring | nullrequiredO texto do corpo.content.sent_interactive.footerstring | nullrequiredO texto do rodapé.content.sent_interactive.buttonsarray<object> | nullrequiredOs botões de resposta (id e título). Só em type button.content.sent_interactive.buttons[].idstring | nullrequiredcontent.sent_interactive.buttons[].titlestring | nullrequiredcontent.sent_interactive.itemsarray<object> | nullrequiredOs itens da lista, de todas as seções (id, título e descrição). Só em type list.content.sent_interactive.items[].idstring | nullrequiredcontent.sent_interactive.items[].titlestring | nullrequiredcontent.sent_interactive.items[].descriptionstring | nullrequiredcontent.sent_interactive.ctaobject | nullrequiredO 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 | nullrequiredcontent.sent_interactive.cta.urlstring | nullrequiredcontent.sent_interactive.catalog_idstring | nullrequiredO catálogo de onde vêm os produtos. Só em type product e product_list.content.sent_interactive.productsarray<object> | nullrequiredOs 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 | nullrequiredcontent.sent_interactive.products[].product_retailer_idstring | nullrequiredstatusstring | nullrequiredO estado atual da entrega, como a Meta o reportou por último. Nulo quando nenhum evento de status chegou ainda.criadaEmstring | nullrequiredQuando a Luna aceitou a mensagem, em ISO-8601 UTC.enviadaEmstring | nullrequiredQuando a Meta confirmou o envio. Nulo enquanto isso não aconteceu.entregueEmstring | nullrequiredQuando a mensagem chegou ao aparelho do destinatário. Nulo enquanto isso não aconteceu.lidaEmstring | nullrequiredQuando o destinatário leu a mensagem. Nulo enquanto isso não aconteceu, e também quando ele desliga a confirmação de leitura.callbackDatastring | nullrequiredA 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 | nullrequiredO 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 | nullrequiredSe a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.pricing.pricing_modelstring | nullrequiredO modelo de preço da Meta, como ela informou (hoje PMP ou CBP).pricing.typestring | nullrequiredO tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.pricing.categorystring | nullrequiredA categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.errosarray<object>requiredO 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 | nullrequiredO 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[].categoriastringrequiredA 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_invalidoreauth_requiredrecurso_inacessivelorcamento_managementthroughput_excedidoestado_de_produtojanela_de_atendimentomidia_indisponivelnao_entregaveltemplate_invalidoritmo_por_destinatarioterminaltransportecontratodesconhecidoerros[].mensagemstringrequiredO que aconteceu, em português. É texto da Helsen, não a tradução da mensagem da Meta.erros[].acaoRecomendadastringrequiredO que fazer a respeito, em português e em uma frase acionável.erros[].originalany | nullrequiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Path parameters
idstring (uuid)requiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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."
}{
"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."
}{
"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.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Path parameters
idstring (uuid)requiredO 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)requiredO identificador desta entrega. Cada pedido gera um novo: o reenvio é entrega nova, e não reescrita de histórico.requestedAtstringrequiredQuando 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Request body
phoneNumberIdstringoptionalO 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_-]+$/waIdstringoptionalO telefone de quem "escreveu", só dígitos. Ausente, 5511900000000./^[1-9]\d{7,14}$/textstringoptionalO 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)requiredO id da mensagem simulada, o mesmo que vai em message.id do evento.wamidstringrequiredO wamid simulado. Começa com wamid.TESTE_ para nunca se confundir com um da Meta.endpointsintegerrequiredQuantos 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"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"
}{
"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."
}{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}