LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Mensagens

Usar com IA

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.

Autenticação
Chave de API
Escopo exigido
messages:read

Parâmetros de consulta

  • limitintegeropcional
    Quantas mensagens trazer. Padrão 50, máximo 100. Com format=csv o padrão e o máximo são 1000. Mais que 100 sem format=csv responde 400.mínimo 1 · máximo 1000
  • formatstringopcional
    json (o padrão) ou csv. O csv vem em text/csv, uma linha por mensagem, com os mesmos filtros e a mesma ordem; a próxima página vem no cabeçalho X-Luna-Next-Cursor (ausente na última) e vai em cursor. Colunas: id, direction, wamid, type, bodyText, status, waId, userId, displayNumber, numberId, externalId, conversationId, errorCode, errorMessage, createdAt.Valores: json csv
  • phoneNumberIdstringopcional
    O 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_-]+$/
  • externalIdstringopcional
    O rótulo que você deu ao seu cliente (externalId): só as mensagens dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia.1 a 128 caracteres
  • conversationIdstring (uuid)opcional
  • waIdstringopcional
    O telefone do interlocutor (waId), só com dígitos: só as mensagens da conversa dele. Igualdade exata, e o celular do Brasil vale com e sem o nono dígito; um waId sem conversa devolve lista vazia.1 a 64 caracteres
  • userIdstringopcional
    O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só as mensagens da conversa dele. Igualdade exata; um userId sem conversa devolve lista vazia.1 a 200 caracteres
  • directionstringopcional
    inbound: só o que chegou. outbound: só o que você enviou.Valores: inbound outbound
  • statusstringopcional
    O status da mensagem, como a Meta o informa e como o campo status o devolve (por exemplo sent, delivered, read, failed). Igualdade exata, e um valor que nenhuma mensagem tem devolve lista vazia. Vale só para mensagem enviada, que é a que tem status.1 a 32 caracteres
  • sincestring (date-time) | string (date)opcional
    Só as mensagens criadas neste instante ou depois (ISO 8601: 2026-11-03T00:00:00.000Z, 2026-11-03T00:00:00-03:00, ou a data 2026-11-03, que vale meia-noite UTC).
  • untilstring (date-time) | string (date)opcional
    Só as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until).
  • wamidstringopcional
    O identificador da mensagem na Meta, o mesmo que os eventos de webhook trazem em wamid. Devolve só a mensagem com esse wamid, e a lista vem vazia quando ele não é seu ou não existe.1 a 512 caracteres
  • cursorstringopcional
    até 256 caracteres

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].idstring (uuid)obrigatório
  • data[].directionstringobrigatório
  • data[].wamidstring | nullobrigatório
  • data[].typestring | nullobrigatório
    O tipo da mensagem: text, image, template e os demais. Nulo só em mensagem enviada antes de a plataforma passar a gravar o tipo na saída.
  • data[].bodyTextstring | nullobrigatório
    O texto da mensagem. Em mensagem enviada, só vem preenchido quando ela é do tipo text: para os outros tipos o corpo não é reescrito como texto e o campo é nulo.
  • data[].contentobject | nullobrigatório
    O que a mensagem carrega além do texto, nos dois sentidos. Recebida: mídia com legenda, botão ou item clicado, localização, contatos, reação, citação, anúncio de origem e nome de perfil, com os nomes de campo da Meta, os mesmos do evento message.received. Enviada: o que você mandou, de volta: template (nome, idioma e valores das variáveis), sent_interactive (corpo, botões ou itens, endereço do botão de URL), media (legenda e nome do arquivo, sem o link), location, reaction, contacts e context. Nulo em mensagem de texto enviada (o texto está em bodyText), e em mensagem anterior à plataforma guardar o conteúdo.
  • data[].content.profile_namestring | nullobrigatório
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • data[].content.mediaobject | nullobrigatório
    O arquivo que o interlocutor mandou. O tipo (imagem, vídeo, áudio, documento, figurinha) está em type. Os bytes saem por GET /v1/messages/{id}/media, e o identificador e a URL da Meta não são entregues: você não tem o token que os abre.
  • data[].content.media.mime_typestring | nullobrigatório
    O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu.
  • data[].content.media.sha256string | nullobrigatório
    O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type.
  • data[].content.media.captionstring | nullobrigatório
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • data[].content.media.filenamestring | nullobrigatório
    O nome do arquivo. Só documento tem.
  • data[].content.media.voiceboolean | nullobrigatório
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • data[].content.media.animatedboolean | nullobrigatório
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • data[].content.interactiveobject | nullobrigatório
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • data[].content.interactive.typestring | nullobrigatório
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • data[].content.interactive.idstring | nullobrigatório
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • data[].content.interactive.titlestring | nullobrigatório
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • data[].content.interactive.descriptionstring | nullobrigatório
    A descrição do item da lista. Nula nos demais.
  • data[].content.interactive.namestring | nullobrigatório
    O nome do Flow. Só em nfm_reply.
  • data[].content.interactive.response_jsonstring | nullobrigatório
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • data[].content.buttonobject | nullobrigatório
    O clique num botão de resposta rápida de um template.
  • data[].content.button.payloadstring | nullobrigatório
    O payload que você definiu no botão de resposta rápida do template.
  • data[].content.button.textstring | nullobrigatório
    O texto do botão.
  • data[].content.locationobject | nullobrigatório
    A localização que o interlocutor compartilhou.
  • data[].content.location.latitudenumber | nullobrigatório
    A latitude, em graus decimais.
  • data[].content.location.longitudenumber | nullobrigatório
    A longitude, em graus decimais.
  • data[].content.location.namestring | nullobrigatório
    O nome do lugar, quando o interlocutor escolheu um.
  • data[].content.location.addressstring | nullobrigatório
    O endereço, quando há.
  • data[].content.location.urlstring | nullobrigatório
    O endereço web do lugar, quando há.
  • data[].content.contactsarray<object> | nullobrigatório
    Os cartões de contato que o interlocutor compartilhou.
  • data[].content.contacts[].nameobject | nullobrigatório
    O nome do contato, nos campos da Meta.
  • data[].content.contacts[].name.formatted_namestring | nullobrigatório
  • data[].content.contacts[].name.first_namestring | nullobrigatório
  • data[].content.contacts[].name.last_namestring | nullobrigatório
  • data[].content.contacts[].name.middle_namestring | nullobrigatório
  • data[].content.contacts[].name.prefixstring | nullobrigatório
  • data[].content.contacts[].name.suffixstring | nullobrigatório
  • data[].content.contacts[].phonesarray<object> | nullobrigatório
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • data[].content.contacts[].phones[].phonestring | nullobrigatório
  • data[].content.contacts[].phones[].wa_idstring | nullobrigatório
  • data[].content.contacts[].phones[].typestring | nullobrigatório
  • data[].content.contacts[].emailsarray<object> | nullobrigatório
    Os e-mails do contato.
  • data[].content.contacts[].emails[].emailstring | nullobrigatório
  • data[].content.contacts[].emails[].typestring | nullobrigatório
  • data[].content.contacts[].orgobject | nullobrigatório
    A organização do contato.
  • data[].content.contacts[].org.companystring | nullobrigatório
  • data[].content.contacts[].org.departmentstring | nullobrigatório
  • data[].content.contacts[].org.titlestring | nullobrigatório
  • data[].content.reactionobject | nullobrigatório
    A reação a uma mensagem, ou a retirada dela.
  • data[].content.reaction.wamidstring | nullobrigatório
    O wamid da mensagem que recebeu a reação.
  • data[].content.reaction.emojistring | nullobrigatório
    O emoji. Nulo quando o interlocutor retirou a reação.
  • data[].content.contextobject | nullobrigatório
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • data[].content.context.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor citou ao responder.
  • data[].content.context.fromstring | nullobrigatório
    Quem enviou a mensagem citada.
  • data[].content.context.forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada.
  • data[].content.context.frequently_forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • data[].content.referralobject | nullobrigatório
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • data[].content.referral.source_typestring | nullobrigatório
    A origem do clique, como ad ou post.
  • data[].content.referral.source_idstring | nullobrigatório
    O identificador do anúncio ou da publicação na Meta.
  • data[].content.referral.source_urlstring | nullobrigatório
    O endereço do anúncio ou da publicação.
  • data[].content.referral.headlinestring | nullobrigatório
    O título do anúncio.
  • data[].content.referral.bodystring | nullobrigatório
    O texto do anúncio.
  • data[].content.referral.media_typestring | nullobrigatório
    O tipo da mídia do anúncio, como image ou video.
  • data[].content.referral.ctwa_clidstring | nullobrigatório
    O identificador do clique, para atribuição de conversão.
  • data[].content.unsupportedobject | nullobrigatório
    Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso".
  • data[].content.unsupported.codeinteger | nullobrigatório
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • data[].content.unsupported.titlestring | nullobrigatório
    O título do erro, como a Meta o mandou.
  • data[].content.unsupported.detailsstring | nullobrigatório
    O detalhe do erro, como a Meta o mandou.
  • data[].content.editobject | nullobrigatório
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • data[].content.edit.wamidstring | nullobrigatório
    O wamid da mensagem que foi editada.
  • data[].content.edit.typestring | nullobrigatório
    O tipo do conteúdo novo, como text.
  • data[].content.edit.textstring | nullobrigatório
    O texto novo, quando o conteúdo novo é texto.
  • data[].content.revokeobject | nullobrigatório
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • data[].content.revoke.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor apagou para todos.
  • data[].content.orderobject | nullobrigatório
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • data[].content.order.catalog_idstring | nullobrigatório
    O catálogo de onde veio o pedido.
  • data[].content.order.textstring | nullobrigatório
    O texto que o interlocutor escreveu junto com o pedido.
  • data[].content.order.itemsarray<object> | nullobrigatório
    Os itens do pedido.
  • data[].content.order.items[].product_retailer_idstring | nullobrigatório
    O identificador do produto no seu catálogo.
  • data[].content.order.items[].quantitystring | nullobrigatório
    A quantidade pedida, como a Meta mandou.
  • data[].content.order.items[].item_pricestring | nullobrigatório
    O preço unitário, como a Meta mandou.
  • data[].content.order.items[].currencystring | nullobrigatório
    A moeda do preço.
  • data[].content.templateobject | nullobrigatório
    O template que você enviou, com os valores que preencheram as variáveis.
  • data[].content.template.namestring | nullobrigatório
    O nome do template que você enviou.
  • data[].content.template.languagestring | nullobrigatório
    O idioma do template, no código da Meta (por exemplo pt_BR).
  • data[].content.template.variablesarray<object> | nullobrigatório
    Os valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.
  • data[].content.template.variables[].componentstringobrigatório
    Onde a variável entra: header, body ou button.
  • data[].content.template.variables[].namestring | nullobrigatório
    O nome da variável, quando o template usa variáveis nomeadas. Nulo nas posicionais, em que a ordem na lista é a posição.
  • data[].content.template.variables[].valuestringobrigatório
    O valor que você mandou. Parâmetro de imagem, vídeo ou documento não aparece: o link do arquivo não é devolvido.
  • data[].content.sent_interactiveobject | nullobrigatório
    A mensagem interativa que você enviou: o texto, os botões ou itens que o seu cliente viu, e o endereço do botão de URL.
  • data[].content.sent_interactive.typestring | nullobrigatório
    O tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.
  • data[].content.sent_interactive.headerstring | nullobrigatório
    O texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.
  • data[].content.sent_interactive.bodystring | nullobrigatório
    O texto do corpo.
  • data[].content.sent_interactive.footerstring | nullobrigatório
    O texto do rodapé.
  • data[].content.sent_interactive.buttonsarray<object> | nullobrigatório
    Os botões de resposta (id e título). Só em type button.
  • data[].content.sent_interactive.buttons[].idstring | nullobrigatório
  • data[].content.sent_interactive.buttons[].titlestring | nullobrigatório
  • data[].content.sent_interactive.itemsarray<object> | nullobrigatório
    Os itens da lista, de todas as seções (id, título e descrição). Só em type list.
  • data[].content.sent_interactive.items[].idstring | nullobrigatório
  • data[].content.sent_interactive.items[].titlestring | nullobrigatório
  • data[].content.sent_interactive.items[].descriptionstring | nullobrigatório
  • data[].content.sent_interactive.ctaobject | nullobrigatório
    O botão de chamada: o rótulo e, no cta_url, o endereço que ele abre. No flow, só o rótulo.
  • data[].content.sent_interactive.cta.textstring | nullobrigatório
  • data[].content.sent_interactive.cta.urlstring | nullobrigatório
  • data[].content.sent_interactive.catalog_idstring | nullobrigatório
    O catálogo de onde vêm os produtos. Só em type product e product_list.
  • data[].content.sent_interactive.productsarray<object> | nullobrigatório
    Os produtos enviados, com o título da seção a que pertencem (nulo no product, que não tem seção). Só em type product e product_list.
  • data[].content.sent_interactive.products[].sectionstring | nullobrigatório
  • data[].content.sent_interactive.products[].product_retailer_idstring | nullobrigatório
  • data[].callbackDatastring | nullobrigatório
    A etiqueta que você mandou em callbackData ao enviar a mensagem (de 1 a 512 caracteres), devolvida como veio. Nulo quando o envio não trouxe etiqueta e em mensagem recebida.
  • data[].statusstring | nullobrigatório
  • data[].pricingobject | nullobrigatório
    O custo que a Meta aplicou à mensagem enviada, com os nomes dela: type e category juntos. Nulo enquanto a Meta não o informou, e em mensagem recebida. Não é a fatura da Meta.
  • data[].pricing.billableboolean | nullobrigatório
    Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.
  • data[].pricing.pricing_modelstring | nullobrigatório
    O modelo de preço da Meta, como ela informou (hoje PMP ou CBP).
  • data[].pricing.typestring | nullobrigatório
    O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.
  • data[].pricing.categorystring | nullobrigatório
    A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.
  • data[].waIdstring | nullobrigatório
    O telefone do interlocutor (wa_id da Meta). Nulo quando a mensagem não tem conversa resolvida e quando o interlocutor escreveu só com BSUID, caso em que userId o identifica.
  • data[].userIdstring | nullobrigatório
    O BSUID do interlocutor, como a Meta o mandou. Nulo quando a Meta nunca o mandou para esta conversa.
  • data[].parentUserIdstring | nullobrigatório
    O BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais.
  • data[].usernamestring | nullobrigatório
    O nome de usuário do interlocutor, quando ele adotou um. Nulo no demais.
  • data[].displayNumberstring | nullobrigatório
  • data[].numberIdstring (uuid) | nullobrigatório
    O número da Luna por onde a mensagem passou, o mesmo id de GET /v1/numbers. Nulo quando a mensagem não tem número resolvido.
  • data[].externalIdstring | nullobrigatório
    O seu rótulo para o cliente dono do número (externalId do número). Nulo quando o número não tem rótulo.
  • data[].conversationIdstring (uuid) | nullobrigatório
    A conversa da mensagem, o mesmo id de GET /v1/conversations. Nulo quando não há conversa resolvida.
  • data[].errorSummaryobject | nullobrigatório
    Por que a mensagem falhou, quando falhou: o último erro, na mesma taxonomia de GET /v1/messages/{id}, sem o corpo original da Meta (ele continua só no detalhe, em erros). Nulo quando a mensagem não teve erro.
  • data[].errorSummary.codigonumber | nullobrigatório
    O código do erro da Meta, quando ela mandou um.
  • data[].errorSummary.mensagemstringobrigatório
    O que aconteceu, em português.
  • data[].errorSummary.acaoRecomendadastringobrigatório
    O que fazer a respeito, em português.
  • data[].createdAtstringobrigatório
  • nextCursorstring | nullobrigatório
    Mande 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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
