Mensagens
Enviar mensagens e consultar o que entrou e saiu. O envio é assíncrono: a resposta é 202 e a entrega acontece no ritmo que a Meta permite.
Listar mensagens
GET/v1/messages
O registro do que entrou e saiu, do mais recente para o mais antigo. Cada mensagem traz o número, o rótulo do cliente, a conversa e, quando falhou, o resumo do erro. Filtros: phoneNumberId, externalId, conversationId, waId, userId, wamid, direction, status, since e until. Parâmetro que a rota não conhece volta 400. format=csv devolve text/csv, com os mesmos filtros.
Parâmetros de consulta
limitintegeropcionalQuantas 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.mínimo 1 · máximo 1000formatstringopcionaljson (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.Valores:jsoncsvphoneNumberIdstringopcionalO número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/externalIdstringopcionalO 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 a 128 caracteresconversationIdstring (uuid)opcionalwaIdstringopcionalO 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 a 64 caracteresuserIdstringopcionalO 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 a 200 caracteresdirectionstringopcionalinbound: só o que chegou. outbound: só o que você enviou.Valores:inboundoutboundstatusstringopcionalO 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 a 32 caracteressincestring (date-time) | string (date)opcionalSó 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)opcionalSó as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until).wamidstringopcionalO 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 a 512 caracterescursorstringopcionalaté 256 caracteres
Respostas
200Sucesso.
dataarray<object>obrigatóriodata[].idstring (uuid)obrigatóriodata[].directionstringobrigatóriodata[].wamidstring | nullobrigatóriodata[].typestring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.data[].content.mediaobject | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.data[].content.media.filenamestring | nullobrigatórioO nome do arquivo. Só documento tem.data[].content.media.voiceboolean | nullobrigatórioVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.data[].content.media.animatedboolean | nullobrigatórioVerdadeiro quando a figurinha é animada. Só figurinha tem.data[].content.interactiveobject | nullobrigatórioA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.data[].content.interactive.typestring | nullobrigatórioQual 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 | nullobrigatórioO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.data[].content.interactive.titlestring | nullobrigatórioO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.data[].content.interactive.descriptionstring | nullobrigatórioA descrição do item da lista. Nula nos demais.data[].content.interactive.namestring | nullobrigatórioO nome do Flow. Só em nfm_reply.data[].content.interactive.response_jsonstring | nullobrigatórioAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.data[].content.buttonobject | nullobrigatórioO clique num botão de resposta rápida de um template.data[].content.button.payloadstring | nullobrigatórioO payload que você definiu no botão de resposta rápida do template.data[].content.button.textstring | nullobrigatórioO texto do botão.data[].content.locationobject | nullobrigatórioA localização que o interlocutor compartilhou.data[].content.location.latitudenumber | nullobrigatórioA latitude, em graus decimais.data[].content.location.longitudenumber | nullobrigatórioA longitude, em graus decimais.data[].content.location.namestring | nullobrigatórioO nome do lugar, quando o interlocutor escolheu um.data[].content.location.addressstring | nullobrigatórioO endereço, quando há.data[].content.location.urlstring | nullobrigatórioO endereço web do lugar, quando há.data[].content.contactsarray<object> | nullobrigatórioOs cartões de contato que o interlocutor compartilhou.data[].content.contacts[].nameobject | nullobrigatórioO nome do contato, nos campos da Meta.data[].content.contacts[].name.formatted_namestring | nullobrigatóriodata[].content.contacts[].name.first_namestring | nullobrigatóriodata[].content.contacts[].name.last_namestring | nullobrigatóriodata[].content.contacts[].name.middle_namestring | nullobrigatóriodata[].content.contacts[].name.prefixstring | nullobrigatóriodata[].content.contacts[].name.suffixstring | nullobrigatóriodata[].content.contacts[].phonesarray<object> | nullobrigatórioOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.data[].content.contacts[].phones[].phonestring | nullobrigatóriodata[].content.contacts[].phones[].wa_idstring | nullobrigatóriodata[].content.contacts[].phones[].typestring | nullobrigatóriodata[].content.contacts[].emailsarray<object> | nullobrigatórioOs e-mails do contato.data[].content.contacts[].emails[].emailstring | nullobrigatóriodata[].content.contacts[].emails[].typestring | nullobrigatóriodata[].content.contacts[].orgobject | nullobrigatórioA organização do contato.data[].content.contacts[].org.companystring | nullobrigatóriodata[].content.contacts[].org.departmentstring | nullobrigatóriodata[].content.contacts[].org.titlestring | nullobrigatóriodata[].content.reactionobject | nullobrigatórioA reação a uma mensagem, ou a retirada dela.data[].content.reaction.wamidstring | nullobrigatórioO wamid da mensagem que recebeu a reação.data[].content.reaction.emojistring | nullobrigatórioO emoji. Nulo quando o interlocutor retirou a reação.data[].content.contextobject | nullobrigatórioA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.data[].content.context.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor citou ao responder.data[].content.context.fromstring | nullobrigatórioQuem enviou a mensagem citada.data[].content.context.forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada.data[].content.context.frequently_forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada muitas vezes.data[].content.referralobject | nullobrigatórioO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.data[].content.referral.source_typestring | nullobrigatórioA origem do clique, como ad ou post.data[].content.referral.source_idstring | nullobrigatórioO identificador do anúncio ou da publicação na Meta.data[].content.referral.source_urlstring | nullobrigatórioO endereço do anúncio ou da publicação.data[].content.referral.headlinestring | nullobrigatórioO título do anúncio.data[].content.referral.bodystring | nullobrigatórioO texto do anúncio.data[].content.referral.media_typestring | nullobrigatórioO tipo da mídia do anúncio, como image ou video.data[].content.referral.ctwa_clidstring | nullobrigatórioO identificador do clique, para atribuição de conversão.data[].content.unsupportedobject | nullobrigatórioPresente 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 | nullobrigatórioO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").data[].content.unsupported.titlestring | nullobrigatórioO título do erro, como a Meta o mandou.data[].content.unsupported.detailsstring | nullobrigatórioO detalhe do erro, como a Meta o mandou.data[].content.editobject | nullobrigatórioPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).data[].content.edit.wamidstring | nullobrigatórioO wamid da mensagem que foi editada.data[].content.edit.typestring | nullobrigatórioO tipo do conteúdo novo, como text.data[].content.edit.textstring | nullobrigatórioO texto novo, quando o conteúdo novo é texto.data[].content.revokeobject | nullobrigatórioPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).data[].content.revoke.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor apagou para todos.data[].content.orderobject | nullobrigatórioO pedido que o interlocutor montou num catálogo e enviou (type é order).data[].content.order.catalog_idstring | nullobrigatórioO catálogo de onde veio o pedido.data[].content.order.textstring | nullobrigatórioO texto que o interlocutor escreveu junto com o pedido.data[].content.order.itemsarray<object> | nullobrigatórioOs itens do pedido.data[].content.order.items[].product_retailer_idstring | nullobrigatórioO identificador do produto no seu catálogo.data[].content.order.items[].quantitystring | nullobrigatórioA quantidade pedida, como a Meta mandou.data[].content.order.items[].item_pricestring | nullobrigatórioO preço unitário, como a Meta mandou.data[].content.order.items[].currencystring | nullobrigatórioA moeda do preço.data[].content.templateobject | nullobrigatórioO template que você enviou, com os valores que preencheram as variáveis.data[].content.template.namestring | nullobrigatórioO nome do template que você enviou.data[].content.template.languagestring | nullobrigatórioO idioma do template, no código da Meta (por exemplo pt_BR).data[].content.template.variablesarray<object> | nullobrigatórioOs valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.data[].content.template.variables[].componentstringobrigatórioOnde a variável entra: header, body ou button.data[].content.template.variables[].namestring | nullobrigatórioO 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[].valuestringobrigatórioO 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 | nullobrigatórioA 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 | nullobrigatórioO tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.data[].content.sent_interactive.headerstring | nullobrigatórioO texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.data[].content.sent_interactive.bodystring | nullobrigatórioO texto do corpo.data[].content.sent_interactive.footerstring | nullobrigatórioO texto do rodapé.data[].content.sent_interactive.buttonsarray<object> | nullobrigatórioOs botões de resposta (id e título). Só em type button.data[].content.sent_interactive.buttons[].idstring | nullobrigatóriodata[].content.sent_interactive.buttons[].titlestring | nullobrigatóriodata[].content.sent_interactive.itemsarray<object> | nullobrigatórioOs itens da lista, de todas as seções (id, título e descrição). Só em type list.data[].content.sent_interactive.items[].idstring | nullobrigatóriodata[].content.sent_interactive.items[].titlestring | nullobrigatóriodata[].content.sent_interactive.items[].descriptionstring | nullobrigatóriodata[].content.sent_interactive.ctaobject | nullobrigatórioO 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 | nullobrigatóriodata[].content.sent_interactive.cta.urlstring | nullobrigatóriodata[].content.sent_interactive.catalog_idstring | nullobrigatórioO catálogo de onde vêm os produtos. Só em type product e product_list.data[].content.sent_interactive.productsarray<object> | nullobrigatórioOs 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 | nullobrigatóriodata[].content.sent_interactive.products[].product_retailer_idstring | nullobrigatóriodata[].callbackDatastring | nullobrigatórioA 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 | nullobrigatóriodata[].pricingobject | nullobrigatórioO 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 | nullobrigatórioSe a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.data[].pricing.pricing_modelstring | nullobrigatórioO modelo de preço da Meta, como ela informou (hoje PMP ou CBP).data[].pricing.typestring | nullobrigatórioO tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.data[].pricing.categorystring | nullobrigatórioA categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.data[].waIdstring | nullobrigatórioO 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 | nullobrigatórioO BSUID do interlocutor, como a Meta o mandou. Nulo quando a Meta nunca o mandou para esta conversa.data[].parentUserIdstring | nullobrigatórioO BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais.data[].usernamestring | nullobrigatórioO nome de usuário do interlocutor, quando ele adotou um. Nulo no demais.data[].displayNumberstring | nullobrigatóriodata[].numberIdstring (uuid) | nullobrigatórioO 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 | nullobrigatórioO 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) | nullobrigatórioA conversa da mensagem, o mesmo id de GET /v1/conversations. Nulo quando não há conversa resolvida.data[].errorSummaryobject | nullobrigatórioPor 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 | nullobrigatórioO código do erro da Meta, quando ela mandou um.data[].errorSummary.mensagemstringobrigatórioO que aconteceu, em português.data[].errorSummary.acaoRecomendadastringobrigatórioO que fazer a respeito, em português.data[].createdAtstringobrigatórionextCursorstring | nullobrigatórioMande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Enviar mensagem
POST/v1/messages
Aceita a mensagem, devolve 202 com o identificador, e entrega à Meta de forma assíncrona. Com uma chave de teste, a mensagem NÃO vai à Meta: a Luna devolve o 202 e entrega ao seu webhook os estados simulados sent, delivered e read, com test: true. O cabeçalho opcional Idempotency-Key (de 1 a 255 caracteres visíveis, sem espaço) faz repetir o pedido devolver a mensagem original; vazio ou fora do formato volta 400.
Corpo da requisição
O corpo é uma destas formas (escolha uma):
Forma 1: type = "text"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringopcionalSempre text. Pode ser omitido: um corpo sem type é interpretado como texto, para não quebrar quem integrou antes dos demais tipos existirem.padrão: "text"Valores:texttextobjectobrigatóriotext.bodystringobrigatórioO texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API.1 a 4096 caracterestext.preview_urlbooleanopcionalSe 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.
Forma 2: type = "image"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre image.Valores:imageimageobjectobrigatórioimage.idstringopcionalO 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 a 128 caracteresimage.linkstring (uri)opcionalA 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.até 2048 caracteresimage.captionstringopcionalA legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.até 1024 caracteres
Forma 3: type = "video"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre video.Valores:videovideoobjectobrigatóriovideo.idstringopcionalO 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 a 128 caracteresvideo.linkstring (uri)opcionalA 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.até 2048 caracteresvideo.captionstringopcionalA legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.até 1024 caracteres
Forma 4: type = "audio"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre audio.Valores:audioaudioobjectobrigatórioaudio.idstringopcionalO 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 a 128 caracteresaudio.linkstring (uri)opcionalA 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.até 2048 caracteresaudio.voicebooleanopcionaltrue 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.
Forma 5: type = "document"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre document.Valores:documentdocumentobjectobrigatóriodocument.idstringopcionalO 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 a 128 caracteresdocument.linkstring (uri)opcionalA 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.até 2048 caracteresdocument.captionstringopcionalA legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.até 1024 caracteresdocument.filenamestringopcionalO nome com que o arquivo aparece para quem recebe. Sem ele, quem recebe vê o nome que a Meta derivar da origem.1 a 240 caracteres
Forma 6: type = "sticker"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre sticker.Valores:stickerstickerobjectobrigatóriosticker.idstringopcionalO 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 a 128 caracteressticker.linkstring (uri)opcionalA 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.até 2048 caracteres
Forma 7: type = "location"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre location.Valores:locationlocationobjectobrigatóriolocation.latitudenumberobrigatórioA latitude em graus decimais, entre -90 e 90.mínimo -90 · máximo 90location.longitudenumberobrigatórioA longitude em graus decimais, entre -180 e 180.mínimo -180 · máximo 180location.namestringopcionalO nome do lugar, exibido acima do endereço.até 1000 caractereslocation.addressstringopcionalO endereço do lugar, exibido abaixo do nome.até 1000 caracteres
Forma 8: type = "contacts"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre contacts.Valores:contactscontactsarray<object>obrigatórioOs cartões de contato a enviar. Ao menos um, no máximo vinte.1 a 20 itenscontacts[].nameobjectobrigatóriocontacts[].name.formatted_namestringobrigatórioO nome como ele aparece no cartão.1 a 512 caracterescontacts[].name.first_namestringopcionalO primeiro nome.até 256 caracterescontacts[].name.last_namestringopcionalO sobrenome.até 256 caracterescontacts[].name.middle_namestringopcionalO nome do meio.até 256 caracterescontacts[].name.prefixstringopcionalO prefixo, como Dr. ou Sra.até 64 caracterescontacts[].name.suffixstringopcionalO sufixo, como Jr. ou Neto.até 64 caracterescontacts[].birthdaystringopcionalA data de nascimento em AAAA-MM-DD./^\d{4}-\d{2}-\d{2}$/contacts[].orgobjectopcionalOs dados profissionais do contato.contacts[].org.companystringopcionalA empresa.até 256 caracterescontacts[].org.departmentstringopcionalO departamento.até 256 caracterescontacts[].org.titlestringopcionalO cargo.até 256 caracterescontacts[].phonesarray<object>opcionalOs telefones do contato.até 20 itenscontacts[].phones[].phonestringopcionalO telefone, como ele deve aparecer.até 64 caracterescontacts[].phones[].typestringopcionalO rótulo do telefone, como CELL ou WORK.até 64 caracterescontacts[].phones[].wa_idstringopcionalO identificador do contato no WhatsApp, se conhecido.até 64 caracterescontacts[].emailsarray<object>opcionalOs e-mails do contato.até 20 itenscontacts[].emails[].emailstringopcionalO endereço de e-mail.até 320 caracterescontacts[].emails[].typestringopcionalO rótulo do e-mail, como HOME ou WORK.até 64 caracterescontacts[].addressesarray<object>opcionalOs endereços do contato.até 20 itenscontacts[].addresses[].streetstringopcionalO logradouro e o número.até 512 caracterescontacts[].addresses[].citystringopcionalA cidade.até 256 caracterescontacts[].addresses[].statestringopcionalO estado.até 256 caracterescontacts[].addresses[].zipstringopcionalO CEP.até 64 caracterescontacts[].addresses[].countrystringopcionalO país.até 256 caracterescontacts[].addresses[].country_codestringopcionalO código do país em duas letras.até 8 caracterescontacts[].addresses[].typestringopcionalO rótulo do endereço, como HOME ou WORK.até 64 caracterescontacts[].urlsarray<object>opcionalAs páginas do contato.até 20 itenscontacts[].urls[].urlstringopcionalO endereço na web.até 2048 caracterescontacts[].urls[].typestringopcionalO rótulo da URL, como HOME ou WORK.até 64 caracteres
Forma 9: type = "reaction"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre reaction.Valores:reactionreactionobjectobrigatórioreaction.message_idstringobrigatórioA 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 a 256 caracteresreaction.emojistringobrigatórioO emoji da reação. Mande vazio para remover uma reação que já tinha sido posta.até 16 caracteres
Forma 10: type = "interactive"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre interactive.Valores:interactiveinteractiveobjectobrigatórioA 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.typestringopcionalSempre button.Valores:buttoninteractive.headerobjectopcionalO cabeçalho, exibido acima do corpo.interactive.header.typestringobrigatórioO que o cabeçalho carrega.Valores:textimagevideodocumentinteractive.header.textstringopcionalO texto do cabeçalho, quando type é text.até 60 caracteresinteractive.header.imageobjectopcionalA imagem do cabeçalho, quando type é image.interactive.header.image.idstringopcionalO 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 a 128 caracteresinteractive.header.image.linkstring (uri)opcionalA 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.até 2048 caracteresinteractive.header.videoobjectopcionalO vídeo do cabeçalho, quando type é video.interactive.header.video.idstringopcionalO 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 a 128 caracteresinteractive.header.video.linkstring (uri)opcionalA 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.até 2048 caracteresinteractive.header.documentobjectopcionalO documento do cabeçalho, quando type é document.interactive.header.document.idstringopcionalO 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 a 128 caracteresinteractive.header.document.linkstring (uri)opcionalA 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.até 2048 caracteresinteractive.header.document.filenamestringopcionalaté 240 caracteresinteractive.bodyobjectopcionalO corpo da mensagem interativa.interactive.body.textstringobrigatórioO texto do corpo.1 a 1024 caracteresinteractive.footerobjectopcionalO rodapé, exibido abaixo dos botões.interactive.footer.textstringobrigatórioO texto do rodapé.até 60 caracteresinteractive.actionobjectopcionalinteractive.action.buttonsarray<object>obrigatórioOs botões de resposta. De um a três, o teto da Cloud API.1 a 3 itensinteractive.action.buttons[].typestringobrigatórioSempre reply.Valores:replyinteractive.action.buttons[].replyobjectobrigatóriointeractive.action.buttons[].reply.idstringobrigatórioO identificador que volta no webhook quando o botão é tocado.1 a 256 caracteresinteractive.action.buttons[].reply.titlestringobrigatórioO rótulo do botão. Limite de 20 caracteres.1 a 20 caracteresinteractive.action.buttonstringobrigatórioO rótulo do botão que abre a lista. Limite de 20 caracteres.1 a 20 caracteresinteractive.action.sectionsarray<object>obrigatórioAs seções da lista. De uma a dez, o teto da Cloud API.1 a 10 itensinteractive.action.sections[].titlestringopcionalO título da seção.até 24 caracteresinteractive.action.sections[].rowsarray<object>obrigatórioAs linhas da seção. De uma a dez.1 a 10 itensinteractive.action.sections[].rows[].idstringobrigatórioO identificador que volta no webhook quando a linha é escolhida.1 a 200 caracteresinteractive.action.sections[].rows[].titlestringobrigatórioO título da linha.1 a 24 caracteresinteractive.action.sections[].rows[].descriptionstringopcionalA descrição da linha.até 72 caracteresinteractive.action.namestringopcionalSempre cta_url.padrão: "cta_url"Valores:cta_urlinteractive.action.parametersobjectobrigatóriointeractive.action.parameters.display_textstringobrigatórioO rótulo do botão. Limite de 20 caracteres.1 a 20 caracteresinteractive.action.parameters.urlstring (uri)obrigatórioO endereço que o botão abre.até 2048 caracteresinteractive.action.parameters.countrystringopcionalO país do endereço, em duas letras (ISO 3166). O padrão é BR./^[A-Za-z]{2}$/ · padrão: "BR"interactive.action.parameters.valuesobjectopcionalOs campos do endereço já preenchidos, com os nomes que a Meta define para o país.interactive.action.parameters.saved_addressesarray<object>opcionalEndereços salvos que o usuário pode escolher, no máximo vinte.até 20 itensinteractive.action.parameters.saved_addresses[].idstringobrigatórioO identificador do endereço salvo.1 a 128 caracteresinteractive.action.parameters.saved_addresses[].valueobjectobrigatórioOs campos do endereço salvo.interactive.action.parameters.validation_errorsobjectopcionalMensagens de erro por campo, para quando você devolve o formulário depois de uma validação.interactive.action.cardsarray<object>obrigatórioOs cartões, de dois a dez.2 a 10 itensinteractive.action.cards[].card_indexintegerobrigatórioA posição do cartão, de 0 a 9. Não repita.mínimo 0 · máximo 9interactive.action.cards[].typestringopcionalSempre cta_url.padrão: "cta_url"Valores:cta_urlinteractive.action.cards[].headerobjectobrigatórioA mídia do cartão.interactive.action.cards[].header.typestringobrigatórioO que o cartão mostra.Valores:imagevideointeractive.action.cards[].header.imageobjectopcionalA imagem do cartão, quando type é image.interactive.action.cards[].header.image.idstringopcionalO 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 a 128 caracteresinteractive.action.cards[].header.image.linkstring (uri)opcionalA 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.até 2048 caracteresinteractive.action.cards[].header.videoobjectopcionalO vídeo do cartão, quando type é video.interactive.action.cards[].header.video.idstringopcionalO 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 a 128 caracteresinteractive.action.cards[].header.video.linkstring (uri)opcionalA 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.até 2048 caracteresinteractive.action.cards[].bodyobjectopcionalO texto do cartão.interactive.action.cards[].body.textstringobrigatórioO texto do cartão. Limite de 160 caracteres.1 a 160 caracteresinteractive.action.cards[].actionobjectobrigatóriointeractive.action.cards[].action.namestringopcionalSempre cta_url.padrão: "cta_url"Valores:cta_urlinteractive.action.cards[].action.parametersobjectobrigatóriointeractive.action.cards[].action.parameters.display_textstringobrigatórioO rótulo do botão. Limite de 20 caracteres.1 a 20 caracteresinteractive.action.cards[].action.parameters.urlstring (uri)obrigatórioO endereço que o botão abre.até 2048 caracteresinteractive.action.parameters.flow_message_versionstringopcionalA versão do formato da mensagem de Flow. O padrão é 3, a corrente na Meta.1 a 8 caracteres · padrão: "3"interactive.action.parameters.flow_idstringopcionalO identificador do Flow. Use este OU flow_name.1 a 64 caracteresinteractive.action.parameters.flow_namestringopcionalO nome do Flow. Use este OU flow_id.1 a 200 caracteresinteractive.action.parameters.flow_ctastringobrigatórioO 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 a 40 caracteresinteractive.action.parameters.flow_tokenstringopcionalO que você quer receber de volta na resposta do Flow, para ligá-la a este envio.até 256 caracteresinteractive.action.parameters.flow_actionstringopcionalnavigate (padrão da Meta) ou data_exchange.1 a 32 caracteresinteractive.action.parameters.flow_action_payloadobjectopcionalA tela e os dados de abertura, quando flow_action é navigate.interactive.action.parameters.flow_action_payload.screenstringobrigatórioA tela do Flow que abre primeiro.1 a 200 caracteresinteractive.action.parameters.flow_action_payload.dataobjectopcionalOs dados que o Flow recebe nessa tela.interactive.action.parameters.modestringopcionaldraft para testar um Flow ainda não publicado, ou published (padrão da Meta).1 a 16 caracteresinteractive.action.catalog_idstringobrigatórioO identificador do catálogo na conta de negócio do número (catalog_id da Meta).1 a 64 caracteresinteractive.action.product_retailer_idstringobrigatórioO identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta).1 a 256 caracteresinteractive.action.sections[].product_itemsarray<object>obrigatórioOs produtos da seção.1 a 30 itensinteractive.action.sections[].product_items[].product_retailer_idstringobrigatórioO identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta).1 a 256 caracteres
Forma 11: type = "template"
fromstringobrigatórioO 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/tostringopcionalO 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}$/recipientstringopcionalO 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.contextobjectopcionalResponder 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_idstringobrigatórioA 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 a 256 caracterescallbackDatastringopcionalUma 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 a 512 caracterestypingMsintegeropcionalMostra 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.mínimo 1 · máximo 25000typestringobrigatórioSempre template.Valores:templatetemplateobjectobrigatóriotemplate.namestringobrigatórioO nome do template já aprovado pela Meta.1 a 512 caracterestemplate.languageobjectobrigatóriotemplate.language.codestringobrigatórioO código do idioma do template, como pt_BR. Ele precisa bater com o aprovado.2 a 16 caracterestemplate.componentsarray<object>opcionalOs componentes que preenchem as variáveis do template.até 32 itenstemplate.components[].typestringobrigatórioQual parte do template este componente preenche.Valores:headerbodybuttontemplate.components[].sub_typestringopcionalO subtipo, exigido pela Cloud API quando type é button.até 64 caracterestemplate.components[].indexstringopcionalA posição do botão, exigida pela Cloud API quando type é button.até 8 caracterestemplate.components[].parametersarray<object>opcionalOs valores das variáveis desta parte, na forma que a Cloud API define.até 64 itens
Respostas
202Aceito: o pedido foi registrado e será processado.
idstring (uuid)obrigatórioO identificador da mensagem na Luna. Ele existe antes de a Meta responder.statusstringobrigatórioSempre queued: a mensagem foi aceita e está na fila de saída.Valores:queued
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"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)."
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"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."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Marcar uma mensagem como lida
POST/v1/messages/{id}/read
Marca na Meta uma mensagem que você recebeu como lida, e responde 200 quando ela aceitou.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador da mensagem na Luna, como GET /v1/messages o devolve.
Respostas
200A Meta aceitou a marcação.
Sem campos.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"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."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Mostrar o indicador de digitando
POST/v1/messages/{id}/typing
Mostra ao destinatário que você está escrevendo, e responde 200 quando a Meta aceitou.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador da mensagem na Luna, como GET /v1/messages o devolve.
Respostas
200A Meta aceitou o indicador.
Sem campos.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"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."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Consultar o estado de uma mensagem
GET/v1/messages/{id}
Devolve o estado atual da mensagem, os instantes de cada etapa e o que a Meta disse quando recusou alguma coisa.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador da mensagem na Luna, como GET /v1/messages o devolve.
Respostas
200Sucesso.
idstring (uuid)obrigatórioO identificador da mensagem na Luna.wamidstring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.content.mediaobject | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.content.media.filenamestring | nullobrigatórioO nome do arquivo. Só documento tem.content.media.voiceboolean | nullobrigatórioVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.content.media.animatedboolean | nullobrigatórioVerdadeiro quando a figurinha é animada. Só figurinha tem.content.interactiveobject | nullobrigatórioA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.content.interactive.typestring | nullobrigatórioQual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).content.interactive.idstring | nullobrigatórioO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.content.interactive.titlestring | nullobrigatórioO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.content.interactive.descriptionstring | nullobrigatórioA descrição do item da lista. Nula nos demais.content.interactive.namestring | nullobrigatórioO nome do Flow. Só em nfm_reply.content.interactive.response_jsonstring | nullobrigatórioAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.content.buttonobject | nullobrigatórioO clique num botão de resposta rápida de um template.content.button.payloadstring | nullobrigatórioO payload que você definiu no botão de resposta rápida do template.content.button.textstring | nullobrigatórioO texto do botão.content.locationobject | nullobrigatórioA localização que o interlocutor compartilhou.content.location.latitudenumber | nullobrigatórioA latitude, em graus decimais.content.location.longitudenumber | nullobrigatórioA longitude, em graus decimais.content.location.namestring | nullobrigatórioO nome do lugar, quando o interlocutor escolheu um.content.location.addressstring | nullobrigatórioO endereço, quando há.content.location.urlstring | nullobrigatórioO endereço web do lugar, quando há.content.contactsarray<object> | nullobrigatórioOs cartões de contato que o interlocutor compartilhou.content.contacts[].nameobject | nullobrigatórioO nome do contato, nos campos da Meta.content.contacts[].name.formatted_namestring | nullobrigatóriocontent.contacts[].name.first_namestring | nullobrigatóriocontent.contacts[].name.last_namestring | nullobrigatóriocontent.contacts[].name.middle_namestring | nullobrigatóriocontent.contacts[].name.prefixstring | nullobrigatóriocontent.contacts[].name.suffixstring | nullobrigatóriocontent.contacts[].phonesarray<object> | nullobrigatórioOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.content.contacts[].phones[].phonestring | nullobrigatóriocontent.contacts[].phones[].wa_idstring | nullobrigatóriocontent.contacts[].phones[].typestring | nullobrigatóriocontent.contacts[].emailsarray<object> | nullobrigatórioOs e-mails do contato.content.contacts[].emails[].emailstring | nullobrigatóriocontent.contacts[].emails[].typestring | nullobrigatóriocontent.contacts[].orgobject | nullobrigatórioA organização do contato.content.contacts[].org.companystring | nullobrigatóriocontent.contacts[].org.departmentstring | nullobrigatóriocontent.contacts[].org.titlestring | nullobrigatóriocontent.reactionobject | nullobrigatórioA reação a uma mensagem, ou a retirada dela.content.reaction.wamidstring | nullobrigatórioO wamid da mensagem que recebeu a reação.content.reaction.emojistring | nullobrigatórioO emoji. Nulo quando o interlocutor retirou a reação.content.contextobject | nullobrigatórioA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.content.context.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor citou ao responder.content.context.fromstring | nullobrigatórioQuem enviou a mensagem citada.content.context.forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada.content.context.frequently_forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada muitas vezes.content.referralobject | nullobrigatórioO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.content.referral.source_typestring | nullobrigatórioA origem do clique, como ad ou post.content.referral.source_idstring | nullobrigatórioO identificador do anúncio ou da publicação na Meta.content.referral.source_urlstring | nullobrigatórioO endereço do anúncio ou da publicação.content.referral.headlinestring | nullobrigatórioO título do anúncio.content.referral.bodystring | nullobrigatórioO texto do anúncio.content.referral.media_typestring | nullobrigatórioO tipo da mídia do anúncio, como image ou video.content.referral.ctwa_clidstring | nullobrigatórioO identificador do clique, para atribuição de conversão.content.unsupportedobject | nullobrigatórioPresente 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 | nullobrigatórioO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").content.unsupported.titlestring | nullobrigatórioO título do erro, como a Meta o mandou.content.unsupported.detailsstring | nullobrigatórioO detalhe do erro, como a Meta o mandou.content.editobject | nullobrigatórioPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).content.edit.wamidstring | nullobrigatórioO wamid da mensagem que foi editada.content.edit.typestring | nullobrigatórioO tipo do conteúdo novo, como text.content.edit.textstring | nullobrigatórioO texto novo, quando o conteúdo novo é texto.content.revokeobject | nullobrigatórioPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).content.revoke.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor apagou para todos.content.orderobject | nullobrigatórioO pedido que o interlocutor montou num catálogo e enviou (type é order).content.order.catalog_idstring | nullobrigatórioO catálogo de onde veio o pedido.content.order.textstring | nullobrigatórioO texto que o interlocutor escreveu junto com o pedido.content.order.itemsarray<object> | nullobrigatórioOs itens do pedido.content.order.items[].product_retailer_idstring | nullobrigatórioO identificador do produto no seu catálogo.content.order.items[].quantitystring | nullobrigatórioA quantidade pedida, como a Meta mandou.content.order.items[].item_pricestring | nullobrigatórioO preço unitário, como a Meta mandou.content.order.items[].currencystring | nullobrigatórioA moeda do preço.content.templateobject | nullobrigatórioO template que você enviou, com os valores que preencheram as variáveis.content.template.namestring | nullobrigatórioO nome do template que você enviou.content.template.languagestring | nullobrigatórioO idioma do template, no código da Meta (por exemplo pt_BR).content.template.variablesarray<object> | nullobrigatórioOs valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.content.template.variables[].componentstringobrigatórioOnde a variável entra: header, body ou button.content.template.variables[].namestring | nullobrigatórioO 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[].valuestringobrigatórioO 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 | nullobrigatórioA 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 | nullobrigatórioO tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.content.sent_interactive.headerstring | nullobrigatórioO texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.content.sent_interactive.bodystring | nullobrigatórioO texto do corpo.content.sent_interactive.footerstring | nullobrigatórioO texto do rodapé.content.sent_interactive.buttonsarray<object> | nullobrigatórioOs botões de resposta (id e título). Só em type button.content.sent_interactive.buttons[].idstring | nullobrigatóriocontent.sent_interactive.buttons[].titlestring | nullobrigatóriocontent.sent_interactive.itemsarray<object> | nullobrigatórioOs itens da lista, de todas as seções (id, título e descrição). Só em type list.content.sent_interactive.items[].idstring | nullobrigatóriocontent.sent_interactive.items[].titlestring | nullobrigatóriocontent.sent_interactive.items[].descriptionstring | nullobrigatóriocontent.sent_interactive.ctaobject | nullobrigatórioO 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 | nullobrigatóriocontent.sent_interactive.cta.urlstring | nullobrigatóriocontent.sent_interactive.catalog_idstring | nullobrigatórioO catálogo de onde vêm os produtos. Só em type product e product_list.content.sent_interactive.productsarray<object> | nullobrigatórioOs 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 | nullobrigatóriocontent.sent_interactive.products[].product_retailer_idstring | nullobrigatóriostatusstring | nullobrigatórioO estado atual da entrega, como a Meta o reportou por último. Nulo quando nenhum evento de status chegou ainda.criadaEmstring | nullobrigatórioQuando a Luna aceitou a mensagem, em ISO-8601 UTC.enviadaEmstring | nullobrigatórioQuando a Meta confirmou o envio. Nulo enquanto isso não aconteceu.entregueEmstring | nullobrigatórioQuando a mensagem chegou ao aparelho do destinatário. Nulo enquanto isso não aconteceu.lidaEmstring | nullobrigatórioQuando o destinatário leu a mensagem. Nulo enquanto isso não aconteceu, e também quando ele desliga a confirmação de leitura.callbackDatastring | nullobrigatórioA 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 | nullobrigatórioO 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 | nullobrigatórioSe a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.pricing.pricing_modelstring | nullobrigatórioO modelo de preço da Meta, como ela informou (hoje PMP ou CBP).pricing.typestring | nullobrigatórioO tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.pricing.categorystring | nullobrigatórioA categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.errosarray<object>obrigatórioO 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 | nullobrigatórioO 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[].categoriastringobrigatórioA 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.Valores:parametro_invalidoreauth_requiredrecurso_inacessivelorcamento_managementthroughput_excedidoestado_de_produtojanela_de_atendimentomidia_indisponivelnao_entregaveltemplate_invalidoritmo_por_destinatarioterminaltransportecontratodesconhecidoerros[].mensagemstringobrigatórioO que aconteceu, em português. É texto da Helsen, não a tradução da mensagem da Meta.erros[].acaoRecomendadastringobrigatórioO que fazer a respeito, em português e em uma frase acionável.erros[].originalany | nullobrigatórioO 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.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Cancelar uma mensagem na fila
DELETE/v1/messages/{id}
Cancela uma mensagem que ainda está na fila de saída (accepted) e responde 204. Ela passa ao estado canceled, que é terminal, e o evento message.status com status canceled chega ao seu webhook. Se a mensagem já saiu para a Meta ou já tem desfecho, responde 409 message_not_cancelable com o estado atual.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador da mensagem na Luna, como POST /v1/messages o devolveu.
Respostas
204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"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"
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Reenviar o webhook de uma mensagem
POST/v1/messages/{id}/replay
Pede que o evento desta mensagem seja entregue de novo ao seu endpoint: o message.received, se ela foi recebida, ou o último message.status, se ela foi enviada, no mesmo formato do original e assinado do mesmo jeito. A resposta é 202: o pedido foi registrado, e a entrega acontece de forma assíncrona. Mensagem enviada que ainda não tem estado, ou que ainda não foi aceita pela Meta, responde 400.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador da mensagem na Luna, como GET /v1/messages o devolve.
Respostas
202O pedido de reenvio foi registrado. A entrega acontece de forma assíncrona, pelo mesmo caminho de sempre.
deliveryIdstring (uuid)obrigatórioO identificador desta entrega. Cada pedido gera um novo: o reenvio é entrega nova, e não reescrita de histórico.requestedAtstringobrigatórioQuando o pedido foi registrado, em UTC.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"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."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Simular uma mensagem recebida
POST/v1/test-mode/inbound-messages
Entrega aos seus endpoints de webhook UMA message.received de exemplo, assinada e com test: true no envelope, para você exercitar o seu código sem esperar um contato escrever. A mensagem sai em cerca de meio segundo, e nada é gravado nem passa por número seu ou pela Meta. Funciona com a chave de teste e com a chave comum.
Corpo da requisição
phoneNumberIdstringopcionalO phone_number_id que aparece no evento. Texto livre: a Luna não procura o número. Ausente, 123456789012345.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/waIdstringopcionalO telefone de quem "escreveu", só dígitos. Ausente, 5511900000000./^[1-9]\d{7,14}$/textstringopcionalO texto da mensagem recebida. Ausente, um texto de exemplo.1 a 4096 caracteres
Respostas
202Aceito: o pedido foi registrado e será processado.
idstring (uuid)obrigatórioO id da mensagem simulada, o mesmo que vai em message.id do evento.wamidstringobrigatórioO wamid simulado. Começa com wamid.TESTE_ para nunca se confundir com um da Meta.endpointsintegerobrigatórioQuantos 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.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"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."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe 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."
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}