messages:write

Corpo da requisição

application/json · obrigatório

O corpo é uma destas formas (escolha uma):

Forma 1: type = "text"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringopcional
    Sempre 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: text
  • textobjectobrigatório
  • text.bodystringobrigatório
    O texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API.1 a 4096 caracteres
  • text.preview_urlbooleanopcional
    Se a Meta deve buscar a primeira URL do texto para montar uma prévia. Desligado por padrão: ligado, ele dispara uma requisição de saída a partir de conteúdo que o negócio final escreveu, com latência e comportamento que não são da plataforma.
Forma 2: type = "image"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre image.Valores: image
  • imageobjectobrigatório
  • image.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • image.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • image.captionstringopcional
    A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.até 1024 caracteres
Forma 3: type = "video"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre video.Valores: video
  • videoobjectobrigatório
  • video.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • video.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • video.captionstringopcional
    A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.até 1024 caracteres
Forma 4: type = "audio"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre audio.Valores: audio
  • audioobjectobrigatório
  • audio.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • audio.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • audio.voicebooleanopcional
    true para enviar como mensagem de voz (a bolinha de áudio do WhatsApp, com a forma de onda), e não como arquivo de áudio. A Meta exige um arquivo .ogg com codec OPUS, e a Luna não converte áudio: com link, um arquivo de outro tipo reconhecido (por exemplo .mp3) é recusado com 400. Com id, a Luna não vê o tipo do arquivo, e a conferência é da Meta.
Forma 5: type = "document"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre document.Valores: document
  • documentobjectobrigatório
  • document.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • document.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • document.captionstringopcional
    A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.até 1024 caracteres
  • document.filenamestringopcional
    O 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ório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre sticker.Valores: sticker
  • stickerobjectobrigatório
  • sticker.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • sticker.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
Forma 7: type = "location"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre location.Valores: location
  • locationobjectobrigatório
  • location.latitudenumberobrigatório
    A latitude em graus decimais, entre -90 e 90.mínimo -90 · máximo 90
  • location.longitudenumberobrigatório
    A longitude em graus decimais, entre -180 e 180.mínimo -180 · máximo 180
  • location.namestringopcional
    O nome do lugar, exibido acima do endereço.até 1000 caracteres
  • location.addressstringopcional
    O endereço do lugar, exibido abaixo do nome.até 1000 caracteres
Forma 8: type = "contacts"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre contacts.Valores: contacts
  • contactsarray<object>obrigatório
    Os cartões de contato a enviar. Ao menos um, no máximo vinte.1 a 20 itens
  • contacts[].nameobjectobrigatório
  • contacts[].name.formatted_namestringobrigatório
    O nome como ele aparece no cartão.1 a 512 caracteres
  • contacts[].name.first_namestringopcional
    O primeiro nome.até 256 caracteres
  • contacts[].name.last_namestringopcional
    O sobrenome.até 256 caracteres
  • contacts[].name.middle_namestringopcional
    O nome do meio.até 256 caracteres
  • contacts[].name.prefixstringopcional
    O prefixo, como Dr. ou Sra.até 64 caracteres
  • contacts[].name.suffixstringopcional
    O sufixo, como Jr. ou Neto.até 64 caracteres
  • contacts[].birthdaystringopcional
    A data de nascimento em AAAA-MM-DD./^\d{4}-\d{2}-\d{2}$/
  • contacts[].orgobjectopcional
    Os dados profissionais do contato.
  • contacts[].org.companystringopcional
    A empresa.até 256 caracteres
  • contacts[].org.departmentstringopcional
    O departamento.até 256 caracteres
  • contacts[].org.titlestringopcional
    O cargo.até 256 caracteres
  • contacts[].phonesarray<object>opcional
    Os telefones do contato.até 20 itens
  • contacts[].phones[].phonestringopcional
    O telefone, como ele deve aparecer.até 64 caracteres
  • contacts[].phones[].typestringopcional
    O rótulo do telefone, como CELL ou WORK.até 64 caracteres
  • contacts[].phones[].wa_idstringopcional
    O identificador do contato no WhatsApp, se conhecido.até 64 caracteres
  • contacts[].emailsarray<object>opcional
    Os e-mails do contato.até 20 itens
  • contacts[].emails[].emailstringopcional
    O endereço de e-mail.até 320 caracteres
  • contacts[].emails[].typestringopcional
    O rótulo do e-mail, como HOME ou WORK.até 64 caracteres
  • contacts[].addressesarray<object>opcional
    Os endereços do contato.até 20 itens
  • contacts[].addresses[].streetstringopcional
    O logradouro e o número.até 512 caracteres
  • contacts[].addresses[].citystringopcional
    A cidade.até 256 caracteres
  • contacts[].addresses[].statestringopcional
    O estado.até 256 caracteres
  • contacts[].addresses[].zipstringopcional
    O CEP.até 64 caracteres
  • contacts[].addresses[].countrystringopcional
    O país.até 256 caracteres
  • contacts[].addresses[].country_codestringopcional
    O código do país em duas letras.até 8 caracteres
  • contacts[].addresses[].typestringopcional
    O rótulo do endereço, como HOME ou WORK.até 64 caracteres
  • contacts[].urlsarray<object>opcional
    As páginas do contato.até 20 itens
  • contacts[].urls[].urlstringopcional
    O endereço na web.até 2048 caracteres
  • contacts[].urls[].typestringopcional
    O rótulo da URL, como HOME ou WORK.até 64 caracteres
Forma 9: type = "reaction"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre reaction.Valores: reaction
  • reactionobjectobrigatório
  • reaction.message_idstringobrigatório
    A mensagem que recebe a reação: o wamid que a Meta atribuiu ou o id da Luna (UUID), que a Luna troca pelo wamid. O content da mensagem enviada mostra o wamid.1 a 256 caracteres
  • reaction.emojistringobrigatório
    O emoji da reação. Mande vazio para remover uma reação que já tinha sido posta.até 16 caracteres
Forma 10: type = "interactive"
  • fromstringobrigatório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre interactive.Valores: interactive
  • interactiveobjectobrigatório
    A mensagem interativa: botões de resposta (button), lista de opções (list), botão com URL (cta_url), pedido de localização (location_request_message), pedido de endereço (address_message), carrossel de mídia (carousel), Flow (flow), um produto do catálogo (product) ou uma lista de produtos do catálogo (product_list).
  • interactive.typestringopcional
    Sempre button.Valores: button
  • interactive.headerobjectopcional
    O cabeçalho, exibido acima do corpo.
  • interactive.header.typestringobrigatório
    O que o cabeçalho carrega.Valores: text image video document
  • interactive.header.textstringopcional
    O texto do cabeçalho, quando type é text.até 60 caracteres
  • interactive.header.imageobjectopcional
    A imagem do cabeçalho, quando type é image.
  • interactive.header.image.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • interactive.header.image.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • interactive.header.videoobjectopcional
    O vídeo do cabeçalho, quando type é video.
  • interactive.header.video.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • interactive.header.video.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • interactive.header.documentobjectopcional
    O documento do cabeçalho, quando type é document.
  • interactive.header.document.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • interactive.header.document.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • interactive.header.document.filenamestringopcional
    até 240 caracteres
  • interactive.bodyobjectopcional
    O corpo da mensagem interativa.
  • interactive.body.textstringobrigatório
    O texto do corpo.1 a 1024 caracteres
  • interactive.footerobjectopcional
    O rodapé, exibido abaixo dos botões.
  • interactive.footer.textstringobrigatório
    O texto do rodapé.até 60 caracteres
  • interactive.actionobjectopcional
  • interactive.action.buttonsarray<object>obrigatório
    Os botões de resposta. De um a três, o teto da Cloud API.1 a 3 itens
  • interactive.action.buttons[].typestringobrigatório
    Sempre reply.Valores: reply
  • interactive.action.buttons[].replyobjectobrigatório
  • interactive.action.buttons[].reply.idstringobrigatório
    O identificador que volta no webhook quando o botão é tocado.1 a 256 caracteres
  • interactive.action.buttons[].reply.titlestringobrigatório
    O rótulo do botão. Limite de 20 caracteres.1 a 20 caracteres
  • interactive.action.buttonstringobrigatório
    O rótulo do botão que abre a lista. Limite de 20 caracteres.1 a 20 caracteres
  • interactive.action.sectionsarray<object>obrigatório
    As seções da lista. De uma a dez, o teto da Cloud API.1 a 10 itens
  • interactive.action.sections[].titlestringopcional
    O título da seção.até 24 caracteres
  • interactive.action.sections[].rowsarray<object>obrigatório
    As linhas da seção. De uma a dez.1 a 10 itens
  • interactive.action.sections[].rows[].idstringobrigatório
    O identificador que volta no webhook quando a linha é escolhida.1 a 200 caracteres
  • interactive.action.sections[].rows[].titlestringobrigatório
    O título da linha.1 a 24 caracteres
  • interactive.action.sections[].rows[].descriptionstringopcional
    A descrição da linha.até 72 caracteres
  • interactive.action.namestringopcional
    Sempre cta_url.padrão: "cta_url"Valores: cta_url
  • interactive.action.parametersobjectobrigatório
  • interactive.action.parameters.display_textstringobrigatório
    O rótulo do botão. Limite de 20 caracteres.1 a 20 caracteres
  • interactive.action.parameters.urlstring (uri)obrigatório
    O endereço que o botão abre.até 2048 caracteres
  • interactive.action.parameters.countrystringopcional
    O país do endereço, em duas letras (ISO 3166). O padrão é BR./^[A-Za-z]{2}$/ · padrão: "BR"
  • interactive.action.parameters.valuesobjectopcional
    Os campos do endereço já preenchidos, com os nomes que a Meta define para o país.
  • interactive.action.parameters.saved_addressesarray<object>opcional
    Endereços salvos que o usuário pode escolher, no máximo vinte.até 20 itens
  • interactive.action.parameters.saved_addresses[].idstringobrigatório
    O identificador do endereço salvo.1 a 128 caracteres
  • interactive.action.parameters.saved_addresses[].valueobjectobrigatório
    Os campos do endereço salvo.
  • interactive.action.parameters.validation_errorsobjectopcional
    Mensagens de erro por campo, para quando você devolve o formulário depois de uma validação.
  • interactive.action.cardsarray<object>obrigatório
    Os cartões, de dois a dez.2 a 10 itens
  • interactive.action.cards[].card_indexintegerobrigatório
    A posição do cartão, de 0 a 9. Não repita.mínimo 0 · máximo 9
  • interactive.action.cards[].typestringopcional
    Sempre cta_url.padrão: "cta_url"Valores: cta_url
  • interactive.action.cards[].headerobjectobrigatório
    A mídia do cartão.
  • interactive.action.cards[].header.typestringobrigatório
    O que o cartão mostra.Valores: image video
  • interactive.action.cards[].header.imageobjectopcional
    A imagem do cartão, quando type é image.
  • interactive.action.cards[].header.image.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • interactive.action.cards[].header.image.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • interactive.action.cards[].header.videoobjectopcional
    O vídeo do cartão, quando type é video.
  • interactive.action.cards[].header.video.idstringopcional
    O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias.1 a 128 caracteres
  • interactive.action.cards[].header.video.linkstring (uri)opcional
    A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação.até 2048 caracteres
  • interactive.action.cards[].bodyobjectopcional
    O texto do cartão.
  • interactive.action.cards[].body.textstringobrigatório
    O texto do cartão. Limite de 160 caracteres.1 a 160 caracteres
  • interactive.action.cards[].actionobjectobrigatório
  • interactive.action.cards[].action.namestringopcional
    Sempre cta_url.padrão: "cta_url"Valores: cta_url
  • interactive.action.cards[].action.parametersobjectobrigatório
  • interactive.action.cards[].action.parameters.display_textstringobrigatório
    O rótulo do botão. Limite de 20 caracteres.1 a 20 caracteres
  • interactive.action.cards[].action.parameters.urlstring (uri)obrigatório
    O endereço que o botão abre.até 2048 caracteres
  • interactive.action.parameters.flow_message_versionstringopcional
    A 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_idstringopcional
    O identificador do Flow. Use este OU flow_name.1 a 64 caracteres
  • interactive.action.parameters.flow_namestringopcional
    O nome do Flow. Use este OU flow_id.1 a 200 caracteres
  • interactive.action.parameters.flow_ctastringobrigatório
    O rótulo do botão que abre o Flow. A Meta limita o tamanho (o limite exato está a confirmar na doc da Meta).1 a 40 caracteres
  • interactive.action.parameters.flow_tokenstringopcional
    O que você quer receber de volta na resposta do Flow, para ligá-la a este envio.até 256 caracteres
  • interactive.action.parameters.flow_actionstringopcional
    navigate (padrão da Meta) ou data_exchange.1 a 32 caracteres
  • interactive.action.parameters.flow_action_payloadobjectopcional
    A tela e os dados de abertura, quando flow_action é navigate.
  • interactive.action.parameters.flow_action_payload.screenstringobrigatório
    A tela do Flow que abre primeiro.1 a 200 caracteres
  • interactive.action.parameters.flow_action_payload.dataobjectopcional
    Os dados que o Flow recebe nessa tela.
  • interactive.action.parameters.modestringopcional
    draft para testar um Flow ainda não publicado, ou published (padrão da Meta).1 a 16 caracteres
  • interactive.action.catalog_idstringobrigatório
    O identificador do catálogo na conta de negócio do número (catalog_id da Meta).1 a 64 caracteres
  • interactive.action.product_retailer_idstringobrigatório
    O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta).1 a 256 caracteres
  • interactive.action.sections[].product_itemsarray<object>obrigatório
    Os produtos da seção.1 a 30 itens
  • interactive.action.sections[].product_items[].product_retailer_idstringobrigatório
    O 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ório
    O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • tostringopcional
    O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400./^[1-9]\d{7,14}$/
  • recipientstringopcional
    O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to.
  • contextobjectopcional
    Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar.
  • context.message_idstringobrigatório
    A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar.1 a 256 caracteres
  • callbackDatastringopcional
    Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos.1 a 512 caracteres
  • typingMsintegeropcional
    Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida.mínimo 1 · máximo 25000
  • typestringobrigatório
    Sempre template.Valores: template
  • templateobjectobrigatório
  • template.namestringobrigatório
    O nome do template já aprovado pela Meta.1 a 512 caracteres
  • template.languageobjectobrigatório
  • template.language.codestringobrigatório
    O código do idioma do template, como pt_BR. Ele precisa bater com o aprovado.2 a 16 caracteres
  • template.componentsarray<object>opcional
    Os componentes que preenchem as variáveis do template.até 32 itens
  • template.components[].typestringobrigatório
    Qual parte do template este componente preenche.Valores: header body button
  • template.components[].sub_typestringopcional
    O subtipo, exigido pela Cloud API quando type é button.até 64 caracteres
  • template.components[].indexstringopcional
    A posição do botão, exigida pela Cloud API quando type é button.até 8 caracteres
  • template.components[].parametersarray<object>opcional
    Os 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ório
    O identificador da mensagem na Luna. Ele existe antes de a Meta responder.
  • statusstringobrigatório
    Sempre 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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "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.
Janela de atendimento fechadaJSON
{
  "error": "window_closed",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A janela de atendimento desta conversa está fechada. Só é possível enviar mensagem livre até 24 horas depois da última mensagem do contato.",
  "fechadaEm": "2026-10-06T12:00:00.000Z",
  "acaoRecomendada": "Para falar com este contato agora, envie um template aprovado. A mensagem livre volta a ser aceita quando o contato responder, porque é a resposta dele que abre a janela. Se este contato escreveu há pouco e a janela devia estar aberta, confira o campo to: use o telefone do evento recebido (wa_id).",
  "detalheTecnico": "A Luna já acha a conversa do celular brasileiro com e sem o nono dígito, mas qualquer outra diferença no telefone não encontra a conversa. Se o contato escreveu sem telefone (só com BSUID, o identificador de usuário), envie com recipient igual ao user_id do evento, e não com to."
}
Template que ainda não está aprovadoJSON
{
  "error": "template_not_approved",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "O template lembrete_consulta (pt_BR) está PENDING, e a Meta só entrega template APPROVED. Se está em análise, espere: o evento template.status chega no seu webhook, e GET /v1/templates/{id} mostra o estado atual. Se foi rejeitado, pausado ou desativado, corrija o template (PATCH /v1/templates/{id}) ou crie outro (POST /v1/templates).",
  "templateStatus": "PENDING"
}
Idempotency-Key usada com outro corpoJSON
{
  "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."
}
Número desconectado da LunaJSON
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Fila de envio cheiaJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
messages:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O 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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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.
Não existe, ou não é seuJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Ritmo do númeroJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
messages:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O 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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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.
Não existe, ou não é seuJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Ritmo do númeroJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
messages:read

Parâmetros de caminho

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

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
    O identificador da mensagem na Luna.
  • wamidstring | nullobrigatório
    O identificador da mensagem na Meta, o mesmo que os eventos de webhook trazem em wamid. Use-o para ligar um evento recebido a esta mensagem. Nulo enquanto a Meta ainda não aceitou o envio.
  • contentobject | nullobrigatório
    O que a mensagem carrega além do texto, nos dois sentidos, a mesma forma de content em GET /v1/messages. Na recebida, os nomes de campo da Meta, os mesmos do evento message.received; na enviada, o que você mandou (template, sent_interactive, media sem o link, location, reaction, contacts, context). Nulo em mensagem de texto enviada, e em mensagem recebida antes de a plataforma passar a guardar o conteúdo.
  • content.profile_namestring | nullobrigatório
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • content.mediaobject | nullobrigatório
    O arquivo que o interlocutor mandou. O tipo (imagem, vídeo, áudio, documento, figurinha) está em type. Os bytes saem por GET /v1/messages/{id}/media, e o identificador e a URL da Meta não são entregues: você não tem o token que os abre.
  • content.media.mime_typestring | nullobrigatório
    O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu.
  • content.media.sha256string | nullobrigatório
    O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type.
  • content.media.captionstring | nullobrigatório
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • content.media.filenamestring | nullobrigatório
    O nome do arquivo. Só documento tem.
  • content.media.voiceboolean | nullobrigatório
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • content.media.animatedboolean | nullobrigatório
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • content.interactiveobject | nullobrigatório
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • content.interactive.typestring | nullobrigatório
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • content.interactive.idstring | nullobrigatório
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • content.interactive.titlestring | nullobrigatório
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • content.interactive.descriptionstring | nullobrigatório
    A descrição do item da lista. Nula nos demais.
  • content.interactive.namestring | nullobrigatório
    O nome do Flow. Só em nfm_reply.
  • content.interactive.response_jsonstring | nullobrigatório
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • content.buttonobject | nullobrigatório
    O clique num botão de resposta rápida de um template.
  • content.button.payloadstring | nullobrigatório
    O payload que você definiu no botão de resposta rápida do template.
  • content.button.textstring | nullobrigatório
    O texto do botão.
  • content.locationobject | nullobrigatório
    A localização que o interlocutor compartilhou.
  • content.location.latitudenumber | nullobrigatório
    A latitude, em graus decimais.
  • content.location.longitudenumber | nullobrigatório
    A longitude, em graus decimais.
  • content.location.namestring | nullobrigatório
    O nome do lugar, quando o interlocutor escolheu um.
  • content.location.addressstring | nullobrigatório
    O endereço, quando há.
  • content.location.urlstring | nullobrigatório
    O endereço web do lugar, quando há.
  • content.contactsarray<object> | nullobrigatório
    Os cartões de contato que o interlocutor compartilhou.
  • content.contacts[].nameobject | nullobrigatório
    O nome do contato, nos campos da Meta.
  • content.contacts[].name.formatted_namestring | nullobrigatório
  • content.contacts[].name.first_namestring | nullobrigatório
  • content.contacts[].name.last_namestring | nullobrigatório
  • content.contacts[].name.middle_namestring | nullobrigatório
  • content.contacts[].name.prefixstring | nullobrigatório
  • content.contacts[].name.suffixstring | nullobrigatório
  • content.contacts[].phonesarray<object> | nullobrigatório
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • content.contacts[].phones[].phonestring | nullobrigatório
  • content.contacts[].phones[].wa_idstring | nullobrigatório
  • content.contacts[].phones[].typestring | nullobrigatório
  • content.contacts[].emailsarray<object> | nullobrigatório
    Os e-mails do contato.
  • content.contacts[].emails[].emailstring | nullobrigatório
  • content.contacts[].emails[].typestring | nullobrigatório
  • content.contacts[].orgobject | nullobrigatório
    A organização do contato.
  • content.contacts[].org.companystring | nullobrigatório
  • content.contacts[].org.departmentstring | nullobrigatório
  • content.contacts[].org.titlestring | nullobrigatório
  • content.reactionobject | nullobrigatório
    A reação a uma mensagem, ou a retirada dela.
  • content.reaction.wamidstring | nullobrigatório
    O wamid da mensagem que recebeu a reação.
  • content.reaction.emojistring | nullobrigatório
    O emoji. Nulo quando o interlocutor retirou a reação.
  • content.contextobject | nullobrigatório
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • content.context.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor citou ao responder.
  • content.context.fromstring | nullobrigatório
    Quem enviou a mensagem citada.
  • content.context.forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada.
  • content.context.frequently_forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • content.referralobject | nullobrigatório
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • content.referral.source_typestring | nullobrigatório
    A origem do clique, como ad ou post.
  • content.referral.source_idstring | nullobrigatório
    O identificador do anúncio ou da publicação na Meta.
  • content.referral.source_urlstring | nullobrigatório
    O endereço do anúncio ou da publicação.
  • content.referral.headlinestring | nullobrigatório
    O título do anúncio.
  • content.referral.bodystring | nullobrigatório
    O texto do anúncio.
  • content.referral.media_typestring | nullobrigatório
    O tipo da mídia do anúncio, como image ou video.
  • content.referral.ctwa_clidstring | nullobrigatório
    O identificador do clique, para atribuição de conversão.
  • content.unsupportedobject | nullobrigatório
    Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso".
  • content.unsupported.codeinteger | nullobrigatório
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • content.unsupported.titlestring | nullobrigatório
    O título do erro, como a Meta o mandou.
  • content.unsupported.detailsstring | nullobrigatório
    O detalhe do erro, como a Meta o mandou.
  • content.editobject | nullobrigatório
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • content.edit.wamidstring | nullobrigatório
    O wamid da mensagem que foi editada.
  • content.edit.typestring | nullobrigatório
    O tipo do conteúdo novo, como text.
  • content.edit.textstring | nullobrigatório
    O texto novo, quando o conteúdo novo é texto.
  • content.revokeobject | nullobrigatório
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • content.revoke.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor apagou para todos.
  • content.orderobject | nullobrigatório
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • content.order.catalog_idstring | nullobrigatório
    O catálogo de onde veio o pedido.
  • content.order.textstring | nullobrigatório
    O texto que o interlocutor escreveu junto com o pedido.
  • content.order.itemsarray<object> | nullobrigatório
    Os itens do pedido.
  • content.order.items[].product_retailer_idstring | nullobrigatório
    O identificador do produto no seu catálogo.
  • content.order.items[].quantitystring | nullobrigatório
    A quantidade pedida, como a Meta mandou.
  • content.order.items[].item_pricestring | nullobrigatório
    O preço unitário, como a Meta mandou.
  • content.order.items[].currencystring | nullobrigatório
    A moeda do preço.
  • content.templateobject | nullobrigatório
    O template que você enviou, com os valores que preencheram as variáveis.
  • content.template.namestring | nullobrigatório
    O nome do template que você enviou.
  • content.template.languagestring | nullobrigatório
    O idioma do template, no código da Meta (por exemplo pt_BR).
  • content.template.variablesarray<object> | nullobrigatório
    Os valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum.
  • content.template.variables[].componentstringobrigatório
    Onde a variável entra: header, body ou button.
  • content.template.variables[].namestring | nullobrigatório
    O nome da variável, quando o template usa variáveis nomeadas. Nulo nas posicionais, em que a ordem na lista é a posição.
  • content.template.variables[].valuestringobrigatório
    O valor que você mandou. Parâmetro de imagem, vídeo ou documento não aparece: o link do arquivo não é devolvido.
  • content.sent_interactiveobject | nullobrigatório
    A mensagem interativa que você enviou: o texto, os botões ou itens que o seu cliente viu, e o endereço do botão de URL.
  • content.sent_interactive.typestring | nullobrigatório
    O tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list.
  • content.sent_interactive.headerstring | nullobrigatório
    O texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia.
  • content.sent_interactive.bodystring | nullobrigatório
    O texto do corpo.
  • content.sent_interactive.footerstring | nullobrigatório
    O texto do rodapé.
  • content.sent_interactive.buttonsarray<object> | nullobrigatório
    Os botões de resposta (id e título). Só em type button.
  • content.sent_interactive.buttons[].idstring | nullobrigatório
  • content.sent_interactive.buttons[].titlestring | nullobrigatório
  • content.sent_interactive.itemsarray<object> | nullobrigatório
    Os itens da lista, de todas as seções (id, título e descrição). Só em type list.
  • content.sent_interactive.items[].idstring | nullobrigatório
  • content.sent_interactive.items[].titlestring | nullobrigatório
  • content.sent_interactive.items[].descriptionstring | nullobrigatório
  • content.sent_interactive.ctaobject | nullobrigatório
    O botão de chamada: o rótulo e, no cta_url, o endereço que ele abre. No flow, só o rótulo.
  • content.sent_interactive.cta.textstring | nullobrigatório
  • content.sent_interactive.cta.urlstring | nullobrigatório
  • content.sent_interactive.catalog_idstring | nullobrigatório
    O catálogo de onde vêm os produtos. Só em type product e product_list.
  • content.sent_interactive.productsarray<object> | nullobrigatório
    Os produtos enviados, com o título da seção a que pertencem (nulo no product, que não tem seção). Só em type product e product_list.
  • content.sent_interactive.products[].sectionstring | nullobrigatório
  • content.sent_interactive.products[].product_retailer_idstring | nullobrigatório
  • statusstring | nullobrigatório
    O estado atual da entrega, como a Meta o reportou por último. Nulo quando nenhum evento de status chegou ainda.
  • criadaEmstring | nullobrigatório
    Quando a Luna aceitou a mensagem, em ISO-8601 UTC.
  • enviadaEmstring | nullobrigatório
    Quando a Meta confirmou o envio. Nulo enquanto isso não aconteceu.
  • entregueEmstring | nullobrigatório
    Quando a mensagem chegou ao aparelho do destinatário. Nulo enquanto isso não aconteceu.
  • lidaEmstring | nullobrigatório
    Quando o destinatário leu a mensagem. Nulo enquanto isso não aconteceu, e também quando ele desliga a confirmação de leitura.
  • callbackDatastring | nullobrigatório
    A etiqueta que você mandou em callbackData ao enviar a mensagem (de 1 a 512 caracteres), devolvida como veio. Nulo quando o envio não trouxe etiqueta e em mensagem recebida.
  • pricingobject | nullobrigatório
    O custo que a Meta aplicou a esta mensagem, com os nomes dela: type e category juntos dizem se a Meta cobra e em que categoria. Vem nulo enquanto a Meta não o informou (ela o manda no estado sent e em um entre delivered e read) e em mensagem recebida. Não é a fatura da Meta, e a Luna não calcula valor em dinheiro: a fonte da verdade é o painel de cobrança dela.
  • pricing.billableboolean | nullobrigatório
    Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.
  • pricing.pricing_modelstring | nullobrigatório
    O modelo de preço da Meta, como ela informou (hoje PMP ou CBP).
  • pricing.typestring | nullobrigatório
    O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.
  • pricing.categorystring | nullobrigatório
    A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.
  • errosarray<object>obrigatório
    O que deu errado, em ordem de acontecimento, e vazio quando nada deu. Reúne o que a Meta recusou na hora do envio e o que ela informou depois por evento de status: você não precisa saber de qual das duas veio cada item.
  • erros[].codigointeger | nullobrigatório
    O código de erro da Meta, íntegro. Nulo quando não houve resposta da Meta: um tempo esgotado, por exemplo, não tem código.
  • erros[].categoriastringobrigatório
    A natureza do erro, no vocabulário da Helsen. O valor desconhecido é literal e deliberado: a Meta acrescenta códigos sem aviso, e um código ainda não mapeado chega assim em vez de ser traduzido para uma categoria que não é a dele.Valores: parametro_invalido reauth_required recurso_inacessivel orcamento_management throughput_excedido estado_de_produto janela_de_atendimento midia_indisponivel nao_entregavel template_invalido ritmo_por_destinatario terminal transporte contrato desconhecido
  • erros[].mensagemstringobrigatório
    O que aconteceu, em português. É texto da Helsen, não a tradução da mensagem da Meta.
  • erros[].acaoRecomendadastringobrigatório
    O que fazer a respeito, em português e em uma frase acionável.
  • erros[].originalany | nullobrigatório
    O corpo de erro que a Meta devolveu, sem reescrita e sem filtro. É o que o suporte da Meta reconhece, e o fbtrace_id dentro dele é o que faz um chamado avançar. Atenção: ele pode conter o telefone do consumidor final e trechos da conversa, então trate-o com o mesmo cuidado do restante do conteúdo das mensagens antes de repassá-lo a terceiros. É nulo quando não houve resposta da Meta.
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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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.
Não existe, ou não é seuJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
messages:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O 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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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.
Não existe, ou não é seuJSON
{
  "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.
Mensagem que já saiu da filaJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O 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ório
    O identificador desta entrega. Cada pedido gera um novo: o reenvio é entrega nova, e não reescrita de histórico.
  • requestedAtstringobrigatório
    Quando 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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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.
Não existe, ou não é seuJSON
{
  "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.
Sem endpoint de webhook ativoJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "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.
IndisponívelJSON
{
  "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.

Autenticação
Chave de API
Escopo exigido
messages:write

Corpo da requisição

application/json · obrigatório

  • phoneNumberIdstringopcional
    O 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_-]+$/
  • waIdstringopcional
    O telefone de quem "escreveu", só dígitos. Ausente, 5511900000000./^[1-9]\d{7,14}$/
  • textstringopcional
    O 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ório
    O id da mensagem simulada, o mesmo que vai em message.id do evento.
  • wamidstringobrigatório
    O wamid simulado. Começa com wamid.TESTE_ para nunca se confundir com um da Meta.
  • endpointsintegerobrigatório
    Quantos dos seus endpoints de webhook vão receber o evento: os ativos, sem filtro de cliente ou de número, que aceitam message.received. Zero quer dizer que nada vai chegar: cadastre um endpoint.
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.
Campo recusado, com o motivoJSON
{
  "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-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "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.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "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-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "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.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}