{"openapi":"3.1.0","info":{"title":"Luna: WhatsApp messaging API","version":"1.0.0","description":"Luna delivers WhatsApp to software companies that need to talk to their own customers.\nIt is built on top of the **official WhatsApp Cloud API from Meta**, and Helsen operates\nas an approved Tech Provider. No unofficial library takes part in the path, under any\ncircumstance.\n\n[Leia esta documentação em português](https://lunahia.com.br/docs/referencia)\n\n## What this API does for you\n\nConnect an end customer's WhatsApp, receive everything that arrives on that number, and\nsend messages back. The connection happens in a Meta window that only opens on the domain\nof Luna's console: inside the console, or on a page Luna hosts and that you send to your\ncustomer as a connect link. The intelligence of the conversation is yours. What Luna\ndelivers is the messaging infrastructure underneath it.\n\n## Authentication\n\nEvery integration route requires an API key in the `Authorization` header, in the form `Bearer hlsn_...`.\nKeys carry **scopes**: each route demands its own, and a key without the right scope gets a\n403. Create and revoke keys from the console, under Integration and then Keys.\n\nThe key is shown **once**, at the moment it is created. No route returns it afterwards:\nLuna stores only a cryptographic digest.\n\n## Sending is asynchronous, and that is a contract\n\nSending a message returns 202, not 200. Luna accepts it, queues it, and delivers it to Meta\nat the pace Meta allows. This exists because the tightest limit is **one message every six\nseconds to the same recipient**. An agent that answers in bursts trips it on its own, and the\nright answer to that is a queue, never an error handed back to you.\n\n## Errors\n\nEvery error returns a JSON body with `error` and `message`. 404 is also used for a resource\nthat exists but is not yours, because the API does not confirm the existence of another\ncustomer's resource, not even through the status code.\n\nA validation refusal (`400`, `invalid_request`) carries `campos`, a list where each item has\nthe refused `campo` and the `motivo` in one short sentence (in Portuguese). The value you sent\nnever comes back in the response. Each operation lists the errors it can return, and each\nerror body has an example.\n\n## Webhook events\n\nWhat Luna delivers to your endpoint is in the Webhooks and events group of this specification: each\nevent type with its body schema, the signature header and the delivery guarantees.\n\n## Limits\n\nThere is a request limit per API key. It is technical, identical for every customer, and\ndocumented. No limit on this platform varies with price.","contact":{"name":"Suporte Luna","email":"ia.helsenservice@gmail.com"}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Chave de API do tenant"}},"schemas":{"Erro":{"type":"object","properties":{"error":{"type":"string","description":"The error code. It is stable: decide by it and by the status, never by the text of message."},"message":{"type":"string","description":"Text for a person to read, in Portuguese."},"docsUrl":{"description":"The site guide that explains this error. It is always filled in today, and may be null in the future for a code with no guide: in that case, ignore it.","anyOf":[{"type":"string"},{"type":"null"}]},"fechadaEm":{"description":"window_closed: when the service window closed, or null if it never opened.","anyOf":[{"type":"string"},{"type":"null"}]},"acaoRecomendada":{"description":"window_closed: what to do. It includes checking that to is the phone of the received event (wa_id), because Luna finds a Brazilian mobile with and without the ninth digit but no other difference, and using recipient with the user_id of the event when the contact wrote without a phone number.","type":"string"},"detalheTecnico":{"description":"window_closed: the detail for whoever already checked to and the window is still closed (ninth digit, BSUID and recipient). The everyday action is in acaoRecomendada.","type":"string"},"requiredScope":{"description":"forbidden: the scope the key needs for this operation, for example numbers:read.","type":"string"},"campos":{"description":"not_found: when the missing resource is pointed to by the body (for example from), the field that pointed to it.","type":"array","items":{"type":"object","properties":{"campo":{"type":"string"},"motivo":{"type":"string"}},"required":["campo","motivo"],"additionalProperties":false}},"templateStatus":{"description":"template_not_approved: the template state at Meta (PENDING, REJECTED, PAUSED...). Only APPROVED sends.","type":"string"},"estado":{"description":"media_not_ready: where the media stands (pendente, falhou or expirado).","type":"string"},"faltando":{"description":"connection_not_released: the conditions that are missing.","type":"array","items":{"type":"string"}},"tentativasRestantes":{"description":"register_budget_reserved: how many registration attempts are left.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"janelaVira":{"description":"register_budget_reserved: when the 72-hour window rolls over.","type":"string"},"reenfileiradoEm":{"description":"already_requeued: when the item was requeued.","type":"string"},"credentialStatus":{"description":"reconnect_not_applicable: the state of the authorization.","type":"string"},"limit":{"description":"webhook_endpoint_limit: the maximum number of endpoints per customer.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"capacity":{"description":"number_capacity_reached: how many numbers the account can keep active.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"activeNumbers":{"description":"number_capacity_reached: how many numbers are active right now.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["error","message"],"additionalProperties":{},"example":{"error":"not_found","message":"Recurso não encontrado.","docsUrl":"https://lunahia.com.br/docs/erros"},"description":"The body of every API error: error and message, plus the extra fields that say what to do in each case."},"ErroDeValidacao":{"type":"object","properties":{"error":{"type":"string","const":"invalid_request"},"message":{"type":"string","description":"Text for a person to read, in Portuguese."},"docsUrl":{"description":"The site guide that explains this error.","anyOf":[{"type":"string"},{"type":"null"}]},"campos":{"description":"One item per refused field. Absent when the body is not even readable JSON.","type":"array","items":{"type":"object","properties":{"campo":{"type":"string","description":"The path of the refused field, for example text.body."},"motivo":{"type":"string","description":"A short sentence, in Portuguese, saying why the field was refused. The value you sent never comes back."}},"required":["campo","motivo"],"additionalProperties":false}}},"required":["error","message"],"additionalProperties":false,"example":{"error":"invalid_request","message":"Requisição inválida.","docsUrl":"https://lunahia.com.br/docs/erros","campos":[{"campo":"text.body","motivo":"Não pode ficar vazio."}]},"description":"The body of the validation 400: campos lists each refused field with the reason."},"EventoDeFanout":{"oneOf":[{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"message.received"},"message":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem."},"wamid":{"type":"string","minLength":1,"description":"O identificador da mensagem na Meta."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador do interlocutor na Meta, em E.164 sem o sinal de mais: o telefone. Nulo quando o usuário escreveu sem que o telefone apareça (nome de usuário adotado): use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais."},"type":{"type":"string","minLength":1,"description":"O tipo da mensagem, no vocabulário da Meta."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title."},"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou."},"media":{"anyOf":[{"type":"object","properties":{"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do arquivo. Só documento tem."},"voice":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem."},"animated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a figurinha é animada. Só figurinha tem."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo."}},"required":["mime_type","sha256","caption","filename","voice","animated","url"],"additionalProperties":false},{"type":"null"}]},"interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow)."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do item da lista. Nula nos demais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do Flow. Só em nfm_reply."},"response_json":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply."}},"required":["type","id","title","description","name","response_json"],"additionalProperties":false,"description":"A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu."},{"type":"null"}]},"button":{"anyOf":[{"type":"object","properties":{"payload":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O payload que você definiu no botão de resposta rápida do template."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do botão."}},"required":["payload","text"],"additionalProperties":false,"description":"O clique num botão de resposta rápida de um template."},{"type":"null"}]},"location":{"anyOf":[{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A latitude, em graus decimais."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A longitude, em graus decimais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do lugar, quando o interlocutor escolheu um."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço, quando há."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço web do lugar, quando há."}},"required":["latitude","longitude","name","address","url"],"additionalProperties":false,"description":"A localização que o interlocutor compartilhou."},{"type":"null"}]},"contacts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"object","properties":{"formatted_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["formatted_name","first_name","last_name","middle_name","prefix","suffix"],"additionalProperties":false},{"type":"null"}],"description":"O nome do contato, nos campos da Meta."},"phones":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"wa_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","wa_id","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp."},"emails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os e-mails do contato."},"org":{"anyOf":[{"type":"object","properties":{"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"department":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["company","department","title"],"additionalProperties":false},{"type":"null"}],"description":"A organização do contato."}},"required":["name","phones","emails","org"],"additionalProperties":false}},{"type":"null"}],"description":"Os cartões de contato que o interlocutor compartilhou."},"reaction":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que recebeu a reação."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O emoji. Nulo quando o interlocutor retirou a reação."}},"required":["wamid","emoji"],"additionalProperties":false,"description":"A reação a uma mensagem, ou a retirada dela."},{"type":"null"}]},"context":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor citou ao responder."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem enviou a mensagem citada."},"forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada."},"frequently_forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada muitas vezes."}},"required":["wamid","from","forwarded","frequently_forwarded"],"additionalProperties":false,"description":"A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada."},{"type":"null"}]},"referral":{"anyOf":[{"type":"object","properties":{"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A origem do clique, como ad ou post."},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do anúncio ou da publicação na Meta."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do anúncio ou da publicação."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do anúncio."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do anúncio."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mídia do anúncio, como image ou video."},"ctwa_clid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do clique, para atribuição de conversão."}},"required":["source_type","source_id","source_url","headline","body","media_type","ctwa_clid"],"additionalProperties":false,"description":"O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever."},{"type":"null"}]},"unsupported":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta, como ela mandou (131051 é \"tipo de mensagem sem suporte\")."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o mandou."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O detalhe do erro, como a Meta o mandou."}},"required":["code","title","details"],"additionalProperties":false,"description":"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\"."},{"type":"null"}]},"edit":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que foi editada."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do conteúdo novo, como text."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto novo, quando o conteúdo novo é texto."}},"required":["wamid","type","text"],"additionalProperties":false,"description":"Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit)."},{"type":"null"}]},"revoke":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor apagou para todos."}},"required":["wamid"],"additionalProperties":false,"description":"Presente quando o interlocutor apagou uma mensagem para todos (type é revoke)."},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde veio o pedido."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto que o interlocutor escreveu junto com o pedido."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do produto no seu catálogo."},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A quantidade pedida, como a Meta mandou."},"item_price":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O preço unitário, como a Meta mandou."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda do preço."}},"required":["product_retailer_id","quantity","item_price","currency"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens do pedido."}},"required":["catalog_id","text","items"],"additionalProperties":false,"description":"O pedido que o interlocutor montou num catálogo e enviou (type é order)."},{"type":"null"}]}},"required":["id","wamid","wa_id","user_id","parent_user_id","username","type","text","profile_name","media","interactive","button","location","contacts","reaction","context","referral","unsupported","edit","revoke","order"],"additionalProperties":false,"description":"Uma mensagem que chegou de um interlocutor. Além de wamid, wa_id (que pode ser nulo), user_id, parent_user_id, username, type e text, ela traz o conteúdo que o tipo carrega (mídia, botão ou item clicado, resposta de Flow, localização, contatos, reação, pedido, edição, apagamento, aviso de tipo sem suporte), a citação, o anúncio de origem e o nome de perfil. Os nomes dentro desses campos são os da Meta. Todo campo está sempre presente, e é nulo quando não se aplica."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","message"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"message.status"},"message":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O identificador da mensagem na Luna, o mesmo que POST /v1/messages devolveu quando você a enviou. Nulo quando o status é de uma mensagem que a Luna não conhece."},"wamid":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador da mensagem na Meta. Nulo quando a Meta recusou o envio antes de aceitar a mensagem, caso em que ela nunca teve identificador: use id para correlacionar."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais."},"status":{"type":"string","minLength":1,"description":"O estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer."},"error_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta quando o estado é de falha. Nulo nos demais."},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código do erro, como a Meta o informou."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o informou."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do erro, como a Meta a informou."}},"required":["code","title","message"],"additionalProperties":false},{"type":"null"}],"description":"O primeiro erro que a Meta informou quando o estado é de falha, com code, title e message. Nulo nos demais estados. O detalhe completo, com a causa e a ação recomendada, está em GET /v1/messages/{id}."},"pricing":{"anyOf":[{"type":"object","properties":{"billable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos."},"pricing_model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O modelo de preço da Meta, como ela informou (hoje PMP ou CBP)."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer."}},"required":["billable","pricing_model","type","category"],"additionalProperties":false},{"type":"null"}],"description":"O custo que a Meta aplicou à mensagem. A Meta o informa só no estado sent e em um entre delivered e read, então nos demais estados vem nulo. Não é a fatura da Meta: a fonte da verdade é o painel de cobrança dela."},"callback_data":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A etiqueta que você mandou em callbackData ao enviar a mensagem, devolvida como veio. Nulo quando o envio não trouxe etiqueta. Está em todos os estados da mensagem, inclusive failed."}},"required":["id","wamid","wa_id","user_id","parent_user_id","username","status","error_code","error","pricing","callback_data"],"additionalProperties":false,"description":"Uma mudança de estado de uma mensagem que você enviou."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","message"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"contact.identity_changed"},"contact":{"type":"object","properties":{"wamid":{"type":"string","minLength":1,"description":"O identificador, na Meta, da mensagem de sistema que avisou a troca."},"change_type":{"type":"string","minLength":1,"description":"O que mudou, como a Meta informou: user_changed_number (o telefone) ou user_changed_user_id (o BSUID). Novos valores podem aparecer."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário)."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do contato depois da troca, como a Meta mandou."},"previous_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do contato depois da troca, quando a Meta o informa."},"previous_parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai de antes da troca, quando a Meta o informa."}},"required":["wamid","change_type","wa_id","user_id","previous_user_id","parent_user_id","previous_parent_user_id"],"additionalProperties":false,"description":"O contato trocou de telefone ou de BSUID. A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro. Todo campo está sempre presente, e é nulo quando não se aplica."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","contact"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"contact.preferences_changed"},"contact":{"type":"object","properties":{"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário): use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do contato, como a Meta mandou."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do contato, quando a Meta o informa."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do contato, quando ele adotou um."},"profile_name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome que o contato exibe no WhatsApp, quando a Meta o manda."}},"required":["wa_id","user_id","parent_user_id","username","profile_name"],"additionalProperties":false,"description":"Quem mudou a preferência."},"preference":{"type":"object","properties":{"category":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer."},"value":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer."},"detail":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O texto que a Meta mandou para explicar a mudança."}},"required":["category","value","detail"],"additionalProperties":false,"description":"O que mudou."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","contact","preference"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"backlog.dropped"},"backlog":{"type":"object","properties":{"motivo":{"type":"string","enum":["idade","volume"],"description":"Qual limite foi atingido: idade, quando as mensagens ficaram velhas demais para serem acionáveis; volume, quando o acumulado deste endpoint passou do teto da plataforma."},"quantidade":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Quantos eventos foram descartados nesta ocorrência."},"janela_inicio":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"O evento mais antigo descartado nesta ocorrência."},"janela_fim":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"O evento mais recente descartado nesta ocorrência."}},"required":["motivo","quantidade","janela_inicio","janela_fim"],"additionalProperties":false,"description":"Eventos que a plataforma descartou sem entregar, e que não serão reenviados."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","backlog"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"history_sync.deadline_approaching"},"history_sync":{"type":"object","properties":{"prazo":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Até quando a importação precisa terminar, em UTC. É o mesmo instante que sincronizacaoPrazo devolve na rota de saúde do número."}},"required":["prazo"],"additionalProperties":false,"description":"A importação das conversas anteriores de um número em coexistência está em curso e o prazo dela se aproxima. O estado corrente, inclusive o progresso, está em GET /v1/numbers/{id}/health."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","history_sync"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o evento de teste não passa por nenhum número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"webhook.test"},"webhook_test":{"type":"object","properties":{"endpoint_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu."}},"required":["endpoint_id"],"additionalProperties":false,"description":"Um evento de teste, enviado porque você pediu em POST /v1/webhooks/endpoints/{id}/test. Ele nunca aparece se você não pediu, não tem número nem conversa, e serve para conferir a URL e a verificação da assinatura."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","webhook_test"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"message.echo"},"message":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem."},"wamid":{"type":"string","minLength":1,"description":"O identificador da mensagem na Meta."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador do DESTINATÁRIO na Meta, em E.164 sem o sinal de mais: o cliente final para quem o dono do negócio escreveu. É a conversa onde o seu agente deve ficar quieto. Nulo quando a conversa é só de BSUID: use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais."},"type":{"type":"string","minLength":1,"description":"O tipo da mensagem, no vocabulário da Meta."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title."},"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou."},"media":{"anyOf":[{"type":"object","properties":{"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do arquivo. Só documento tem."},"voice":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem."},"animated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a figurinha é animada. Só figurinha tem."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo."}},"required":["mime_type","sha256","caption","filename","voice","animated","url"],"additionalProperties":false},{"type":"null"}]},"interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow)."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do item da lista. Nula nos demais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do Flow. Só em nfm_reply."},"response_json":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply."}},"required":["type","id","title","description","name","response_json"],"additionalProperties":false,"description":"A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu."},{"type":"null"}]},"button":{"anyOf":[{"type":"object","properties":{"payload":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O payload que você definiu no botão de resposta rápida do template."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do botão."}},"required":["payload","text"],"additionalProperties":false,"description":"O clique num botão de resposta rápida de um template."},{"type":"null"}]},"location":{"anyOf":[{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A latitude, em graus decimais."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A longitude, em graus decimais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do lugar, quando o interlocutor escolheu um."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço, quando há."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço web do lugar, quando há."}},"required":["latitude","longitude","name","address","url"],"additionalProperties":false,"description":"A localização que o interlocutor compartilhou."},{"type":"null"}]},"contacts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"object","properties":{"formatted_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["formatted_name","first_name","last_name","middle_name","prefix","suffix"],"additionalProperties":false},{"type":"null"}],"description":"O nome do contato, nos campos da Meta."},"phones":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"wa_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","wa_id","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp."},"emails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os e-mails do contato."},"org":{"anyOf":[{"type":"object","properties":{"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"department":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["company","department","title"],"additionalProperties":false},{"type":"null"}],"description":"A organização do contato."}},"required":["name","phones","emails","org"],"additionalProperties":false}},{"type":"null"}],"description":"Os cartões de contato que o interlocutor compartilhou."},"reaction":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que recebeu a reação."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O emoji. Nulo quando o interlocutor retirou a reação."}},"required":["wamid","emoji"],"additionalProperties":false,"description":"A reação a uma mensagem, ou a retirada dela."},{"type":"null"}]},"context":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor citou ao responder."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem enviou a mensagem citada."},"forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada."},"frequently_forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada muitas vezes."}},"required":["wamid","from","forwarded","frequently_forwarded"],"additionalProperties":false,"description":"A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada."},{"type":"null"}]},"referral":{"anyOf":[{"type":"object","properties":{"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A origem do clique, como ad ou post."},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do anúncio ou da publicação na Meta."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do anúncio ou da publicação."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do anúncio."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do anúncio."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mídia do anúncio, como image ou video."},"ctwa_clid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do clique, para atribuição de conversão."}},"required":["source_type","source_id","source_url","headline","body","media_type","ctwa_clid"],"additionalProperties":false,"description":"O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever."},{"type":"null"}]},"unsupported":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta, como ela mandou (131051 é \"tipo de mensagem sem suporte\")."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o mandou."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O detalhe do erro, como a Meta o mandou."}},"required":["code","title","details"],"additionalProperties":false,"description":"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\"."},{"type":"null"}]},"edit":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que foi editada."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do conteúdo novo, como text."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto novo, quando o conteúdo novo é texto."}},"required":["wamid","type","text"],"additionalProperties":false,"description":"Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit)."},{"type":"null"}]},"revoke":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor apagou para todos."}},"required":["wamid"],"additionalProperties":false,"description":"Presente quando o interlocutor apagou uma mensagem para todos (type é revoke)."},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde veio o pedido."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto que o interlocutor escreveu junto com o pedido."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do produto no seu catálogo."},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A quantidade pedida, como a Meta mandou."},"item_price":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O preço unitário, como a Meta mandou."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda do preço."}},"required":["product_retailer_id","quantity","item_price","currency"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens do pedido."}},"required":["catalog_id","text","items"],"additionalProperties":false,"description":"O pedido que o interlocutor montou num catálogo e enviou (type é order)."},{"type":"null"}]}},"required":["id","wamid","wa_id","user_id","parent_user_id","username","type","text","profile_name","media","interactive","button","location","contacts","reaction","context","referral","unsupported","edit","revoke","order"],"additionalProperties":false,"description":"Uma mensagem que o dono do negócio escreveu pelo aplicativo WhatsApp Business do celular, num número conectado em coexistência. Só ocorre em número conectado em coexistência. É o sinal para um agente automatizado ficar quieto na conversa: um humano respondeu. A forma é a de message.received, e wa_id é o destinatário. Todo campo está sempre presente, e é nulo quando não se aplica."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","message"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o template pertence à conta de negócio, e não a um número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"template.status"},"template":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem."},"name":{"type":"string","minLength":1,"description":"O nome do template."},"language":{"type":"string","minLength":1,"description":"O idioma do template, no código da Meta."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts)."},"status":{"type":"string","minLength":1,"description":"O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer."},"category":{"type":"string","minLength":1,"description":"A categoria do template, no vocabulário da Meta."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O motivo que a Meta informou para a rejeição ou a pausa. Nulo quando ela não informa um, como nas aprovações."}},"required":["id","name","language","waba_id","external_id","status","category","reason"],"additionalProperties":false,"description":"O estado de um template mudou na Meta: aprovado, rejeitado, pausado, desativado ou outro. Não tem número nem conversa, porque o template pertence à conta de negócio."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","template"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"coexistence":{"type":"boolean","description":"true quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo do celular. Pode ser false no instante da conexão e passar a true depois. O estado corrente está no campo coexistence de GET /v1/numbers/{id}."}},"required":["id","phone_number_id","display_number","external_id","waba_id","coexistence"],"additionalProperties":false,"description":"Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão: você não precisa consultar a lista de números para descobrir. Para saber se o envio já está liberado, leia o campo ready de GET /v1/numbers/{id}."},"event_type":{"type":"string","const":"number.connected"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"awaiting_payment_since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando a Meta recusou o primeiro envio por falta de método de pagamento. É o mesmo valor que GET /v1/numbers/{id} devolve em awaitingPaymentSince enquanto a espera durar."}},"required":["id","phone_number_id","display_number","external_id","awaiting_payment_since"],"additionalProperties":false,"description":"A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). O número continua conectado e os eventos de entrada seguem chegando, mas os envios são recusados até o dono da conta cadastrar ou regularizar o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. O evento sai uma vez ao entrar no estado, e não a cada mensagem recusada: as mensagens recusadas chegam como message.status com status failed."},"event_type":{"type":"string","const":"number.payment_required"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."}},"required":["id","phone_number_id","display_number","external_id"],"additionalProperties":false,"description":"Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas; envie de novo o que ainda interessa."},"event_type":{"type":"string","const":"number.payment_resolved"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.restricted"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"restrictions":{"type":"array","items":{"type":"object","properties":{"restriction_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da restrição, no vocabulário da Meta."},"expiration":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo."},"remediation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que a Meta diz que resolve a restrição, quando informa."}},"required":["restriction_type","expiration","remediation"],"additionalProperties":false},"description":"As restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar."}},"required":["waba_id","number_id","display_number","external_id","restrictions"],"additionalProperties":false,"description":"A Meta restringiu a conta de WhatsApp Business deste número. O que a restrição impede depende do tipo: confira restrictions[].restriction_type e o prazo em expiration. A Luna não levanta restrição; quem resolve é o dono da conta, no WhatsApp Manager da Meta. A Meta não avisa quando uma restrição por prazo termina."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.violation"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"violation_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da violação, no vocabulário da Meta."}},"required":["waba_id","number_id","display_number","external_id","violation_type"],"additionalProperties":false,"description":"A Meta registrou uma violação de política na conta de WhatsApp Business deste número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. O dono da conta lê os detalhes no WhatsApp Manager da Meta."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.disabled"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"ban_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A data da desativação, como a Meta informou."}},"required":["waba_id","number_id","display_number","external_id","ban_date"],"additionalProperties":false,"description":"A Meta desativou a conta de WhatsApp Business deste número. Os envios param de ser aceitos. A Luna não reativa conta: o dono dela pede a revisão à Meta, e o evento account.reinstated avisa se a conta voltar."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.reinstated"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"ban_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A data informada pela Meta junto com a reativação, quando houver."}},"required":["waba_id","number_id","display_number","external_id","ban_date"],"additionalProperties":false,"description":"A Meta reativou a conta de WhatsApp Business deste número depois de uma desativação."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.update"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"event":{"type":"string","minLength":1,"description":"O campo event do aviso account_update da Meta, sem tradução: ACCOUNT_DELETED, ACCOUNT_RECONNECTED, VOLUME_BASED_PRICING_TIER_UPDATE, DISABLED_UPDATE com um estado que não é desativação nem reativação, e outros. Novos valores podem aparecer."},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"O restante do aviso da Meta, como ela mandou, sem o campo event."}},"required":["waba_id","number_id","display_number","external_id","event","details"],"additionalProperties":false,"description":"Um aviso de conta da Meta que a Luna não traduz em um tipo próprio. Chega com o event cru da Meta para que o seu sistema decida o que fazer com ele. Se você não usa, ignore."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.limit_changed"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"daily_conversation_limit":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Conta pessoas únicas a quem o negócio escreve fora da janela de atendimento, e é do portfólio empresarial. É o teto concedido, e nunca quanto foi usado. Nulo quando o aviso mudou só o limite de números."},"max_phone_numbers_per_waba":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Quantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas."}},"required":["waba_id","number_id","display_number","external_id","daily_conversation_limit","max_phone_numbers_per_waba"],"additionalProperties":false,"description":"A Meta mudou o limite desta conta. O limite é do portfólio de negócio, e vale para todos os números da conta. O valor corrente de cada número está em limiteDiarioDeConversas, em GET /v1/numbers."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"reason":{"type":"string","minLength":1,"description":"O motivo da desconexão: requested_by_tenant (você desconectou o número com DELETE /v1/numbers/{id}), ou o aviso da Meta que a causou, PARTNER_APP_UNINSTALLED (o cliente removeu o aplicativo), PARTNER_REMOVED (a Luna foi removida como parceira da conta) ou ACCOUNT_OFFBOARDED (o vínculo da conta com a Luna foi encerrado). Novos valores podem aparecer."},"disconnection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O motivo que a Meta informou em disconnection_info, quando informa."},"initiated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem iniciou a desconexão, como a Meta informou."}},"required":["id","phone_number_id","display_number","external_id","waba_id","reason","disconnection_reason","initiated_by"],"additionalProperties":false,"description":"O número deixou de estar conectado à Luna. É o par de number.connected. Os envios deste número não funcionam mais; para voltar, o seu cliente precisa conectar de novo, com um novo link de conexão."},"event_type":{"type":"string","const":"number.disconnected"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"previous_quality_rating":{"type":"string","minLength":1,"description":"A avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED."},"quality_rating":{"type":"string","minLength":1,"description":"A avaliação de qualidade atual, no vocabulário da Meta."}},"required":["id","phone_number_id","display_number","external_id","waba_id","previous_quality_rating","quality_rating"],"additionalProperties":false,"description":"A avaliação de qualidade do número mudou. A Meta não tem webhook para isso: a Luna confere a qualidade de cada número periodicamente, então o evento chega com atraso de até a cadência da conferência (cerca de uma hora). O histórico está em GET /v1/numbers/{id}/health."},"event_type":{"type":"string","const":"number.quality_changed"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"status":{"type":"string","minLength":1,"description":"O estado da revisão do nome de exibição, o mesmo de displayNameStatus em GET /v1/numbers/{id}: approved, pending_review, declined, expired ou none. Novos valores podem aparecer."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome a que o estado se refere: o nome pedido, quando há um pedido, senão o nome em uso. Nulo quando a Meta não informou."}},"required":["id","phone_number_id","display_number","external_id","waba_id","status","name"],"additionalProperties":false,"description":"O estado da revisão do nome de exibição do número mudou, por exemplo de pending_review para approved ou declined. A Luna confere o nome de cada número periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo; o estado corrente está em displayNameStatus, em GET /v1/numbers/{id}."},"event_type":{"type":"string","const":"number.display_name_reviewed"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"credential_expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. É o mesmo valor que GET /v1/business-accounts devolve em credentialExpiresAt. Depois dessa data a Meta recusa as chamadas da Luna nesta conta, e o número para de enviar e de receber."}},"required":["id","phone_number_id","display_number","external_id","waba_id","credential_expires_at"],"additionalProperties":false,"description":"A autorização que o cliente deu à Luna para operar este número vence em até 14 dias. Para renovar, o seu cliente refaz a conexão: abra um link com POST /v1/onboarding/links informando numberId, e ele cai direto na reconexão deste número, sem contar um número novo. O evento sai uma vez por vencimento e por número, e não se repete a cada dia. Se a autorização foi emitida sem prazo, ele não sai nunca."},"event_type":{"type":"string","const":"number.credential_expiring"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.alert"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número)."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador, na Meta, do que o alerta cita."},"alert_severity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A gravidade que a Meta atribuiu ao alerta, no vocabulário dela."},"alert_status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Se o alerta está ativo ou foi resolvido, no vocabulário da Meta."},"alert_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do alerta, no vocabulário da Meta: por exemplo INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED, INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO ou PROFILE_PICTURE_LOST. Novos valores podem aparecer."},"alert_description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do alerta, em texto, como a Meta mandou."},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"O restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia."}},"required":["waba_id","number_id","display_number","external_id","entity_type","entity_id","alert_severity","alert_status","alert_type","alert_description","details"],"additionalProperties":false,"description":"A Meta mandou um alerta sobre a conta de WhatsApp Business deste número (o campo account_alerts). Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager da Meta."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}."},"can_send":{"type":"boolean","description":"Se o envio por este número vai funcionar agora, o mesmo de connection.canSend."},"reasons":{"minItems":1,"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"O código do motivo, para o seu código comparar: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired, account_blocked. Novos códigos podem aparecer."},"message":{"type":"string","description":"O que está acontecendo, em português, pronto para repassar ao seu cliente."},"solution":{"type":"string","description":"O que fazer a respeito, em português."}},"required":["code","message","solution"],"additionalProperties":false},"description":"Os motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento."}},"required":["id","phone_number_id","display_number","external_id","status","can_send","reasons"],"additionalProperties":false,"description":"Este número passou a precisar de uma ação sua ou do seu cliente: autorização vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela. Mostra o motivo ao seu cliente com message e solution. Quando a lista esvazia, sai number.action_resolved. O estado corrente está em connection, em GET /v1/numbers/{id}."},"event_type":{"type":"string","const":"number.action_required"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}."},"can_send":{"type":"boolean","description":"Se o envio por este número vai funcionar agora, o mesmo de connection.canSend."}},"required":["id","phone_number_id","display_number","external_id","status","can_send"],"additionalProperties":false,"description":"Este número não precisa mais de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou (connected, ou connecting se a conexão voltou a estar em curso)."},"event_type":{"type":"string","const":"number.action_resolved"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão ou o que resultou da conexão, ou null quando o evento não tem número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."}},"required":["id","phone_number_id","display_number","external_id","waba_id"],"additionalProperties":false},{"type":"null"}],"description":"O número que resultou da conexão, no mesmo formato dos eventos number.*, com waba_id. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto."},"event_type":{"type":"string","const":"onboarding.link.completed"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"used_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}."},"waba_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A conta de WhatsApp Business que o seu cliente conectou, o mesmo id que GET /v1/business-accounts devolve em wabaId. Está preenchido mesmo quando a conta foi conectada sem número (number_id nulo). Nulo só se a Luna não a leu."},"number_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O número que resultou da conexão, o mesmo id de GET /v1/numbers. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto."}},"required":["id","external_id","used_at","waba_id","number_id"],"additionalProperties":false,"description":"O seu cliente concluiu a conexão por um link: ele aceitou os termos da Meta e a Luna recebeu o acesso à conta dele. É o fim do link, que passa a used. O número pode ainda estar sendo registrado: quem avisa que ele ficou pronto para enviar é number.connected. Sai uma vez por link."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão, ou null quando o link é de uma conexão nova."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"onboarding.link.opened"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"opened_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o seu cliente abriu o link pela primeira vez."}},"required":["id","external_id","opened_at"],"additionalProperties":false,"description":"O seu cliente abriu o link pela primeira vez. Sai uma vez por link, na primeira abertura, e não de novo quando ele volta à página ou tenta outra vez. É o começo do ciclo: depois dele vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão, ou null quando o link é de uma conexão nova."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"onboarding.link.failed"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"session_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"A tentativa de conexão que não deu certo. Um link aberto admite várias."},"reason":{"type":"string","enum":["abandoned","error","failed","country_not_supported","registration_blocked"],"description":"Por que a tentativa não deu certo: abandoned (o cliente fechou a janela da Meta e a tela em que parou está em step), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir várias vezes e não conseguiu), country_not_supported (o número escolhido não é +55) ou registration_blocked (a Meta bloqueou o registro do número por 72 horas). Novos motivos podem aparecer."},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado."},"error_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro que a janela da Meta relatou. Nulo quando não houve erro relatado."}},"required":["id","external_id","session_id","reason","step","error_code"],"additionalProperties":false,"description":"Uma tentativa de conexão por um link não deu certo: o cliente desistiu em alguma tela, a janela da Meta relatou um erro, ou a conexão parou. O link continua aberto até vencer, e o cliente pode tentar de novo. Sai uma vez por tentativa. O que o cliente deve fazer para cada reason está no guia Conectar um número."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão, ou null quando o link é de uma conexão nova."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"onboarding.link.expired"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"expired_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o link venceu, o mesmo expiresAt de GET /v1/onboarding/links/{id}."}},"required":["id","external_id","expired_at"],"additionalProperties":false,"description":"O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link que foi usado nunca gera este evento. Sai uma vez por link."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o template pertence à conta de negócio, e não a um número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"template.category"},"template":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem."},"name":{"type":"string","minLength":1,"description":"O nome do template."},"language":{"type":"string","minLength":1,"description":"O idioma do template, no código da Meta."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts)."},"category":{"type":"string","minLength":1,"description":"A categoria do template, no vocabulário da Meta."},"previous_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio."},"new_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio."},"correct_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"No aviso prévio, a categoria para a qual a Meta vai mudar o template. Nulo quando a mudança já foi feita."},"scheduled_for":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},{"type":"null"}],"description":"No aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita."}},"required":["id","name","language","waba_id","external_id","category","previous_category","new_category","correct_category","scheduled_for"],"additionalProperties":false,"description":"A Meta mudou, ou vai mudar, a categoria de um template. Chega de duas formas: o aviso prévio (correct_category e scheduled_for preenchidos) e a mudança feita (previous_category e new_category preenchidos). A categoria define o preço que a Meta cobra do negócio por mensagem: de UTILITY para MARKETING, o preço sobe. Quem paga é o dono da conta, direto à Meta."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","template"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o template pertence à conta de negócio, e não a um número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"template.quality"},"template":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem."},"name":{"type":"string","minLength":1,"description":"O nome do template."},"language":{"type":"string","minLength":1,"description":"O idioma do template, no código da Meta."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts)."},"previous_quality_score":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN."},"new_quality_score":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A nota de qualidade de agora, no vocabulário da Meta."}},"required":["id","name","language","waba_id","external_id","previous_quality_score","new_quality_score"],"additionalProperties":false,"description":"A nota de qualidade de um template mudou. Nota baixa antecede a pausa do template pela Meta: é o momento de revisar o conteúdo ou o público."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","template"],"additionalProperties":false}],"description":"The event Luna delivers to your server's endpoint.\n\nDelivery is at-least-once: the same delivery can arrive more than once, and this happens in practice, not just in theory. A timeout reached after your server has already processed the request produces exactly that case.\n\nOrder is guaranteed within a conversation, and template.status events are ordered among themselves per business account, since a template belongs to no conversation, template.category and template.quality events join that same order, and number and account events (number.* and account.*) are ordered among themselves per number. It is not guaranteed across conversations: two events from different conversations can arrive in any order, and an event from a slow conversation can arrive after a newer event from another one.\n\nIdempotency is your duty, and the event_id is what the platform gives you to fulfil it. It is stable: the same delivery, repeated, carries the same event_id. Keep the ones you have processed and drop the repeats.\n\nIf your endpoint stays down for too long, the platform drops what piled up, and you lose those events: they will not be resent. When that happens you receive a backlog.dropped event stating how many were dropped and for what period. That notice is not dropped along with the backlog it describes.\n\nNew event types can appear without the contract version changing. If your server receives an event_type it does not know, answer 2xx and ignore the event. The version only changes when the shape of an existing type changes, and that comes with notice and a deadline.\n\nOn a number connected in coexistence, if the import of earlier conversations is still in progress when its deadline approaches, you receive a history_sync.deadline_approaching event carrying the number and the deadline as an instant. That deadline is the platform's estimate: 24 hours from when it saw the import begin. Meta's own clock starts slightly earlier, so treat the instant as a limit and act with margin. Once the deadline passes without completion, the Meta platform disconnects the end business and it has to redo the connection on the device. The notice is sent before the deadline and never after, and there is a single one for the number: like any delivery, it can repeat, always with the same event_id, and a number that redoes the connection later does not receive a second notice. The current state of the import is at GET /v1/numbers/{id}/health."}}},"paths":{"/healthz":{"get":{"summary":"Check whether the API is up","tags":["Status"],"description":"Answers 200 while the process is running. It requires no authentication and touches neither database nor queue, because it probes the process and not its dependencies. A 200 here does not promise that message sending works.","responses":{"200":{"description":"Success."}},"security":[]}},"/status":{"get":{"summary":"See whether Luna is receiving and delivering","tags":["Status"],"description":"Answers 200 with the platform state, measured every few minutes by a synthetic message that enters through the same door Meta uses and has to reach a destination over HTTPS. It requires no authentication and reveals no account data. When there is no recent check yet, the state is unknown, never ok.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"description":"O veredito geral. ok: a entrada e a entrega funcionam. degraded: uma verificação falhou e ainda não se repetiu, ou o horizonte de partições do banco está curto. down: a entrada ou a entrega falhou em verificações seguidas. unknown: ainda não há verificação recente."},"checkedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a última verificação terminou, em UTC. Nulo se nunca houve."},"components":{"type":"object","properties":{"ingestion":{"type":"string","enum":["ok","degraded","down","unknown"],"description":"A porta que recebe os webhooks da Meta."},"delivery":{"type":"string","enum":["ok","degraded","down","unknown"],"description":"A entrega de um evento recebido ao destino, por HTTPS."},"partitions":{"type":"string","enum":["ok","degraded","down","unknown"],"description":"O horizonte de partições futuras do banco."}},"required":["ingestion","delivery","partitions"],"additionalProperties":false,"description":"Cada parte do caminho, medida de ponta a ponta por uma mensagem sintética."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Desde quando o veredito geral é o atual, em UTC. Nulo se unknown."}},"required":["status","checkedAt","components","since"],"additionalProperties":false}}}}},"security":[]}},"/":{"get":{"summary":"Introduce the API","tags":["Status"],"description":"Answers 200 with the API name and the addresses of the documentation and of the OpenAPI specification. It requires no authentication and touches neither database nor queue.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"O nome da API."},"docs":{"type":"string","description":"O endereço da documentação legível."},"openapi":{"type":"string","description":"O endereço da especificação OpenAPI em JSON."}},"required":["name","docs","openapi"],"additionalProperties":false}}}}},"security":[]}},"/v1/api-keys":{"get":{"summary":"List API keys","tags":["Keys"],"description":"This customer's keys, with scopes, profile, status (active, revoked or expired), creation date, last use, revocation and what the account can do with each one (allowedActions).","parameters":[{"schema":{"type":"string","enum":["integration","session","elevation"]},"in":"query","name":"kind","required":false}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que você deu à chave, para reconhecê-la na lista."},"kind":{"type":"string","enum":["integration","session","elevation"],"description":"integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele."},"scopes":{"type":"array","items":{"type":"string"},"description":"O que esta chave pode fazer. Uma rota fora deste conjunto responde 403."},"mode":{"type":"string","enum":["live","test"],"description":"live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação."},"createdAt":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Nulo em chave de integração: ela vale até ser revogada."},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O último uso registrado, para identificar chave esquecida."},"status":{"type":"string","enum":["active","revoked","expired"],"description":"active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas."},"profile":{"anyOf":[{"type":"string","enum":["agent","full","read_only"]},{"type":"null"}],"description":"O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes."},"allowedActions":{"type":"array","items":{"type":"string","enum":["revoke"]},"description":"O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou."}},"required":["id","label","kind","scopes","mode","externalId","createdAt","expiresAt","revokedAt","lastUsedAt","status","profile","allowedActions"],"additionalProperties":false,"example":{"id":"7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334","label":"integração de produção","kind":"integration","scopes":["messages:write","messages:read","numbers:read"],"mode":"live","externalId":null,"createdAt":"2026-08-07T12:10:44.201Z","expiresAt":null,"revokedAt":null,"lastUsedAt":"2026-08-10T09:02:18.664Z","status":"active","profile":"agent","allowedActions":["revoke"]}}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"keys:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-api-keys"}},"post":{"summary":"Create an API key","tags":["Keys"],"description":"Mints a new key and returns the secret exactly once. Store it the moment you receive it, because no route will return it again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"scopes":{"description":"O que a chave pode fazer, escopo por escopo. Mande scopes ou profile, e nunca os dois: a lista de escopos que cada perfil concede está em GET /v1/api-keys/profiles.","minItems":1,"type":"array","items":{"type":"string","enum":["keys:read","keys:write","numbers:read","numbers:write","messages:read","messages:write","templates:read","templates:write","onboarding:write","webhooks:read","webhooks:write","session:end","session:elevate"]}},"profile":{"description":"Um perfil pronto no lugar de scopes: agent (atendimento), full (integração completa) ou read_only (somente leitura). A chave nasce com os escopos que o perfil concede no momento da criação, e a lista deles está em GET /v1/api-keys/profiles.","type":"string","enum":["agent","full","read_only"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"mode":{"description":"live (o padrão) é a chave de sempre. test cria uma chave do modo de teste: POST /v1/messages com ela NÃO vai à Meta, não usa número seu e não conta na capacidade do plano; a Luna devolve ao seu webhook eventos simulados, assinados e com test: true. Uma chave de teste só usa POST /v1/messages e POST /v1/test-mode/inbound-messages, e não aceita externalId. Não dá para mudar depois: crie outra.","type":"string","enum":["live","test"]},"externalId":{"description":"O seu identificador para o cliente a que esta chave pertence (1 a 128 caracteres), o mesmo externalId do link de conexão e dos números. Com ele, a chave é de UM cliente seu: só lê e envia pelos números com este externalId (inclusive os conectados depois), só cria link com ele, e não lista nem cria endpoints de webhook nem chaves. Sem ele, a chave é da conta inteira. Não dá para mudar depois: crie outra.","type":"string","minLength":1,"maxLength":128}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que você deu à chave, para reconhecê-la na lista."},"kind":{"type":"string","enum":["integration","session","elevation"],"description":"integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele."},"scopes":{"type":"array","items":{"type":"string"},"description":"O que esta chave pode fazer. Uma rota fora deste conjunto responde 403."},"mode":{"type":"string","enum":["live","test"],"description":"live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação."},"createdAt":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Nulo em chave de integração: ela vale até ser revogada."},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O último uso registrado, para identificar chave esquecida."},"status":{"type":"string","enum":["active","revoked","expired"],"description":"active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas."},"profile":{"anyOf":[{"type":"string","enum":["agent","full","read_only"]},{"type":"null"}],"description":"O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes."},"allowedActions":{"type":"array","items":{"type":"string","enum":["revoke"]},"description":"O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou."},"secret":{"type":"string"}},"required":["id","label","kind","scopes","mode","externalId","createdAt","expiresAt","revokedAt","lastUsedAt","status","profile","allowedActions","secret"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"keys:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-api-keys"}}},"/v1/api-keys/scopes":{"get":{"summary":"List the scopes a key can have","tags":["Keys"],"description":"The scopes an integration key can receive, each with its name in Portuguese, what it allows and whether it gives a power that calls for care.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string","description":"O nome do escopo, o que vai em scopes ao criar a chave."},"label":{"type":"string","description":"O nome da permissão em português."},"summary":{"type":"string","description":"O que a permissão deixa fazer."},"sensitive":{"type":"boolean","description":"true quando a permissão dá um poder que exige cuidado (criar chaves, redirecionar o webhook)."}},"required":["scope","label","summary","sensitive"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false,"example":{"data":[{"scope":"messages:write","label":"Enviar mensagens","summary":"Envia mensagens e templates pelos números conectados.","sensitive":false},{"scope":"keys:write","label":"Criar e revogar chaves","summary":"Permite que esta chave crie outras chaves, sem prazo. Dê só a quem precisa.","sensitive":true}]}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"keys:read"}},"/v1/api-keys/profiles":{"get":{"summary":"List the key profiles","tags":["Keys"],"description":"The ready-made key profiles (agent, full and read_only) and the scopes each one grants. In POST /v1/api-keys, profile stands in for scopes.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["agent","full","read_only"],"description":"O que vai em profile ao criar a chave."},"label":{"type":"string"},"summary":{"type":"string","description":"O que a chave deste perfil permite, em uma frase."},"scopes":{"type":"array","items":{"type":"string"},"description":"Os escopos que o perfil concede hoje."}},"required":["id","label","summary","scopes"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false,"example":{"data":[{"id":"read_only","label":"Somente leitura","summary":"Consulta tudo e não altera nada.","scopes":["keys:read","numbers:read","messages:read","templates:read","webhooks:read"]}]}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"keys:read"}},"/v1/api-keys/{id}":{"get":{"summary":"Read one API key","tags":["Keys"],"description":"One key's metadata. The secret does not come back, for the reason described on the listing route.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que você deu à chave, para reconhecê-la na lista."},"kind":{"type":"string","enum":["integration","session","elevation"],"description":"integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele."},"scopes":{"type":"array","items":{"type":"string"},"description":"O que esta chave pode fazer. Uma rota fora deste conjunto responde 403."},"mode":{"type":"string","enum":["live","test"],"description":"live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação."},"createdAt":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Nulo em chave de integração: ela vale até ser revogada."},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O último uso registrado, para identificar chave esquecida."},"status":{"type":"string","enum":["active","revoked","expired"],"description":"active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas."},"profile":{"anyOf":[{"type":"string","enum":["agent","full","read_only"]},{"type":"null"}],"description":"O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes."},"allowedActions":{"type":"array","items":{"type":"string","enum":["revoke"]},"description":"O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou."}},"required":["id","label","kind","scopes","mode","externalId","createdAt","expiresAt","revokedAt","lastUsedAt","status","profile","allowedActions"],"additionalProperties":false,"example":{"id":"7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334","label":"integração de produção","kind":"integration","scopes":["messages:write","messages:read","numbers:read"],"mode":"live","externalId":null,"createdAt":"2026-08-07T12:10:44.201Z","expiresAt":null,"revokedAt":null,"lastUsedAt":"2026-08-10T09:02:18.664Z","status":"active","profile":"agent","allowedActions":["revoke"]}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"keys:read"}},"/v1/api-keys/{id}/revoke":{"post":{"summary":"Revoke an API key","tags":["Keys"],"description":"Invalidates the key immediately. The operation is idempotent, so revoking again returns the same result without an error.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que você deu à chave, para reconhecê-la na lista."},"kind":{"type":"string","enum":["integration","session","elevation"],"description":"integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele."},"scopes":{"type":"array","items":{"type":"string"},"description":"O que esta chave pode fazer. Uma rota fora deste conjunto responde 403."},"mode":{"type":"string","enum":["live","test"],"description":"live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação."},"createdAt":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Nulo em chave de integração: ela vale até ser revogada."},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O último uso registrado, para identificar chave esquecida."},"status":{"type":"string","enum":["active","revoked","expired"],"description":"active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas."},"profile":{"anyOf":[{"type":"string","enum":["agent","full","read_only"]},{"type":"null"}],"description":"O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes."},"allowedActions":{"type":"array","items":{"type":"string","enum":["revoke"]},"description":"O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou."}},"required":["id","label","kind","scopes","mode","externalId","createdAt","expiresAt","revokedAt","lastUsedAt","status","profile","allowedActions"],"additionalProperties":false,"example":{"id":"7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334","label":"integração de produção","kind":"integration","scopes":["messages:write","messages:read","numbers:read"],"mode":"live","externalId":null,"createdAt":"2026-08-07T12:10:44.201Z","expiresAt":null,"revokedAt":null,"lastUsedAt":"2026-08-10T09:02:18.664Z","status":"active","profile":"agent","allowedActions":["revoke"]}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"keys:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-api-keys-id-revoke"}}},"/v1/subscription":{"get":{"summary":"Read the plan and the subscription","tags":["Account and plan"],"description":"The account's plan (free trial or contracted), the number capacity and how many are in use, and what Helsen charges for the period: the capacity of active numbers, and nothing beyond that.","parameters":[{"schema":{"example":"2026-03-01T00:00:00.000Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"in":"query","name":"inicio","required":false},{"schema":{"example":"2026-04-01T00:00:00.000Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"in":"query","name":"fim","required":false}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"planName":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"Growth","description":"O nome do plano: Teste grátis enquanto a conta está no teste, e o nome da faixa que comporta a capacidade depois que ela é contratada (Avulso, Starter, Growth, Scale, ou Sob consulta acima de 60). Nulo enquanto a conta não começou plano."},"status":{"type":"string","enum":["none","trial","active","suspended"],"example":"trial","description":"none: a conta ainda não começou plano (o e-mail não foi confirmado). trial: teste grátis em curso. active: conta contratada. suspended: escrita e envio recusados; suspendedReason diz por quê."},"suspendedReason":{"anyOf":[{"type":"string","enum":["trial_expired","account_blocked"]},{"type":"null"}],"example":null,"description":"Quando status é suspended: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). Nulo nos outros casos."},"capacity":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"example":20,"description":"Quantos números a conta pode manter ativos ao mesmo tempo. Nulo enquanto a conta não começou plano."},"activeNumbers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":3,"description":"Quantos números estão ativos agora. É a contagem que a capacidade usa; a da assinatura do mês é numerosAtivos, que soma os que ficaram ativos em algum momento do período."},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"2026-11-03T13:00:00.000Z","description":"Quando o teste grátis termina. Fica preenchido depois que a conta é contratada, como registro. Nulo se a conta nunca teve teste."},"trialDaysLeft":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"example":5,"description":"Quantos dias faltam para o teste terminar, calculados pela API (arredondados para cima, mínimo 0). Nulo fora do teste."},"periodo":{"type":"object","properties":{"inicio":{"type":"string","example":"2026-03-01T00:00:00.000Z"},"fim":{"type":"string","example":"2026-04-01T00:00:00.000Z"}},"required":["inicio","fim"],"additionalProperties":false},"canConnectNumber":{"type":"boolean","example":true,"description":"Se esta conta pode abrir a conexão de um número novo agora: o e-mail está confirmado, a conta não está suspensa e ainda há vaga na capacidade. É a mesma decisão que a abertura da conexão e a criação do link de conexão aplicam, então a tela pode mostrar ou esconder o botão sem comparar nada."},"capacityLeft":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"example":17,"description":"Quantos números ainda cabem na capacidade (nunca negativo). Nulo enquanto a conta não começou plano."},"capacityNotice":{"anyOf":[{"type":"string"},{"type":"null"}],"example":null,"description":"Quando canConnectNumber é false, o texto da recusa, o mesmo que a API devolve ao tentar conectar: e-mail por confirmar, conta suspensa ou capacidade cheia. Nulo quando pode conectar."},"writesAllowed":{"type":"boolean","example":true,"description":"Se a conta pode fazer alterações agora. É false só com a conta suspensa, e então suspendedNotice diz por quê. Ler, desconectar número e revogar chave continuam valendo."},"suspendedNotice":{"anyOf":[{"type":"string"},{"type":"null"}],"example":null,"description":"O texto da suspensão, o mesmo das recusas 403 de escrita. Nulo quando a conta não está suspensa."},"pricePerMonth":{"anyOf":[{"type":"number"},{"type":"null"}],"example":990,"description":"O valor mensal da faixa de capacidade contratada, em reais, que a Helsen cobra pela capacidade de números e por mais nada. Nulo no teste grátis, enquanto a conta não começou plano e acima da última faixa (Sob consulta)."},"currency":{"anyOf":[{"type":"string","enum":["BRL"]},{"type":"null"}],"example":"BRL","description":"A moeda de pricePerMonth. Nulo quando pricePerMonth é nulo."},"contactEmail":{"type":"string","example":"contato@lunahia.com.br","description":"O e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão."},"numerosAtivos":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"example":3,"description":"Quantos números distintos estiveram ativos em algum momento do período consultado (periodo): a contagem que a assinatura do mês usa. Não é o mesmo que activeNumbers: este é o acumulado do período e inclui um número que já foi desconectado depois de ter sido ativo nele; activeNumbers é quantos estão ativos agora e é o que a capacidade compara."},"phoneNumberIds":{"type":"array","items":{"type":"string"},"example":["15550001111","15550002222"],"description":"Os ids da Meta (metaPhoneNumberId) dos números que entraram em numerosAtivos, para você conferir a contagem. É uma lista de identificadores, sem contagem de mensagens."}},"required":["planName","status","suspendedReason","capacity","activeNumbers","trialEndsAt","trialDaysLeft","periodo","canConnectNumber","capacityLeft","capacityNotice","writesAllowed","suspendedNotice","pricePerMonth","currency","contactEmail","numerosAtivos","phoneNumberIds"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-subscription"}}},"/v1/limits":{"get":{"summary":"Read the platform's technical limits","tags":["Account and plan"],"description":"The ceilings the API applies, each with its value, unit and reason. They are the same for every customer and do not depend on the plan: they exist for infrastructure capacity or because Meta imposes them. They are not a count of your usage and do not enter billing.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"O identificador estável do limite, para o seu código comparar. Novos limites podem aparecer."},"label":{"type":"string","description":"O nome do limite, em português."},"value":{"type":"number","description":"O valor, na unidade de unit."},"unit":{"type":"string","description":"A unidade de value: requests_per_minute, endpoints, seconds, hours, bytes ou messages_per_second."},"reason":{"type":"string","description":"Por que o limite existe, em português. É sempre capacidade ou regra da Meta, nunca preço."}},"required":["key","label","value","unit","reason"],"additionalProperties":false},"description":"Os limites, na ordem em que devem aparecer."}},"required":["data"],"additionalProperties":false,"example":{"data":[{"key":"webhook_endpoints","label":"Endpoints de webhook por cliente","value":25,"unit":"endpoints","reason":"Cada evento é entregue a cada endpoint que o aceita. Remover um endpoint libera a vaga."}]}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"}},"/v1/messages":{"post":{"summary":"Send a text message","tags":["Messages"],"description":"Accepts the message, returns 202 with its identifier, and delivers it to Meta asynchronously. With a test key, the message does NOT go to Meta: Luna returns the 202 and delivers the simulated states sent, delivered and read to your webhook, with test: true. The optional Idempotency-Key header (1 to 255 visible characters, no space) makes repeating the request return the original message; empty or malformed answers 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"default":"text","description":"Sempre text. Pode ser omitido: um corpo sem type é interpretado como texto, para não quebrar quem integrou antes dos demais tipos existirem.","type":"string","enum":["text"]},"text":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4096,"description":"O texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API."},"preview_url":{"description":"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.","type":"boolean"}},"required":["body"],"additionalProperties":false}},"required":["from","text"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","text":{"body":"Olá! Recebemos seu pedido e já estamos preparando."}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre image.","enum":["image"]},"image":{"type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"caption":{"description":"A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.","type":"string","maxLength":1024}},"additionalProperties":false}},"required":["from","type","image"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"image","image":{"link":"https://exemplo.com.br/pedido.jpg","caption":"Seu pedido saiu para entrega."}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre video.","enum":["video"]},"video":{"type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"caption":{"description":"A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.","type":"string","maxLength":1024}},"additionalProperties":false}},"required":["from","type","video"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"video","video":{"id":"1425835918205946"}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre audio.","enum":["audio"]},"audio":{"type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"voice":{"description":"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.","type":"boolean"}},"additionalProperties":false}},"required":["from","type","audio"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"audio","audio":{"id":"1425835918205947"}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre document.","enum":["document"]},"document":{"type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"caption":{"description":"A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API.","type":"string","maxLength":1024},"filename":{"description":"O nome com que o arquivo aparece para quem recebe. Sem ele, quem recebe vê o nome que a Meta derivar da origem.","type":"string","minLength":1,"maxLength":240}},"additionalProperties":false}},"required":["from","type","document"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"document","document":{"link":"https://exemplo.com.br/nota.pdf","filename":"nota-fiscal.pdf"}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre sticker.","enum":["sticker"]},"sticker":{"type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false}},"required":["from","type","sticker"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"sticker","sticker":{"id":"1425835918205948"}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre location.","enum":["location"]},"location":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"A latitude em graus decimais, entre -90 e 90."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"A longitude em graus decimais, entre -180 e 180."},"name":{"description":"O nome do lugar, exibido acima do endereço.","type":"string","maxLength":1000},"address":{"description":"O endereço do lugar, exibido abaixo do nome.","type":"string","maxLength":1000}},"required":["latitude","longitude"],"additionalProperties":false}},"required":["from","type","location"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"location","location":{"latitude":-19.9227,"longitude":-43.9451,"name":"Praça da Liberdade","address":"Belo Horizonte, MG"}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre contacts.","enum":["contacts"]},"contacts":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"object","properties":{"formatted_name":{"type":"string","minLength":1,"maxLength":512,"description":"O nome como ele aparece no cartão."},"first_name":{"description":"O primeiro nome.","type":"string","maxLength":256},"last_name":{"description":"O sobrenome.","type":"string","maxLength":256},"middle_name":{"description":"O nome do meio.","type":"string","maxLength":256},"prefix":{"description":"O prefixo, como Dr. ou Sra.","type":"string","maxLength":64},"suffix":{"description":"O sufixo, como Jr. ou Neto.","type":"string","maxLength":64}},"required":["formatted_name"],"additionalProperties":false},"birthday":{"description":"A data de nascimento em AAAA-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"org":{"description":"Os dados profissionais do contato.","type":"object","properties":{"company":{"description":"A empresa.","type":"string","maxLength":256},"department":{"description":"O departamento.","type":"string","maxLength":256},"title":{"description":"O cargo.","type":"string","maxLength":256}},"additionalProperties":false},"phones":{"description":"Os telefones do contato.","maxItems":20,"type":"array","items":{"type":"object","properties":{"phone":{"description":"O telefone, como ele deve aparecer.","type":"string","maxLength":64},"type":{"description":"O rótulo do telefone, como CELL ou WORK.","type":"string","maxLength":64},"wa_id":{"description":"O identificador do contato no WhatsApp, se conhecido.","type":"string","maxLength":64}},"additionalProperties":false}},"emails":{"description":"Os e-mails do contato.","maxItems":20,"type":"array","items":{"type":"object","properties":{"email":{"description":"O endereço de e-mail.","type":"string","maxLength":320},"type":{"description":"O rótulo do e-mail, como HOME ou WORK.","type":"string","maxLength":64}},"additionalProperties":false}},"addresses":{"description":"Os endereços do contato.","maxItems":20,"type":"array","items":{"type":"object","properties":{"street":{"description":"O logradouro e o número.","type":"string","maxLength":512},"city":{"description":"A cidade.","type":"string","maxLength":256},"state":{"description":"O estado.","type":"string","maxLength":256},"zip":{"description":"O CEP.","type":"string","maxLength":64},"country":{"description":"O país.","type":"string","maxLength":256},"country_code":{"description":"O código do país em duas letras.","type":"string","maxLength":8},"type":{"description":"O rótulo do endereço, como HOME ou WORK.","type":"string","maxLength":64}},"additionalProperties":false}},"urls":{"description":"As páginas do contato.","maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"description":"O endereço na web.","type":"string","maxLength":2048},"type":{"description":"O rótulo da URL, como HOME ou WORK.","type":"string","maxLength":64}},"additionalProperties":false}}},"required":["name"],"additionalProperties":false},"description":"Os cartões de contato a enviar. Ao menos um, no máximo vinte."}},"required":["from","type","contacts"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"contacts","contacts":[{"name":{"formatted_name":"Ana Souza","first_name":"Ana","last_name":"Souza"},"phones":[{"phone":"+55 11 90000-0000","type":"CELL"}]}]}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre reaction.","enum":["reaction"]},"reaction":{"type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."},"emoji":{"type":"string","maxLength":16,"description":"O emoji da reação. Mande vazio para remover uma reação que já tinha sido posta."}},"required":["message_id","emoji"],"additionalProperties":false}},"required":["from","type","reaction"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"reaction","reaction":{"message_id":"wamid.HBgNNTUzMTk4MTAzNjQzNhUCABIYFjNBMEE=","emoji":"👍"}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre interactive.","enum":["interactive"]},"interactive":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","description":"Sempre button.","enum":["button"]},"header":{"description":"O cabeçalho, exibido acima do corpo.","type":"object","properties":{"type":{"type":"string","enum":["text","image","video","document"],"description":"O que o cabeçalho carrega."},"text":{"description":"O texto do cabeçalho, quando type é text.","type":"string","maxLength":60},"image":{"description":"A imagem do cabeçalho, quando type é image.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"video":{"description":"O vídeo do cabeçalho, quando type é video.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"document":{"description":"O documento do cabeçalho, quando type é document.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"filename":{"type":"string","maxLength":240}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"buttons":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Sempre reply.","enum":["reply"]},"reply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"description":"O identificador que volta no webhook quando o botão é tocado."},"title":{"type":"string","minLength":1,"maxLength":20,"description":"O rótulo do botão. Limite de 20 caracteres."}},"required":["id","title"],"additionalProperties":false}},"required":["type","reply"],"additionalProperties":false},"description":"Os botões de resposta. De um a três, o teto da Cloud API."}},"required":["buttons"],"additionalProperties":false}},"required":["type","body","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre list.","enum":["list"]},"header":{"description":"O cabeçalho, exibido acima do corpo.","type":"object","properties":{"type":{"type":"string","enum":["text","image","video","document"],"description":"O que o cabeçalho carrega."},"text":{"description":"O texto do cabeçalho, quando type é text.","type":"string","maxLength":60},"image":{"description":"A imagem do cabeçalho, quando type é image.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"video":{"description":"O vídeo do cabeçalho, quando type é video.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"document":{"description":"O documento do cabeçalho, quando type é document.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"filename":{"type":"string","maxLength":240}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"button":{"type":"string","minLength":1,"maxLength":20,"description":"O rótulo do botão que abre a lista. Limite de 20 caracteres."},"sections":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"description":"O título da seção.","type":"string","maxLength":24},"rows":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"O identificador que volta no webhook quando a linha é escolhida."},"title":{"type":"string","minLength":1,"maxLength":24,"description":"O título da linha."},"description":{"description":"A descrição da linha.","type":"string","maxLength":72}},"required":["id","title"],"additionalProperties":false},"description":"As linhas da seção. De uma a dez."}},"required":["rows"],"additionalProperties":false},"description":"As seções da lista. De uma a dez, o teto da Cloud API."}},"required":["button","sections"],"additionalProperties":false}},"required":["type","body","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre cta_url.","enum":["cta_url"]},"header":{"description":"O cabeçalho, exibido acima do corpo.","type":"object","properties":{"type":{"type":"string","enum":["text","image","video","document"],"description":"O que o cabeçalho carrega."},"text":{"description":"O texto do cabeçalho, quando type é text.","type":"string","maxLength":60},"image":{"description":"A imagem do cabeçalho, quando type é image.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"video":{"description":"O vídeo do cabeçalho, quando type é video.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"document":{"description":"O documento do cabeçalho, quando type é document.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"filename":{"type":"string","maxLength":240}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"name":{"default":"cta_url","description":"Sempre cta_url.","type":"string","enum":["cta_url"]},"parameters":{"type":"object","properties":{"display_text":{"type":"string","minLength":1,"maxLength":20,"description":"O rótulo do botão. Limite de 20 caracteres."},"url":{"type":"string","maxLength":2048,"format":"uri","description":"O endereço que o botão abre."}},"required":["display_text","url"],"additionalProperties":false}},"required":["parameters"],"additionalProperties":false}},"required":["type","body","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre location_request_message.","enum":["location_request_message"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"action":{"default":{"name":"send_location"},"description":"Pode ser omitida: a ação desta mensagem é sempre send_location.","type":"object","properties":{"name":{"default":"send_location","description":"Sempre send_location.","type":"string","enum":["send_location"]}},"additionalProperties":false}},"required":["type","body"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre address_message.","enum":["address_message"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"name":{"default":"address_message","description":"Sempre address_message.","type":"string","enum":["address_message"]},"parameters":{"default":{"country":"BR"},"description":"Pode ser omitido: o formulário abre vazio, para o Brasil.","type":"object","properties":{"country":{"default":"BR","description":"O país do endereço, em duas letras (ISO 3166). O padrão é BR.","type":"string","pattern":"^[A-Za-z]{2}$"},"values":{"description":"Os campos do endereço já preenchidos, com os nomes que a Meta define para o país.","type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"anyOf":[{"type":"string","maxLength":300},{"type":"number"}]}},"saved_addresses":{"description":"Endereços salvos que o usuário pode escolher, no máximo vinte.","maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"O identificador do endereço salvo."},"value":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"anyOf":[{"type":"string","maxLength":300},{"type":"number"}]},"description":"Os campos do endereço salvo."}},"required":["id","value"],"additionalProperties":false}},"validation_errors":{"description":"Mensagens de erro por campo, para quando você devolve o formulário depois de uma validação.","type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":300}}},"additionalProperties":false}},"additionalProperties":false}},"required":["type","body","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre carousel.","enum":["carousel"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"action":{"type":"object","properties":{"cards":{"minItems":2,"maxItems":10,"type":"array","items":{"type":"object","properties":{"card_index":{"type":"integer","minimum":0,"maximum":9,"description":"A posição do cartão, de 0 a 9. Não repita."},"type":{"default":"cta_url","description":"Sempre cta_url.","type":"string","enum":["cta_url"]},"header":{"type":"object","properties":{"type":{"type":"string","enum":["image","video"],"description":"O que o cartão mostra."},"image":{"description":"A imagem do cartão, quando type é image.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"video":{"description":"O vídeo do cartão, quando type é video.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false}},"required":["type"],"additionalProperties":false,"description":"A mídia do cartão."},"body":{"description":"O texto do cartão.","type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":160,"description":"O texto do cartão. Limite de 160 caracteres."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"name":{"default":"cta_url","description":"Sempre cta_url.","type":"string","enum":["cta_url"]},"parameters":{"type":"object","properties":{"display_text":{"type":"string","minLength":1,"maxLength":20,"description":"O rótulo do botão. Limite de 20 caracteres."},"url":{"type":"string","maxLength":2048,"format":"uri","description":"O endereço que o botão abre."}},"required":["display_text","url"],"additionalProperties":false}},"required":["parameters"],"additionalProperties":false}},"required":["card_index","header","action"],"additionalProperties":false},"description":"Os cartões, de dois a dez."}},"required":["cards"],"additionalProperties":false}},"required":["type","body","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre flow.","enum":["flow"]},"header":{"description":"O cabeçalho, exibido acima do corpo.","type":"object","properties":{"type":{"type":"string","enum":["text","image","video","document"],"description":"O que o cabeçalho carrega."},"text":{"description":"O texto do cabeçalho, quando type é text.","type":"string","maxLength":60},"image":{"description":"A imagem do cabeçalho, quando type é image.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"video":{"description":"O vídeo do cabeçalho, quando type é video.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"}},"additionalProperties":false},"document":{"description":"O documento do cabeçalho, quando type é document.","type":"object","properties":{"id":{"description":"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.","type":"string","minLength":1,"maxLength":128},"link":{"description":"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.","type":"string","maxLength":2048,"format":"uri"},"filename":{"type":"string","maxLength":240}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"name":{"default":"flow","description":"Sempre flow.","type":"string","enum":["flow"]},"parameters":{"type":"object","properties":{"flow_message_version":{"default":"3","description":"A versão do formato da mensagem de Flow. O padrão é 3, a corrente na Meta.","type":"string","minLength":1,"maxLength":8},"flow_id":{"description":"O identificador do Flow. Use este OU flow_name.","type":"string","minLength":1,"maxLength":64},"flow_name":{"description":"O nome do Flow. Use este OU flow_id.","type":"string","minLength":1,"maxLength":200},"flow_cta":{"type":"string","minLength":1,"maxLength":40,"description":"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)."},"flow_token":{"description":"O que você quer receber de volta na resposta do Flow, para ligá-la a este envio.","type":"string","maxLength":256},"flow_action":{"description":"navigate (padrão da Meta) ou data_exchange.","type":"string","minLength":1,"maxLength":32},"flow_action_payload":{"description":"A tela e os dados de abertura, quando flow_action é navigate.","type":"object","properties":{"screen":{"type":"string","minLength":1,"maxLength":200,"description":"A tela do Flow que abre primeiro."},"data":{"description":"Os dados que o Flow recebe nessa tela.","type":"object","propertyNames":{"type":"string","maxLength":128},"additionalProperties":{}}},"required":["screen"],"additionalProperties":false},"mode":{"description":"draft para testar um Flow ainda não publicado, ou published (padrão da Meta).","type":"string","minLength":1,"maxLength":16}},"required":["flow_cta"],"additionalProperties":false}},"required":["parameters"],"additionalProperties":false}},"required":["type","body","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre product.","enum":["product"]},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"catalog_id":{"type":"string","minLength":1,"maxLength":64,"description":"O identificador do catálogo na conta de negócio do número (catalog_id da Meta)."},"product_retailer_id":{"type":"string","minLength":1,"maxLength":256,"description":"O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta)."}},"required":["catalog_id","product_retailer_id"],"additionalProperties":false}},"required":["type","action"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","description":"Sempre product_list.","enum":["product_list"]},"header":{"type":"object","properties":{"type":{"type":"string","description":"Sempre text: a lista de produtos só aceita cabeçalho de texto.","enum":["text"]},"text":{"type":"string","minLength":1,"maxLength":60,"description":"O texto do cabeçalho. Limite de 60 caracteres."}},"required":["type","text"],"additionalProperties":false,"description":"O cabeçalho, obrigatório na lista de produtos e sempre de texto."},"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"O texto do corpo."}},"required":["text"],"additionalProperties":false,"description":"O corpo da mensagem interativa."},"footer":{"description":"O rodapé, exibido abaixo dos botões.","type":"object","properties":{"text":{"type":"string","maxLength":60,"description":"O texto do rodapé."}},"required":["text"],"additionalProperties":false},"action":{"type":"object","properties":{"catalog_id":{"type":"string","minLength":1,"maxLength":64,"description":"O identificador do catálogo na conta de negócio do número (catalog_id da Meta)."},"sections":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"description":"O título da seção. Obrigatório quando há mais de uma seção. Limite de 24 caracteres.","type":"string","minLength":1,"maxLength":24},"product_items":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"type":"string","minLength":1,"maxLength":256,"description":"O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta)."}},"required":["product_retailer_id"],"additionalProperties":false},"description":"Os produtos da seção."}},"required":["product_items"],"additionalProperties":false},"description":"As seções da lista de produtos, com no máximo 30 produtos no total."}},"required":["catalog_id","sections"],"additionalProperties":false}},"required":["type","header","body","action"],"additionalProperties":false}],"description":"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)."}},"required":["from","type","interactive"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"interactive","interactive":{"type":"button","body":{"text":"Podemos confirmar a entrega para amanhã?"},"action":{"buttons":[{"type":"reply","reply":{"id":"confirma","title":"Confirmar"}},{"type":"reply","reply":{"id":"remarca","title":"Remarcar"}}]}}}},{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"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."},"to":{"description":"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.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"recipient":{"description":"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.","type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"},"context":{"description":"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.","type":"object","properties":{"message_id":{"type":"string","minLength":1,"maxLength":256,"description":"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."}},"required":["message_id"],"additionalProperties":false},"callbackData":{"description":"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.","type":"string","minLength":1,"maxLength":512},"typingMs":{"description":"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.","type":"integer","minimum":1,"maximum":25000},"type":{"type":"string","description":"Sempre template.","enum":["template"]},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":512,"description":"O nome do template já aprovado pela Meta."},"language":{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":16,"description":"O código do idioma do template, como pt_BR. Ele precisa bater com o aprovado."}},"required":["code"],"additionalProperties":false},"components":{"description":"Os componentes que preenchem as variáveis do template.","maxItems":32,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["header","body","button"],"description":"Qual parte do template este componente preenche."},"sub_type":{"description":"O subtipo, exigido pela Cloud API quando type é button.","type":"string","maxLength":64},"index":{"description":"A posição do botão, exigida pela Cloud API quando type é button.","type":"string","maxLength":8},"parameters":{"description":"Os valores das variáveis desta parte, na forma que a Cloud API define.","maxItems":64,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["type"],"additionalProperties":false}}},"required":["name","language"],"additionalProperties":false}},"required":["from","type","template"],"additionalProperties":false,"example":{"from":"1000000000000001","to":"5511900000000","type":"template","template":{"name":"confirmacao_de_pedido","language":{"code":"pt_BR"},"components":[{"type":"body","parameters":[{"type":"text","parameter_name":"nome","text":"Ana"}]}]}}}],"description":"O pedido de envio de mensagem. O campo type diz qual é o tipo; um corpo sem type é interpretado como texto."}}},"description":"O pedido de envio de mensagem. O campo type diz qual é o tipo; um corpo sem type é interpretado como texto."},"responses":{"202":{"description":"Accepted: the request was recorded and will be processed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"O identificador da mensagem na Luna. Ele existe antes de a Meta responder."},"status":{"type":"string","description":"Sempre queued: a mensagem foi aceita e está na fila de saída.","enum":["queued"]}},"required":["id","status"],"additionalProperties":false,"example":{"id":"ae60f288-7565-4315-a440-3663e9c231e1","status":"queued"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"window_closed":{"summary":"Service window closed","value":{"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_not_approved":{"summary":"Template that is not approved yet","value":{"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_reused":{"summary":"Idempotency-Key used with another body","value":{"error":"idempotency_key_reused","docsUrl":"https://lunahia.com.br/docs/enviar-mensagens","message":"Esta Idempotency-Key já foi usada com outro corpo. Nada foi enviado. Use uma chave nova para uma mensagem nova, e reenvie o mesmo corpo para repetir a original."}},"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"queue_full":{"summary":"Send queue full","value":{"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."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages"}},"get":{"summary":"List messages","tags":["Messages"],"description":"The record of what came in and what went out, newest first. Each message carries the number, the customer label, the conversation and, when it failed, the error summary. Filters: phoneNumberId, externalId, conversationId, waId, userId, wamid, direction, status, since and until. A parameter the route does not know answers 400. format=csv answers text/csv, with the same filters.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false,"description":"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."},{"schema":{"type":"string","enum":["json","csv"]},"in":"query","name":"format","required":false,"description":"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."},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"query","name":"phoneNumberId","required":false,"description":"O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","required":false,"description":"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."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"query","name":"conversationId","required":false},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"waId","required":false,"description":"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."},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"userId","required":false,"description":"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."},{"schema":{"type":"string","enum":["inbound","outbound"]},"in":"query","name":"direction","required":false,"description":"inbound: só o que chegou. outbound: só o que você enviou."},{"schema":{"type":"string","minLength":1,"maxLength":32},"in":"query","name":"status","required":false,"description":"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."},{"schema":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}]},"in":"query","name":"since","required":false,"description":"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)."},{"schema":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}]},"in":"query","name":"until","required":false,"description":"Só as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until)."},{"schema":{"type":"string","minLength":1,"maxLength":512},"in":"query","name":"wamid","required":false,"description":"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."},{"schema":{"type":"string","maxLength":256},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"direction":{"type":"string"},"wamid":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"bodyText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"content":{"anyOf":[{"type":"object","properties":{"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou."},"media":{"anyOf":[{"type":"object","properties":{"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do arquivo. Só documento tem."},"voice":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem."},"animated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a figurinha é animada. Só figurinha tem."}},"required":["mime_type","sha256","caption","filename","voice","animated"],"additionalProperties":false,"description":"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."},{"type":"null"}]},"interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow)."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do item da lista. Nula nos demais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do Flow. Só em nfm_reply."},"response_json":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply."}},"required":["type","id","title","description","name","response_json"],"additionalProperties":false,"description":"A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu."},{"type":"null"}]},"button":{"anyOf":[{"type":"object","properties":{"payload":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O payload que você definiu no botão de resposta rápida do template."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do botão."}},"required":["payload","text"],"additionalProperties":false,"description":"O clique num botão de resposta rápida de um template."},{"type":"null"}]},"location":{"anyOf":[{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A latitude, em graus decimais."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A longitude, em graus decimais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do lugar, quando o interlocutor escolheu um."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço, quando há."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço web do lugar, quando há."}},"required":["latitude","longitude","name","address","url"],"additionalProperties":false,"description":"A localização que o interlocutor compartilhou."},{"type":"null"}]},"contacts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"object","properties":{"formatted_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["formatted_name","first_name","last_name","middle_name","prefix","suffix"],"additionalProperties":false},{"type":"null"}],"description":"O nome do contato, nos campos da Meta."},"phones":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"wa_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","wa_id","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp."},"emails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os e-mails do contato."},"org":{"anyOf":[{"type":"object","properties":{"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"department":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["company","department","title"],"additionalProperties":false},{"type":"null"}],"description":"A organização do contato."}},"required":["name","phones","emails","org"],"additionalProperties":false}},{"type":"null"}],"description":"Os cartões de contato que o interlocutor compartilhou."},"reaction":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que recebeu a reação."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O emoji. Nulo quando o interlocutor retirou a reação."}},"required":["wamid","emoji"],"additionalProperties":false,"description":"A reação a uma mensagem, ou a retirada dela."},{"type":"null"}]},"context":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor citou ao responder."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem enviou a mensagem citada."},"forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada."},"frequently_forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada muitas vezes."}},"required":["wamid","from","forwarded","frequently_forwarded"],"additionalProperties":false,"description":"A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada."},{"type":"null"}]},"referral":{"anyOf":[{"type":"object","properties":{"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A origem do clique, como ad ou post."},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do anúncio ou da publicação na Meta."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do anúncio ou da publicação."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do anúncio."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do anúncio."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mídia do anúncio, como image ou video."},"ctwa_clid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do clique, para atribuição de conversão."}},"required":["source_type","source_id","source_url","headline","body","media_type","ctwa_clid"],"additionalProperties":false,"description":"O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever."},{"type":"null"}]},"unsupported":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta, como ela mandou (131051 é \"tipo de mensagem sem suporte\")."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o mandou."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O detalhe do erro, como a Meta o mandou."}},"required":["code","title","details"],"additionalProperties":false,"description":"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\"."},{"type":"null"}]},"edit":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que foi editada."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do conteúdo novo, como text."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto novo, quando o conteúdo novo é texto."}},"required":["wamid","type","text"],"additionalProperties":false,"description":"Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit)."},{"type":"null"}]},"revoke":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor apagou para todos."}},"required":["wamid"],"additionalProperties":false,"description":"Presente quando o interlocutor apagou uma mensagem para todos (type é revoke)."},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde veio o pedido."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto que o interlocutor escreveu junto com o pedido."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do produto no seu catálogo."},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A quantidade pedida, como a Meta mandou."},"item_price":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O preço unitário, como a Meta mandou."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda do preço."}},"required":["product_retailer_id","quantity","item_price","currency"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens do pedido."}},"required":["catalog_id","text","items"],"additionalProperties":false,"description":"O pedido que o interlocutor montou num catálogo e enviou (type é order)."},{"type":"null"}]},"template":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do template que você enviou."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O idioma do template, no código da Meta (por exemplo pt_BR)."},"variables":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"component":{"type":"string","description":"Onde a variável entra: header, body ou button."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da variável, quando o template usa variáveis nomeadas. Nulo nas posicionais, em que a ordem na lista é a posição."},"value":{"type":"string","description":"O valor que você mandou. Parâmetro de imagem, vídeo ou documento não aparece: o link do arquivo não é devolvido."}},"required":["component","name","value"],"additionalProperties":false}},{"type":"null"}],"description":"Os valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum."}},"required":["name","language","variables"],"additionalProperties":false,"description":"O template que você enviou, com os valores que preencheram as variáveis."},{"type":"null"}]},"sent_interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list."},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do corpo."},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do rodapé."},"buttons":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title"],"additionalProperties":false}},{"type":"null"}],"description":"Os botões de resposta (id e título). Só em type button."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","description"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens da lista, de todas as seções (id, título e descrição). Só em type list."},"cta":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","url"],"additionalProperties":false},{"type":"null"}],"description":"O botão de chamada: o rótulo e, no cta_url, o endereço que ele abre. No flow, só o rótulo."},"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde vêm os produtos. Só em type product e product_list."},"products":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"section":{"anyOf":[{"type":"string"},{"type":"null"}]},"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["section","product_retailer_id"],"additionalProperties":false}},{"type":"null"}],"description":"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."}},"required":["type","header","body","footer","buttons","items","cta","catalog_id","products"],"additionalProperties":false,"description":"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."},{"type":"null"}]}},"required":["profile_name","media","interactive","button","location","contacts","reaction","context","referral","unsupported","edit","revoke","order","template","sent_interactive"],"additionalProperties":false,"description":"O conteúdo da mensagem além do texto, nos dois sentidos. Recebida: mídia com legenda, botão ou item escolhido, 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, curado. Em template, o nome, o idioma e os valores das variáveis; em sent_interactive, o corpo, os botões ou itens e o endereço do botão de URL; em media, a legenda e o nome do arquivo (sem o link); em location, reaction e contacts, o mesmo que a recebida; em context, a mensagem citada. Todo campo está sempre presente, e é nulo quando não se aplica. O content é nulo em mensagem de texto enviada (o texto está em bodyText), e em mensagem anterior à plataforma guardar o conteúdo."},{"type":"null"}],"description":"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."},"callbackData":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"pricing":{"anyOf":[{"type":"object","properties":{"billable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos."},"pricing_model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O modelo de preço da Meta, como ela informou (hoje PMP ou CBP)."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer."}},"required":["billable","pricing_model","type","category"],"additionalProperties":false},{"type":"null"}],"description":"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."},"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do interlocutor, como a Meta o mandou. Nulo quando a Meta nunca o mandou para esta conversa."},"parentUserId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais."},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome de usuário do interlocutor, quando ele adotou um. Nulo no demais."},"displayNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"numberId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}],"description":"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."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"conversationId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}],"description":"A conversa da mensagem, o mesmo id de GET /v1/conversations. Nulo quando não há conversa resolvida."},"errorSummary":{"anyOf":[{"type":"object","properties":{"codigo":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O código do erro da Meta, quando ela mandou um."},"mensagem":{"type":"string","description":"O que aconteceu, em português."},"acaoRecomendada":{"type":"string","description":"O que fazer a respeito, em português."}},"required":["codigo","mensagem","acaoRecomendada"],"additionalProperties":false},{"type":"null"}],"description":"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."},"createdAt":{"type":"string"}},"required":["id","direction","wamid","type","bodyText","content","callbackData","status","pricing","waId","userId","parentUserId","username","displayNumber","numberId","externalId","conversationId","errorSummary","createdAt"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim."}},"required":["data","nextCursor"],"additionalProperties":false,"example":{"data":[{"id":"ae60f288-7565-4315-a440-3663e9c231e1","direction":"outbound","wamid":"wamid.HBgMNTUzMTgwMzYwMjEwFQIAERgSQjczNEE1OEVDMDgyMTJCMjA2AA==","type":"text","bodyText":"Olá! Recebemos seu pedido e já estamos preparando.","content":null,"callbackData":"atendimento-8841","status":"read","pricing":{"billable":true,"pricing_model":"PMP","type":"regular","category":"utility"},"waId":"5511900000000","userId":"BR.13491208655302741918","parentUserId":null,"username":null,"displayNumber":"+55 11 90000-0000","numberId":"a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d","externalId":"cliente-8841","conversationId":"2d9f6a41-0c5b-4e7a-8f13-9b6c4d2e1a07","errorSummary":null,"createdAt":"2026-08-07T12:24:02.085Z"},{"id":"b6d84033-a8e8-4db9-aab6-565ce203cc51","direction":"inbound","wamid":"wamid.HBgMNTUzMTgwMzYwMjEwFQIAEhgUM0FCMEFBNDUzNzg4NzY5MUQ5MTUA","type":"text","bodyText":"oi","content":null,"callbackData":null,"status":null,"pricing":null,"waId":"5511900000000","userId":"BR.13491208655302741918","parentUserId":null,"username":null,"displayNumber":"+55 11 90000-0000","numberId":"a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d","externalId":"cliente-8841","conversationId":"2d9f6a41-0c5b-4e7a-8f13-9b6c4d2e1a07","errorSummary":null,"createdAt":"2026-08-07T11:35:10.000Z"}],"nextCursor":null}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-get-v1-messages"}}},"/v1/conversations":{"get":{"summary":"List conversations","tags":["Conversations"],"description":"One row per correspondent per number, from the most active to the most idle.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"query","name":"phoneNumberId","required":false,"description":"O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","required":false,"description":"O rótulo que você deu ao seu cliente (externalId): só as conversas dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia."},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"waId","required":false,"description":"O identificador do interlocutor no WhatsApp (o waId da conversa, em geral o telefone só com dígitos): só as conversas dele, em cada número. Igualdade exata, mas o celular brasileiro vale nas duas grafias, com e sem o 9 depois do DDD (a Meta entrega alguns sem ele); um waId sem conversa devolve lista vazia."},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"userId","required":false,"description":"O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só a conversa dele, em cada número. Igualdade exata; um userId sem conversa devolve lista vazia."},{"schema":{"type":"string","maxLength":256},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O telefone do interlocutor (wa_id da Meta), cru. Nulo quando o interlocutor escreveu só com BSUID, caso em que userId o identifica. Mudou de obrigatório para anulável com o BSUID: quem lia como texto sempre presente precisa tratar o nulo."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do interlocutor, como a Meta o mandou (por exemplo US.13491208655302741918). Nulo quando a Meta nunca o mandou para esta conversa, como nas conversas anteriores ao BSUID que ainda não receberam mensagem com ele."},"parentUserId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais."},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome de usuário do interlocutor, quando ele adotou um. Nulo no demais."},"phoneNumberId":{"type":"string"},"numberId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"O número da Luna a que a conversa pertence, o mesmo id de GET /v1/numbers. É o mesmo valor de phoneNumberId, com o nome que o resto da API usa."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId do número da conversa, o rótulo que você deu ao seu cliente. Nulo quando o número não tem."},"contactName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp, como a Meta o mandou na última mensagem recebida que trouxe um. Nulo quando ele nunca mandou o nome, ou quando a conversa não tem mensagem recebida guardada."},"displayNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"lastMessage":{"anyOf":[{"type":"object","properties":{"direction":{"type":"string"},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"bodyText":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["direction","type","bodyText","createdAt"],"additionalProperties":false},{"type":"null"}]},"windowOpen":{"type":"boolean","description":"Verdadeiro quando você pode mandar mensagem livre para este interlocutor agora. Falso significa que o caminho é enviar um template, e a mensagem livre volta a ser aceita quando o contato responder."},"windowExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Instante em que a janela de atendimento fecha, em ISO-8601. Nulo quando não há janela conhecida, e nesse caso windowOpen é falso."},"windowSource":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que abriu a janela: usuario quando o interlocutor escreveu, anuncio quando ele veio de um anúncio ou botão de página, e desconhecido quando a origem não foi identificada. O valor template existe no vocabulário e não é mais gravado: enviar um template não abre a janela. Nulo quando não há janela conhecida."}},"required":["id","waId","userId","parentUserId","username","phoneNumberId","numberId","externalId","contactName","displayNumber","createdAt","lastMessage","windowOpen","windowExpiresAt","windowSource"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim."}},"required":["data","nextCursor"],"additionalProperties":false,"example":{"data":[{"id":"0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12","waId":"5511900000000","userId":"BR.13491208655302741918","parentUserId":null,"username":null,"phoneNumberId":"7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11","numberId":"7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11","externalId":"cliente-8841","contactName":"Maria Souza","displayNumber":"+55 11 90000-0000","createdAt":"2026-08-07T11:35:10.000Z","lastMessage":{"direction":"outbound","type":"text","bodyText":"Olá! Recebemos seu pedido e já estamos preparando.","createdAt":"2026-08-07T12:24:02.085Z"},"windowOpen":true,"windowExpiresAt":"2026-08-08T11:35:10.000Z","windowSource":"usuario"}],"nextCursor":null}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-get-v1-conversations"}}},"/v1/messages/{id}/media":{"get":{"summary":"Get a message's media","tags":["Media"],"description":"Returns a signed URL, issued by Luna, to download media that has already been persisted.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"id","required":true,"description":"O identificador da mensagem na Luna, como GET /v1/messages o devolve."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"URL assinada para baixar o arquivo. É credencial de portador: quem a tiver baixa, sem apresentar chave. Não guarde, não registre em log. Ela aponta para o armazenamento da Luna e nunca para a Meta, e sai no domínio da API de objetos do provedor, porque URL assinada não funciona com domínio customizado."},"expiraEm":{"type":"string","description":"Instante em que a URL deixa de valer, em ISO-8601 UTC. Depois dele, chame a rota de novo."}},"required":["url","expiraEm"],"additionalProperties":false,"example":{"url":"https://c1b129d42065073c6f8b203801c44b2d.r2.cloudflarestorage.com/lunabucket/midia/ae60f288-7565-4315-a440-3663e9c231e1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=EXEMPLO","expiraEm":"2026-08-24T12:29:02.085Z"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"media_not_ready":{"summary":"Media not fetched yet","value":{"error":"media_not_ready","docsUrl":"https://lunahia.com.br/docs/enviar-mensagens","message":"A mídia desta mensagem ainda não está disponível.","estado":"pendente"}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-get-v1-messages-id-media"}}},"/v1/media/{token}":{"get":{"summary":"Download media through the notice link","tags":["Media"],"description":"The link that comes in media.url on the message.received and message.echo notices. It asks for no API key: the token in the address is the credential. Ready media answers 302 to a short-lived signed URL; media still being downloaded from Meta, 409 with Retry-After; a token that does not exist or has expired, 404.","parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true,"description":"O token do link, como veio em media.url."}],"responses":{"302":{"description":"Redirect: follow the Location header, which leads to the signed URL of the file."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"media_not_ready":{"summary":"Media not fetched yet","value":{"error":"media_not_ready","docsUrl":"https://lunahia.com.br/docs/enviar-mensagens","message":"A mídia desta mensagem ainda não está disponível.","estado":"pendente"}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-get-v1-media-token"}}},"/v1/messages/{id}/read":{"post":{"summary":"Mark a message as read","tags":["Messages"],"description":"Marks a message you received as read on Meta, and returns 200 once it accepts.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"id","required":true,"description":"O identificador da mensagem na Luna, como GET /v1/messages o devolve."}],"responses":{"200":{"description":"A Meta aceitou a marcação.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false,"description":"A Meta aceitou a marcação."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"number_rate_limited":{"summary":"Number pace","value":{"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."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages-id-read"}}},"/v1/messages/{id}/typing":{"post":{"summary":"Show the typing indicator","tags":["Messages"],"description":"Shows the recipient that you are writing, and returns 200 once Meta accepts.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"id","required":true,"description":"O identificador da mensagem na Luna, como GET /v1/messages o devolve."}],"responses":{"200":{"description":"A Meta aceitou o indicador.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false,"description":"A Meta aceitou o indicador."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"number_rate_limited":{"summary":"Number pace","value":{"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."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages-id-typing"}}},"/v1/numbers/{id}/media":{"post":{"summary":"Upload a file and get its media identifier","tags":["Media"],"description":"Takes a file in multipart/form-data under the field file, uploads it to Meta and returns its identifier.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"type":"string","description":"O identificador do arquivo na Meta. Use-o no lugar de link ao enviar mídia: a Meta não precisa baixar nada da sua infraestrutura, e você reaproveita o mesmo arquivo em várias mensagens. Ele vale 30 dias; depois disso, suba o arquivo de novo."}},"required":["mediaId"],"additionalProperties":false,"example":{"mediaId":"1425835918205946"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"413":{"description":"The file is over the size ceiling, which is the same for every customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"file_too_large":{"summary":"File over the ceiling","value":{"error":"file_too_large","docsUrl":"https://lunahia.com.br/docs/enviar-mensagens","message":"O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-post-v1-numbers-id-media"},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload, in the file field."}},"required":["file"]}}}}}},"/v1/messages/{id}":{"get":{"summary":"Read one message's state","tags":["Messages"],"description":"Returns the message's current state, the timestamp of each step, and what Meta said whenever it refused something.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"id","required":true,"description":"O identificador da mensagem na Luna, como GET /v1/messages o devolve."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"O identificador da mensagem na Luna."},"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"content":{"anyOf":[{"type":"object","properties":{"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou."},"media":{"anyOf":[{"type":"object","properties":{"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do arquivo. Só documento tem."},"voice":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem."},"animated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a figurinha é animada. Só figurinha tem."}},"required":["mime_type","sha256","caption","filename","voice","animated"],"additionalProperties":false,"description":"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."},{"type":"null"}]},"interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow)."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do item da lista. Nula nos demais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do Flow. Só em nfm_reply."},"response_json":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply."}},"required":["type","id","title","description","name","response_json"],"additionalProperties":false,"description":"A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu."},{"type":"null"}]},"button":{"anyOf":[{"type":"object","properties":{"payload":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O payload que você definiu no botão de resposta rápida do template."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do botão."}},"required":["payload","text"],"additionalProperties":false,"description":"O clique num botão de resposta rápida de um template."},{"type":"null"}]},"location":{"anyOf":[{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A latitude, em graus decimais."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A longitude, em graus decimais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do lugar, quando o interlocutor escolheu um."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço, quando há."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço web do lugar, quando há."}},"required":["latitude","longitude","name","address","url"],"additionalProperties":false,"description":"A localização que o interlocutor compartilhou."},{"type":"null"}]},"contacts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"object","properties":{"formatted_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["formatted_name","first_name","last_name","middle_name","prefix","suffix"],"additionalProperties":false},{"type":"null"}],"description":"O nome do contato, nos campos da Meta."},"phones":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"wa_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","wa_id","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp."},"emails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os e-mails do contato."},"org":{"anyOf":[{"type":"object","properties":{"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"department":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["company","department","title"],"additionalProperties":false},{"type":"null"}],"description":"A organização do contato."}},"required":["name","phones","emails","org"],"additionalProperties":false}},{"type":"null"}],"description":"Os cartões de contato que o interlocutor compartilhou."},"reaction":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que recebeu a reação."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O emoji. Nulo quando o interlocutor retirou a reação."}},"required":["wamid","emoji"],"additionalProperties":false,"description":"A reação a uma mensagem, ou a retirada dela."},{"type":"null"}]},"context":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor citou ao responder."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem enviou a mensagem citada."},"forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada."},"frequently_forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada muitas vezes."}},"required":["wamid","from","forwarded","frequently_forwarded"],"additionalProperties":false,"description":"A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada."},{"type":"null"}]},"referral":{"anyOf":[{"type":"object","properties":{"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A origem do clique, como ad ou post."},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do anúncio ou da publicação na Meta."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do anúncio ou da publicação."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do anúncio."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do anúncio."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mídia do anúncio, como image ou video."},"ctwa_clid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do clique, para atribuição de conversão."}},"required":["source_type","source_id","source_url","headline","body","media_type","ctwa_clid"],"additionalProperties":false,"description":"O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever."},{"type":"null"}]},"unsupported":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta, como ela mandou (131051 é \"tipo de mensagem sem suporte\")."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o mandou."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O detalhe do erro, como a Meta o mandou."}},"required":["code","title","details"],"additionalProperties":false,"description":"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\"."},{"type":"null"}]},"edit":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que foi editada."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do conteúdo novo, como text."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto novo, quando o conteúdo novo é texto."}},"required":["wamid","type","text"],"additionalProperties":false,"description":"Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit)."},{"type":"null"}]},"revoke":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor apagou para todos."}},"required":["wamid"],"additionalProperties":false,"description":"Presente quando o interlocutor apagou uma mensagem para todos (type é revoke)."},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde veio o pedido."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto que o interlocutor escreveu junto com o pedido."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do produto no seu catálogo."},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A quantidade pedida, como a Meta mandou."},"item_price":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O preço unitário, como a Meta mandou."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda do preço."}},"required":["product_retailer_id","quantity","item_price","currency"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens do pedido."}},"required":["catalog_id","text","items"],"additionalProperties":false,"description":"O pedido que o interlocutor montou num catálogo e enviou (type é order)."},{"type":"null"}]},"template":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do template que você enviou."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O idioma do template, no código da Meta (por exemplo pt_BR)."},"variables":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"component":{"type":"string","description":"Onde a variável entra: header, body ou button."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da variável, quando o template usa variáveis nomeadas. Nulo nas posicionais, em que a ordem na lista é a posição."},"value":{"type":"string","description":"O valor que você mandou. Parâmetro de imagem, vídeo ou documento não aparece: o link do arquivo não é devolvido."}},"required":["component","name","value"],"additionalProperties":false}},{"type":"null"}],"description":"Os valores das variáveis, na ordem em que você os mandou. Nulo quando o envio não levou nenhum."}},"required":["name","language","variables"],"additionalProperties":false,"description":"O template que você enviou, com os valores que preencheram as variáveis."},{"type":"null"}]},"sent_interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mensagem interativa: button, list, cta_url, location_request_message, address_message, carousel, flow, product ou product_list."},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do cabeçalho. Nulo quando não há, ou quando o cabeçalho é mídia."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do corpo."},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do rodapé."},"buttons":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title"],"additionalProperties":false}},{"type":"null"}],"description":"Os botões de resposta (id e título). Só em type button."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","description"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens da lista, de todas as seções (id, título e descrição). Só em type list."},"cta":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","url"],"additionalProperties":false},{"type":"null"}],"description":"O botão de chamada: o rótulo e, no cta_url, o endereço que ele abre. No flow, só o rótulo."},"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde vêm os produtos. Só em type product e product_list."},"products":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"section":{"anyOf":[{"type":"string"},{"type":"null"}]},"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["section","product_retailer_id"],"additionalProperties":false}},{"type":"null"}],"description":"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."}},"required":["type","header","body","footer","buttons","items","cta","catalog_id","products"],"additionalProperties":false,"description":"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."},{"type":"null"}]}},"required":["profile_name","media","interactive","button","location","contacts","reaction","context","referral","unsupported","edit","revoke","order","template","sent_interactive"],"additionalProperties":false,"description":"O conteúdo da mensagem além do texto, nos dois sentidos. Recebida: mídia com legenda, botão ou item escolhido, 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, curado. Em template, o nome, o idioma e os valores das variáveis; em sent_interactive, o corpo, os botões ou itens e o endereço do botão de URL; em media, a legenda e o nome do arquivo (sem o link); em location, reaction e contacts, o mesmo que a recebida; em context, a mensagem citada. Todo campo está sempre presente, e é nulo quando não se aplica. O content é nulo em mensagem de texto enviada (o texto está em bodyText), e em mensagem anterior à plataforma guardar o conteúdo."},{"type":"null"}],"description":"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."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O estado atual da entrega, como a Meta o reportou por último. Nulo quando nenhum evento de status chegou ainda."},"criadaEm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a Luna aceitou a mensagem, em ISO-8601 UTC."},"enviadaEm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a Meta confirmou o envio. Nulo enquanto isso não aconteceu."},"entregueEm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a mensagem chegou ao aparelho do destinatário. Nulo enquanto isso não aconteceu."},"lidaEm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o destinatário leu a mensagem. Nulo enquanto isso não aconteceu, e também quando ele desliga a confirmação de leitura."},"callbackData":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"pricing":{"anyOf":[{"type":"object","properties":{"billable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos."},"pricing_model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O modelo de preço da Meta, como ela informou (hoje PMP ou CBP)."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer."}},"required":["billable","pricing_model","type","category"],"additionalProperties":false},{"type":"null"}],"description":"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."},"erros":{"type":"array","items":{"type":"object","properties":{"codigo":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"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."},"categoria":{"type":"string","enum":["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"],"description":"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."},"mensagem":{"type":"string","description":"O que aconteceu, em português. É texto da Helsen, não a tradução da mensagem da Meta."},"acaoRecomendada":{"type":"string","description":"O que fazer a respeito, em português e em uma frase acionável."},"original":{"anyOf":[{},{"type":"null"}],"description":"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."}},"required":["codigo","categoria","mensagem","acaoRecomendada","original"],"additionalProperties":false,"example":{"codigo":131026,"categoria":"nao_entregavel","mensagem":"O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.","acaoRecomendada":"Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.","original":{"error":{"message":"Message undeliverable","type":"OAuthException","code":131026,"fbtrace_id":"AbCdEfGhIjK"}}}},"description":"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."}},"required":["id","wamid","content","status","criadaEm","enviadaEm","entregueEm","lidaEm","callbackData","pricing","erros"],"additionalProperties":false,"example":{"id":"ae60f288-7565-4315-a440-3663e9c231e1","wamid":null,"content":null,"status":"failed","criadaEm":"2026-08-24T12:24:02.085Z","enviadaEm":null,"entregueEm":null,"lidaEm":null,"callbackData":null,"pricing":null,"erros":[{"codigo":131026,"categoria":"nao_entregavel","mensagem":"O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.","acaoRecomendada":"Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.","original":{"error":{"message":"Message undeliverable","type":"OAuthException","code":131026,"fbtrace_id":"AbCdEfGhIjK"}}}]}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-get-v1-messages-id"}},"delete":{"summary":"Cancel a message in the queue","tags":["Messages"],"description":"Cancels a message still in the outbound queue (accepted) and answers 204. It moves to the terminal state canceled, and the message.status event with status canceled reaches your webhook. If the message already went to Meta or has an outcome, it answers 409 message_not_cancelable with the current state.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"id","required":true,"description":"O identificador da mensagem na Luna, como POST /v1/messages o devolveu."}],"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"message_not_cancelable":{"summary":"Message that already left the queue","value":{"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"}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-delete-v1-messages-id"}}},"/v1/messages/{id}/replay":{"post":{"summary":"Replay a message's webhook","tags":["Messages"],"description":"Asks for this message's event to be delivered to your endpoint again: the message.received if it was received, or the latest message.status if it was sent, with the same format and the same signature as the original. The response is 202: the request was recorded, and delivery happens asynchronously. A sent message that has no state yet, or that Meta has not accepted yet, answers 400.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"id","required":true,"description":"O identificador da mensagem na Luna, como GET /v1/messages o devolve."}],"responses":{"202":{"description":"O pedido de reenvio foi registrado. A entrega acontece de forma assíncrona, pelo mesmo caminho de sempre.","content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador desta entrega. Cada pedido gera um novo: o reenvio é entrega nova, e não reescrita de histórico."},"requestedAt":{"type":"string","description":"Quando o pedido foi registrado, em UTC."}},"required":["deliveryId","requestedAt"],"additionalProperties":false,"description":"O pedido de reenvio foi registrado. A entrega acontece de forma assíncrona, pelo mesmo caminho de sempre.","example":{"deliveryId":"9f2a1b0c-3d4e-4f5a-8b9c-0d1e2f3a4b5c","requestedAt":"2026-08-26T18:30:00.000Z"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"no_webhook_endpoint":{"summary":"No active webhook endpoint","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages-id-replay"}}},"/v1/meta-pricing":{"get":{"summary":"Read Meta's pricing rules","tags":["Account and plan"],"description":"The rules by which Meta charges for the use of WhatsApp to the business that owns the number, and the day Luna read them. It carries no monetary values: the rate table stays at Meta. Luna charges none of this.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"readAt":{"type":"string","description":"O dia em que as regras foram lidas na página de preços da Meta (AAAA-MM-DD). Mostre-o junto das regras: é o que diz o quão fresca é a informação."},"sourceUrl":{"type":"string","description":"A tabela de tarifas da Meta, que é a referência para qualquer valor."},"aiProvidersUrl":{"type":"string","description":"A política própria da Meta para assistentes de IA de uso geral (Provedores de IA)."},"rules":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"O identificador estável da regra, para o seu código comparar."},"title":{"type":"string"},"text":{"type":"string","description":"A regra, em português. Não traz valor em moeda."}},"required":["key","title","text"],"additionalProperties":false},"description":"As regras, na ordem em que devem aparecer."}},"required":["readAt","sourceUrl","aiProvidersUrl","rules"],"additionalProperties":false,"example":{"readAt":"2026-10-07","sourceUrl":"https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing","aiProvidersUrl":"https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers","rules":[{"key":"marketing_templates","title":"Template de marketing","text":"É sempre cobrado pela Meta, dentro ou fora da janela de 24 horas."}]}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"}},"/v1/test-mode/inbound-messages":{"post":{"summary":"Simulate a received message","tags":["Messages"],"description":"Delivers ONE example message.received to your webhook endpoints, signed and with test: true on the envelope, so you can exercise your code without waiting for a contact to write. The message goes out in about half a second, and nothing is stored or goes through a number of yours or through Meta. It works with the test key and with the regular key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"phoneNumberId":{"description":"O phone_number_id que aparece no evento. Texto livre: a Luna não procura o número. Ausente, 123456789012345.","type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"waId":{"description":"O telefone de quem \"escreveu\", só dígitos. Ausente, 5511900000000.","type":"string","pattern":"^[1-9]\\d{7,14}$"},"text":{"description":"O texto da mensagem recebida. Ausente, um texto de exemplo.","type":"string","minLength":1,"maxLength":4096}},"additionalProperties":false},{"type":"null"}]}}}},"responses":{"202":{"description":"Accepted: the request was recorded and will be processed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O id da mensagem simulada, o mesmo que vai em message.id do evento."},"wamid":{"type":"string","description":"O wamid simulado. Começa com wamid.TESTE_ para nunca se confundir com um da Meta."},"endpoints":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"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."}},"required":["id","wamid","endpoints"],"additionalProperties":false,"example":{"id":"3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14","wamid":"wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14","endpoints":1}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"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."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write"}},"/v1/numbers/{id}/profile":{"get":{"summary":"Read the business profile","tags":["Phone numbers"],"description":"The profile the contact sees on WhatsApp: about text, address, description, email, websites, vertical and the picture. It does not work on a number in coexistence.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O recado curto do perfil. Nulo quando não há.","example":"Atendimento de segunda a sexta"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do negócio."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do negócio."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O e-mail de contato."},"websites":{"type":"array","items":{"type":"string"},"description":"Os sites do negócio. Lista vazia quando não há."},"vertical":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O ramo de atividade, como a Meta o devolve. Texto da Meta, sem lista fechada aqui."},"profilePictureUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da foto do perfil. É da Meta e pode expirar: baixe o arquivo se precisar guardá-lo."}},"required":["about","address","description","email","websites","vertical","profilePictureUrl"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_available_in_coexistence":{"summary":"Unavailable in coexistence","value":{"error":"not_available_in_coexistence","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."}},"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"},"patch":{"summary":"Change the business profile","tags":["Phone numbers"],"description":"Changes the fields you send and leaves the others as they are. With displayName, it requests the display name change and answers 202: the name stays under review at Meta. It does not work on a number in coexistence.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"about":{"description":"O recado curto. Até 139 caracteres.","type":"string","minLength":1,"maxLength":139},"address":{"description":"O endereço. Até 256 caracteres.","type":"string","minLength":1,"maxLength":256},"description":{"description":"A descrição. Até 512 caracteres.","type":"string","minLength":1,"maxLength":512},"email":{"description":"O e-mail de contato. Até 128 caracteres.","type":"string","minLength":1,"maxLength":128},"websites":{"description":"Até dois sites. A lista inteira substitui a que existe.","maxItems":2,"type":"array","items":{"type":"string","maxLength":256,"format":"uri"}},"vertical":{"description":"O ramo de atividade, no vocabulário da Meta.","type":"string","minLength":1,"maxLength":64},"displayName":{"description":"Pede à Meta a mudança do nome de exibição (o nome que o contato vê no topo da conversa). A resposta é 202: o pedido está em revisão e displayNameStatus passa a pending_review. A Meta aceita até 10 mudanças a cada 30 dias, e é ela quem julga o nome. O evento number.display_name_reviewed avisa o resultado. Um nome aprovado só passa a valer depois que o número é registrado de novo.","type":"string","minLength":1,"maxLength":512},"profilePictureHandle":{"description":"O handle de uma foto que você subiu pelo envio resumível da Meta. O mesmo handle que POST /v1/template-assets devolve serve de foto do perfil, o que está a confirmar na doc da Meta.","type":"string","minLength":1,"maxLength":1024}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"updatedFields":{"type":"array","items":{"type":"string"},"description":"Os campos que a Meta aceitou trocar, pelos nomes que você mandou."}},"required":["updatedFields"],"additionalProperties":false}}}},"202":{"description":"Accepted: the request was recorded and will be processed.","content":{"application/json":{"schema":{"type":"object","properties":{"updatedFields":{"type":"array","items":{"type":"string"},"description":"Os campos que a Meta aceitou trocar, pelos nomes que você mandou."},"displayNameStatus":{"type":"string","description":"O nome foi pedido e está em revisão na Meta. O resultado chega no evento number.display_name_reviewed.","enum":["pending_review"]},"pendingDisplayName":{"type":"string","description":"O nome que você pediu."}},"required":["updatedFields","displayNameStatus","pendingDisplayName"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_available_in_coexistence":{"summary":"Unavailable in coexistence","value":{"error":"not_available_in_coexistence","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."}},"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:write"}},"/v1/numbers/{id}/blocked-users":{"post":{"summary":"Block users","tags":["Phone numbers"],"description":"Blocks people who wrote to the number in the last 24 hours. Each user is a phone number or a BSUID, and the response separates the ones Meta accepted from the ones it refused, with the reason.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"users":{"minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{7,14}$"},{"type":"string","pattern":"^[A-Za-z]{2}\\.(?:ENT\\.)?[0-9A-Za-z]{1,128}$"}],"description":"O telefone (só dígitos, sem o sinal de mais) ou o BSUID do usuário. O BSUID pai não bloqueia."},"description":"Os usuários a bloquear, de um a cinquenta."}},"required":["users"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"done":{"type":"array","items":{"type":"object","properties":{"input":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que você pediu, como a Meta o devolveu."},"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O telefone do usuário na Meta, quando ela o devolve."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do usuário, quando a Meta o devolve."},"reasons":{"type":"array","items":{"type":"string"},"description":"Só em failed: o motivo que a Meta deu. Texto dela."}},"required":["input","waId","userId","reasons"],"additionalProperties":false},"description":"Os usuários que a Meta aceitou bloquear ou desbloquear."},"failed":{"type":"array","items":{"type":"object","properties":{"input":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que você pediu, como a Meta o devolveu."},"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O telefone do usuário na Meta, quando ela o devolve."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do usuário, quando a Meta o devolve."},"reasons":{"type":"array","items":{"type":"string"},"description":"Só em failed: o motivo que a Meta deu. Texto dela."}},"required":["input","waId","userId","reasons"],"additionalProperties":false},"description":"Os que a Meta recusou, cada um com o motivo dela."}},"required":["done","failed"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write"},"get":{"summary":"List blocked users","tags":["Phone numbers"],"description":"Who this number has blocked, in pages. The cursor is Meta's, and its shape does not change.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Quantos por página, de 1 a 100."},{"schema":{"type":"string","minLength":1,"maxLength":512},"in":"query","name":"cursor","required":false,"description":"O nextCursor da página anterior."},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O telefone do usuário bloqueado."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do usuário bloqueado."}},"required":["waId","userId"],"additionalProperties":false},"description":"Os usuários bloqueados nesta página."},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cursor da próxima página, como a Meta o deu. Nulo quando acabou."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:read"}},"/v1/numbers/{id}/blocked-users/{user}":{"delete":{"summary":"Unblock a user","tags":["Phone numbers"],"description":"Unblocks a user, by the phone number or the BSUID in the path. It stays open on a suspended account: unblocking is never the problem.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."},{"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9.]+$"},"in":"path","name":"user","required":true,"description":"O telefone (só dígitos) ou o BSUID do usuário."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"done":{"type":"array","items":{"type":"object","properties":{"input":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que você pediu, como a Meta o devolveu."},"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O telefone do usuário na Meta, quando ela o devolve."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do usuário, quando a Meta o devolve."},"reasons":{"type":"array","items":{"type":"string"},"description":"Só em failed: o motivo que a Meta deu. Texto dela."}},"required":["input","waId","userId","reasons"],"additionalProperties":false},"description":"Os usuários que a Meta aceitou bloquear ou desbloquear."},"failed":{"type":"array","items":{"type":"object","properties":{"input":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que você pediu, como a Meta o devolveu."},"waId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O telefone do usuário na Meta, quando ela o devolve."},"userId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O BSUID do usuário, quando a Meta o devolve."},"reasons":{"type":"array","items":{"type":"string"},"description":"Só em failed: o motivo que a Meta deu. Texto dela."}},"required":["input","waId","userId","reasons"],"additionalProperties":false},"description":"Os que a Meta recusou, cada um com o motivo dela."}},"required":["done","failed"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"messages:write"}},"/v1/numbers/{id}/qr-codes":{"post":{"summary":"Create a QR code and a short link","tags":["Phone numbers"],"description":"Creates a code that opens a conversation with the number, with the message already written. It returns the code, the short link and, if you asked for it, the address of the image.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prefilledMessage":{"type":"string","minLength":1,"maxLength":140,"description":"A mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela."},"imageFormat":{"description":"Peça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam.","type":"string","enum":["PNG","SVG"]}},"required":["prefilledMessage"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"O código do QR, que vai no caminho de DELETE.","example":"4O4YGZEG3RIVE1"},"prefilledMessage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A mensagem que já vem escrita quando o contato abre a conversa."},"link":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O link curto (wa.me) que abre a mesma conversa."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da imagem do QR, quando você pediu imageFormat. É da Meta e pode expirar: baixe o arquivo."}},"required":["code","prefilledMessage","link","imageUrl"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:write"},"get":{"summary":"List the QR codes","tags":["Phone numbers"],"description":"The codes that exist on this number, with each one's short link.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"O código do QR, que vai no caminho de DELETE.","example":"4O4YGZEG3RIVE1"},"prefilledMessage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A mensagem que já vem escrita quando o contato abre a conversa."},"link":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O link curto (wa.me) que abre a mesma conversa."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da imagem do QR, quando você pediu imageFormat. É da Meta e pode expirar: baixe o arquivo."}},"required":["code","prefilledMessage","link","imageUrl"],"additionalProperties":false},"description":"Os códigos do número."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"}},"/v1/numbers/{id}/qr-codes/{code}":{"delete":{"summary":"Delete a QR code","tags":["Phone numbers"],"description":"Deletes the code and the short link: whoever still has the QR printed stops opening the conversation. It stays open on a suspended account.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"code","required":true,"description":"O código do QR, como a criação o devolveu."}],"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:write"}},"/v1/onboarding/sessions":{"post":{"summary":"Open a connection session","tags":["Phone numbers"],"description":"Creates the session that Meta's connection flow fills in, and returns the sessionId and the csrfState.","responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string"},"configId":{"type":"string"},"sdkVersion":{"type":"string","description":"A versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código."},"csrfState":{"type":"string"},"expiresAt":{"type":"string"}},"required":["sessionId","state","configId","sdkVersion","csrfState","expiresAt"],"additionalProperties":false}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"connection_not_released":{"summary":"Account not yet released to connect","value":{"error":"connection_not_released","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.","faltando":["email_confirmado"]}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_capacity_reached":{"summary":"The account is already at its number capacity","value":{"error":"number_capacity_reached","message":"Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.","capacity":20,"activeNumbers":20}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-sessions"}}},"/v1/onboarding/sessions/{id}":{"get":{"summary":"Read a connection session","tags":["Phone numbers"],"description":"The session's current state and the matching guidance text, ready to display.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string"},"orientacao":{"type":"string"},"terminal":{"type":"boolean"},"proximoPasso":{"anyOf":[{"type":"string"},{"type":"null"}]},"attemptCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextAttemptAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"retryNotBefore":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["sessionId","state","orientacao","terminal","proximoPasso","attemptCount","nextAttemptAt","retryNotBefore","expiresAt","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-get-v1-onboarding-sessions-id"}}},"/v1/onboarding/sessions/{id}/abandon":{"post":{"summary":"Report an abandoned or failed flow","tags":["Phone numbers"],"description":"Telemetry about what happened in Meta's window when the flow did not complete: which screen the customer stopped on, or which error Meta reported.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csrfState":{"type":"string","minLength":1},"currentStep":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["csrfState"]}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"state":{"type":"string"},"orientacao":{"type":"string"},"abandonedAtStep":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sessionId","state","orientacao","abandonedAtStep"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-sessions-id-abandon"}}},"/v1/onboarding/sessions/{id}/complete":{"post":{"summary":"Complete the connection","tags":["Phone numbers"],"description":"Exchanges the embedded flow's code for permanent access to the customer's account, and drives the session to the end: sealed token, app subscribed to the account, phone number registered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1},"csrfState":{"type":"string","minLength":1},"wabaId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"phoneNumberId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"businessId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["code","csrfState"]}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string"},"orientacao":{"type":"string"},"terminal":{"type":"boolean"},"proximoPasso":{"anyOf":[{"type":"string"},{"type":"null"}]},"motivo":{"anyOf":[{"type":"string"},{"type":"null"}]},"podeRetentar":{"type":"boolean"},"wabaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumberId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sessionId","state","orientacao","terminal","proximoPasso","motivo","podeRetentar","wabaId","phoneNumberId"],"additionalProperties":false,"example":{"sessionId":"77012a00-f049-4523-a658-3a3a4b105de6","state":"APP_SUBSCRIBED","orientacao":"O número está registrado na Meta e pronto para trocar mensagem.","terminal":true,"proximoPasso":null,"motivo":null,"podeRetentar":false,"wabaId":"2000000000000001","phoneNumberId":"1000000000000001"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-sessions-id-complete"}}},"/v1/numbers":{"get":{"summary":"List connected phone numbers","tags":["Phone numbers"],"description":"Every WhatsApp number connected to this customer, with state, quality, sending speed and daily conversation limit. Filters: externalId (exact match), q (prefix search over externalId, label and displayNumber), state, wabaId, qualityRating, connectionStatus, ready and canSend. A parameter the route does not know answers 400.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","required":false,"description":"O rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia."},{"schema":{"type":"string","enum":["PENDING","REGISTER_SENT","REGISTERED","PIN_REQUIRED","BLOCKED","DISCONNECTED"]},"in":"query","name":"state","required":false,"description":"O estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"q","required":false,"description":"Busca por prefixo, sem diferenciar maiúscula, em externalId, label e displayNumber. Quem digita só o número de telefone acha o número mesmo sem os espaços e o hífen."},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"wabaId","required":false,"description":"O id da conta de negócio na Meta (waba.id): só os números dela. Igualdade exata; uma conta sem número seu devolve lista vazia."},{"schema":{"type":"string","enum":["GREEN","YELLOW","RED","NA","UNKNOWN"]},"in":"query","name":"qualityRating","required":false,"description":"A qualidade que a Meta informou para o número (qualityRating): GREEN, YELLOW, RED, NA ou UNKNOWN. Número cuja qualidade a Luna ainda não leu (qualityRating nulo) não entra em nenhum valor."},{"schema":{"type":"string","enum":["connected","connecting","action_required","disconnected"]},"in":"query","name":"connectionStatus","required":false,"description":"Só os números com este connection.status: connected, connecting, action_required ou disconnected."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"ready","required":false,"description":"true: só os números prontos para enviar e receber. false: só os que ainda não estão."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"canSend","required":false,"description":"true: só os números por onde enviar funciona agora (connection.canSend). false: só os que não."},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Quantos números por página: de 1 a 100, 50 se omitido."},{"schema":{"type":"string","maxLength":256},"in":"query","name":"cursor","required":false,"description":"O nextCursor da resposta anterior. Opaco: carrega posição, não contagem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaPhoneNumberId":{"type":"string"},"displayNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"retryNotBefore":{"anyOf":[{"type":"string"},{"type":"null"}]},"podeRetentar":{"type":"boolean"},"qualityRating":{"anyOf":[{"type":"string"},{"type":"null"}]},"throughputLevel":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A VELOCIDADE de envio que a Meta concede a este número: quantas mensagens por segundo ela aceita processar. Não é o volume que pode ser iniciado por dia, que é limiteDiarioDeConversas."},"limiteDiarioDeConversas":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele é do portfólio empresarial (business portfolio) e não do número: vale para todos os números do portfólio juntos, e o valor aqui é o que a Meta devolveu na leitura deste número. Conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, e não mensagens: conversas que o cliente final inicia, e respostas dentro da janela de 24 horas, não consomem este limite. Não é a velocidade de envio, que é throughputLevel. Nulo enquanto a plataforma ainda não verificou este número."},"codeVerificationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome de exibição do número: o nome verificado que o contato vê no topo da conversa. Nulo enquanto a plataforma ainda não leu o número, o que acontece em até cerca de uma hora."},"displayNameStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O estado da revisão do nome de exibição pela Meta: approved, pending_review, declined, expired ou none. Vale para o pedido mais recente, quando há um, e senão para o nome em uso. Novos valores podem aparecer: não trate a lista como fechada. Nulo enquanto a plataforma ainda não leu o número. Quando muda, o evento number.display_name_reviewed avisa. Para pedir um nome novo, use PATCH /v1/numbers/{id}/profile com displayName."},"pendingDisplayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome pedido que ainda não é o nome em uso: em revisão, recusado, ou aprovado à espera de um novo registro do número. Nulo quando não há pedido. A Meta não informa o motivo de uma recusa, e a Luna não devolve um."},"autoRead":{"type":"boolean","description":"Quando true, a Luna marca como lida, na Meta, cada mensagem que este número recebe, sem indicador de digitando. Vale false quando nunca foi ligado. Liga e desliga com PATCH /v1/numbers/{id}. Só vale para mensagem que chega depois de ligar, e a marcação sai alguns segundos depois da chegada: a Luna não a faz no caminho do webhook."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que você deu ao seu cliente ao criar o link de conexão (POST /v1/onboarding/links), devolvido sem alteração. Nulo quando o número foi conectado sem link, ou com um link sem rótulo. Use ?externalId= na listagem para achar os números de um cliente seu."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Um rótulo livre e curto (1 a 128 caracteres) que você dá ao número, por exemplo o nome do ponto de atendimento. Edite com PATCH /v1/numbers/{id}. Nulo quando não há. É diferente de externalId, que identifica o cliente seu a quem o número pertence."},"orientacao":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que está acontecendo com a conexão deste número e o que fazer a respeito, em português pronto para você repassar ao seu cliente sem reescrever. Existe para todos os estados, inclusive os que não são falha: um número operando traz a confirmação de que está tudo certo. Um número que a Meta recusou por falta de método de pagamento traz aqui a razão e onde ela se resolve. Nulo quando não há sessão de conexão registrada para este número."},"awaitingPaymentSince":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a Meta recusou um envio deste número por falta de método de pagamento do negócio final (erro 131042), em ISO-8601 UTC. Nulo quando não há espera. Num número desconectado (connection.status disconnected) é o último valor lido antes da desconexão: a Luna deixou de acompanhá-lo. A Meta não oferece consulta de pagamento nem avisa quando ele é regularizado: este campo só volta a nulo quando um envio seguinte é aceito, e é então que o evento number.payment_resolved sai. A Luna não cobra, não adianta e não intermedeia esse pagamento; quem resolve é o negócio dono da conta, no WhatsApp Manager da Meta."},"waba":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador da conta de negócio do número na Meta (WABA)."},"restricted":{"type":"boolean","description":"true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts."},"disabled":{"type":"boolean","description":"true quando a Meta avisou que desativou a conta."},"credentialExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. O evento number.credential_expiring avisa 14 dias antes."},"credentialNeverExpires":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida."},"paymentMethodOnMeta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a conta tem forma de pagamento na Meta. false: não tem, e a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. Nulo: a Luna ainda não leu. O pagamento é do negócio com a Meta, e a Luna não o intermedeia."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida."}},"required":["id","restricted","disabled","credentialExpiresAt","credentialNeverExpires","paymentMethodOnMeta","currency"],"additionalProperties":false,"description":"O estado de saúde da conta de negócio a que este número pertence, lido do último aviso da Meta (os eventos account.restricted, account.disabled e account.reinstated). A restrição e a desativação são da conta, e valem para todos os números dela."},"ready":{"type":"boolean","description":"true quando o número já pode enviar e receber: state é REGISTERED e a inscrição do aplicativo na conta foi confirmada. Use este campo em vez de combinar os dois você mesmo. É diferente de connection.canSend, que diz se enviar vai funcionar agora."},"connection":{"type":"object","properties":{"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido: connected (nada a fazer), connecting (a conexão está em curso e é automática), action_required (alguém precisa agir, e reasons diz o quê) ou disconnected (você desconectou o número)."},"canSend":{"type":"boolean","description":"Se o envio por este número vai funcionar agora. Pode ser true com status action_required: autorização vencendo e conta sem método de pagamento são avisos, e o número ainda envia."},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"O código do motivo, para o seu código comparar. Novos códigos podem aparecer."},"message":{"type":"string","description":"O que está acontecendo, em português, pronto para repassar ao seu cliente."},"solution":{"type":"string","description":"O que fazer a respeito, em português."},"action":{"anyOf":[{"type":"string","enum":["send_pin","reconnect","reconnect_link","meta_manager","wait","contact_helsen"]},{"type":"null"}],"description":"A ação que resolve o motivo: send_pin (informe o PIN em POST /v1/numbers/{id}/pin), reconnect (reconecte pela janela da Meta), reconnect_link (gere um link de reconexão para o seu cliente), meta_manager (o dono da conta resolve no WhatsApp Manager, em actionUrl), wait (só esperar) ou contact_helsen (fale com o comercial da Helsen). Nulo quando não há ação a oferecer."},"actionUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager."},"docsUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O guia do site que explica o motivo."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Desde quando o motivo vale, em ISO-8601 UTC. É o instante exato quando a Luna o conhece (espera por pagamento, vencimento da autorização, aviso da Meta sobre a conta, fim do teste, bloqueio) e, nos demais, o instante em que o número passou a precisar de ação. Nulo quando a Luna não tem instante nenhum."}},"required":["code","message","solution","action","actionUrl","docsUrl","since"],"additionalProperties":false},"description":"Por que o número precisa de ação. Vazio quando status é connected, connecting ou disconnected. Os motivos possíveis: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired e account_blocked."}},"required":["status","canSend","reasons"],"additionalProperties":false,"description":"O estado resumido da conexão, calculado pela API a partir do estado do número, da autorização do cliente, da espera por pagamento, da forma de pagamento na Meta, da restrição da conta e da suspensão do plano. Os eventos number.action_required e number.action_resolved avisam quando a lista de motivos passa de vazia para não vazia, e de volta."},"allowedActions":{"type":"array","items":{"type":"string","enum":["disconnect","reconnect","reconnect_link","send_pin","edit_label"]},"description":"O que a sua conta pode fazer com este número agora, decidido pela API: disconnect (DELETE /v1/numbers/{id}), reconnect (POST /v1/onboarding/reconnect), reconnect_link (POST /v1/onboarding/links com numberId), send_pin (POST /v1/numbers/{id}/pin) e edit_label (PATCH /v1/numbers/{id}). Mostre o botão quando o verbo está na lista, e não por state ou connection.status. A lista leva em conta o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano, e não leva em conta os escopos da chave que perguntou."},"blockedActions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["disconnect","reconnect","reconnect_link","send_pin","edit_label"]},"message":{"type":"string","description":"Por que a ação não está disponível agora, em português, pronto para mostrar."}},"required":["action","message"],"additionalProperties":false},"description":"As ações que fariam sentido neste número e a conta impede agora, cada uma com a razão. Um verbo que não se aplica ao estado do número não aparece aqui nem em allowedActions."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","metaPhoneNumberId","displayNumber","state","retryNotBefore","podeRetentar","qualityRating","throughputLevel","limiteDiarioDeConversas","codeVerificationStatus","displayName","displayNameStatus","pendingDisplayName","autoRead","externalId","label","orientacao","awaitingPaymentSince","waba","ready","connection","allowedActions","blockedActions","createdAt","updatedAt"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/plan-and-numbers#rota-get-v1-numbers"}}},"/v1/numbers/{id}":{"get":{"summary":"Read one phone number","tags":["Phone numbers"],"description":"One number, with everything the listing carries plus the health of its connection to Meta.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaPhoneNumberId":{"type":"string"},"displayNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"retryNotBefore":{"anyOf":[{"type":"string"},{"type":"null"}]},"podeRetentar":{"type":"boolean"},"qualityRating":{"anyOf":[{"type":"string"},{"type":"null"}]},"throughputLevel":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A VELOCIDADE de envio que a Meta concede a este número: quantas mensagens por segundo ela aceita processar. Não é o volume que pode ser iniciado por dia, que é limiteDiarioDeConversas."},"limiteDiarioDeConversas":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele é do portfólio empresarial (business portfolio) e não do número: vale para todos os números do portfólio juntos, e o valor aqui é o que a Meta devolveu na leitura deste número. Conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, e não mensagens: conversas que o cliente final inicia, e respostas dentro da janela de 24 horas, não consomem este limite. Não é a velocidade de envio, que é throughputLevel. Nulo enquanto a plataforma ainda não verificou este número."},"codeVerificationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome de exibição do número: o nome verificado que o contato vê no topo da conversa. Nulo enquanto a plataforma ainda não leu o número, o que acontece em até cerca de uma hora."},"displayNameStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O estado da revisão do nome de exibição pela Meta: approved, pending_review, declined, expired ou none. Vale para o pedido mais recente, quando há um, e senão para o nome em uso. Novos valores podem aparecer: não trate a lista como fechada. Nulo enquanto a plataforma ainda não leu o número. Quando muda, o evento number.display_name_reviewed avisa. Para pedir um nome novo, use PATCH /v1/numbers/{id}/profile com displayName."},"pendingDisplayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome pedido que ainda não é o nome em uso: em revisão, recusado, ou aprovado à espera de um novo registro do número. Nulo quando não há pedido. A Meta não informa o motivo de uma recusa, e a Luna não devolve um."},"autoRead":{"type":"boolean","description":"Quando true, a Luna marca como lida, na Meta, cada mensagem que este número recebe, sem indicador de digitando. Vale false quando nunca foi ligado. Liga e desliga com PATCH /v1/numbers/{id}. Só vale para mensagem que chega depois de ligar, e a marcação sai alguns segundos depois da chegada: a Luna não a faz no caminho do webhook."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que você deu ao seu cliente ao criar o link de conexão (POST /v1/onboarding/links), devolvido sem alteração. Nulo quando o número foi conectado sem link, ou com um link sem rótulo. Use ?externalId= na listagem para achar os números de um cliente seu."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Um rótulo livre e curto (1 a 128 caracteres) que você dá ao número, por exemplo o nome do ponto de atendimento. Edite com PATCH /v1/numbers/{id}. Nulo quando não há. É diferente de externalId, que identifica o cliente seu a quem o número pertence."},"orientacao":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que está acontecendo com a conexão deste número e o que fazer a respeito, em português pronto para você repassar ao seu cliente sem reescrever. Existe para todos os estados, inclusive os que não são falha: um número operando traz a confirmação de que está tudo certo. Um número que a Meta recusou por falta de método de pagamento traz aqui a razão e onde ela se resolve. Nulo quando não há sessão de conexão registrada para este número."},"awaitingPaymentSince":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a Meta recusou um envio deste número por falta de método de pagamento do negócio final (erro 131042), em ISO-8601 UTC. Nulo quando não há espera. Num número desconectado (connection.status disconnected) é o último valor lido antes da desconexão: a Luna deixou de acompanhá-lo. A Meta não oferece consulta de pagamento nem avisa quando ele é regularizado: este campo só volta a nulo quando um envio seguinte é aceito, e é então que o evento number.payment_resolved sai. A Luna não cobra, não adianta e não intermedeia esse pagamento; quem resolve é o negócio dono da conta, no WhatsApp Manager da Meta."},"waba":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador da conta de negócio do número na Meta (WABA)."},"restricted":{"type":"boolean","description":"true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts."},"disabled":{"type":"boolean","description":"true quando a Meta avisou que desativou a conta."},"credentialExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. O evento number.credential_expiring avisa 14 dias antes."},"credentialNeverExpires":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida."},"paymentMethodOnMeta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a conta tem forma de pagamento na Meta. false: não tem, e a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. Nulo: a Luna ainda não leu. O pagamento é do negócio com a Meta, e a Luna não o intermedeia."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida."}},"required":["id","restricted","disabled","credentialExpiresAt","credentialNeverExpires","paymentMethodOnMeta","currency"],"additionalProperties":false,"description":"O estado de saúde da conta de negócio a que este número pertence, lido do último aviso da Meta (os eventos account.restricted, account.disabled e account.reinstated). A restrição e a desativação são da conta, e valem para todos os números dela."},"ready":{"type":"boolean","description":"true quando o número já pode enviar e receber: state é REGISTERED e a inscrição do aplicativo na conta foi confirmada. Use este campo em vez de combinar os dois você mesmo. É diferente de connection.canSend, que diz se enviar vai funcionar agora."},"connection":{"type":"object","properties":{"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido: connected (nada a fazer), connecting (a conexão está em curso e é automática), action_required (alguém precisa agir, e reasons diz o quê) ou disconnected (você desconectou o número)."},"canSend":{"type":"boolean","description":"Se o envio por este número vai funcionar agora. Pode ser true com status action_required: autorização vencendo e conta sem método de pagamento são avisos, e o número ainda envia."},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"O código do motivo, para o seu código comparar. Novos códigos podem aparecer."},"message":{"type":"string","description":"O que está acontecendo, em português, pronto para repassar ao seu cliente."},"solution":{"type":"string","description":"O que fazer a respeito, em português."},"action":{"anyOf":[{"type":"string","enum":["send_pin","reconnect","reconnect_link","meta_manager","wait","contact_helsen"]},{"type":"null"}],"description":"A ação que resolve o motivo: send_pin (informe o PIN em POST /v1/numbers/{id}/pin), reconnect (reconecte pela janela da Meta), reconnect_link (gere um link de reconexão para o seu cliente), meta_manager (o dono da conta resolve no WhatsApp Manager, em actionUrl), wait (só esperar) ou contact_helsen (fale com o comercial da Helsen). Nulo quando não há ação a oferecer."},"actionUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager."},"docsUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O guia do site que explica o motivo."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Desde quando o motivo vale, em ISO-8601 UTC. É o instante exato quando a Luna o conhece (espera por pagamento, vencimento da autorização, aviso da Meta sobre a conta, fim do teste, bloqueio) e, nos demais, o instante em que o número passou a precisar de ação. Nulo quando a Luna não tem instante nenhum."}},"required":["code","message","solution","action","actionUrl","docsUrl","since"],"additionalProperties":false},"description":"Por que o número precisa de ação. Vazio quando status é connected, connecting ou disconnected. Os motivos possíveis: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired e account_blocked."},"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["authorized","receiving","registered","ready"]},"label":{"type":"string","description":"O nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado."},"status":{"type":"string","enum":["done","current","pending"]}},"required":["key","label","status"],"additionalProperties":false},"description":"Os quatro passos da conexão, sempre nesta ordem: authorized (a autorização do cliente), receiving (a inscrição do aplicativo na conta, que traz os eventos), registered (o número registrado, ou vinculado em coexistência) e ready (pronto para enviar e receber). current é o primeiro que ainda não terminou, e com todos done nenhum é current. A tela só precisa desenhar a lista."}},"required":["status","canSend","reasons","steps"],"additionalProperties":false},"allowedActions":{"type":"array","items":{"type":"string","enum":["disconnect","reconnect","reconnect_link","send_pin","edit_label"]},"description":"O que a sua conta pode fazer com este número agora, decidido pela API: disconnect (DELETE /v1/numbers/{id}), reconnect (POST /v1/onboarding/reconnect), reconnect_link (POST /v1/onboarding/links com numberId), send_pin (POST /v1/numbers/{id}/pin) e edit_label (PATCH /v1/numbers/{id}). Mostre o botão quando o verbo está na lista, e não por state ou connection.status. A lista leva em conta o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano, e não leva em conta os escopos da chave que perguntou."},"blockedActions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["disconnect","reconnect","reconnect_link","send_pin","edit_label"]},"message":{"type":"string","description":"Por que a ação não está disponível agora, em português, pronto para mostrar."}},"required":["action","message"],"additionalProperties":false},"description":"As ações que fariam sentido neste número e a conta impede agora, cada uma com a razão. Um verbo que não se aplica ao estado do número não aparece aqui nem em allowedActions."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"tetoDeVazaoPorSegundo":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O teto de envio deste número em mensagens por segundo, quando ele é FIXO e não sobe. Números conectados em coexistência, que continuam funcionando no aplicativo de celular do negócio, têm esse teto fixo pela plataforma da Meta, e ele não acompanha a progressão de throughputLevel. Nulo significa o contrário: este número segue a progressão da Meta, e quem a descreve é throughputLevel. Não é contagem de nada e não muda com o que o número enviou: é a capacidade que a plataforma da Meta concede.","example":null},"sincronizacaoDoHistorico":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Em que pé está a importação das conversas anteriores do aparelho do negócio, num número conectado em coexistência. São quatro situações e cada uma pede uma reação diferente. Nulo significa que não há importação para este número, e não que ela parou. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele: não vai concluir, e pedir de novo não muda isso. Atenção ao ler sincronizacaoProgresso junto: cem por cento não significa sucesso, porque a recusa chega com o progresso que já havia sido registrado.","example":"em_curso"},"sincronizacaoPrazo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Até quando a importação precisa terminar. Passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. Sai sempre como instante em UTC, e nunca como texto do tipo faltam tantas horas: um texto desses fica errado na tela de quem a deixou aberta, e quem integra pela API precisa de um valor comparável com o próprio relógio. Nulo quando não há importação em curso conhecida.","example":"2026-09-19T09:00:00.000Z"},"sincronizacaoProgresso":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O rótulo de progresso que a plataforma da Meta atribui à importação, de 0 a 100. É um rótulo e não uma contagem: ele chega a 100 igualmente para um aparelho com poucas conversas antigas e para um com muitas, e nada nele cresce com o tamanho do que foi importado. Não use este campo para deduzir quantidade, porque ele não carrega nenhuma. Nulo quando a plataforma da Meta ainda não informou progresso para este número.","example":40},"subscriptionConfirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Nulo significa que os eventos deste número ainda não chegam. Num número desconectado é o último valor lido antes da desconexão."},"credentialStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O estado da autorização concedida pelo cliente. Nunca a credencial em si. Num número desconectado é o último valor lido antes da desconexão, e serve a quem decide reconectar (podeReconectar)."},"podeReconectar":{"type":"boolean","description":"Se a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui."},"coexistence":{"type":"boolean","description":"true quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo de celular do negócio. É a mesma regra do campo coexistence do evento number.connected, e pode passar de false para true depois da conexão. É true exatamente quando tetoDeVazaoPorSegundo tem valor."}},"required":["id","metaPhoneNumberId","displayNumber","state","retryNotBefore","podeRetentar","qualityRating","throughputLevel","limiteDiarioDeConversas","codeVerificationStatus","displayName","displayNameStatus","pendingDisplayName","autoRead","externalId","label","orientacao","awaitingPaymentSince","waba","ready","connection","allowedActions","blockedActions","createdAt","updatedAt","tetoDeVazaoPorSegundo","sincronizacaoDoHistorico","sincronizacaoPrazo","sincronizacaoProgresso","subscriptionConfirmedAt","credentialStatus","podeReconectar","coexistence"],"additionalProperties":false,"example":{"id":"ed404df1-b420-4ed6-8743-ba1609892e0a","metaPhoneNumberId":"1000000000000001","displayNumber":"+55 11 90000-0000","state":"REGISTERED","retryNotBefore":null,"podeRetentar":false,"qualityRating":"GREEN","throughputLevel":"STANDARD","limiteDiarioDeConversas":"TIER_10K","codeVerificationStatus":"VERIFIED","displayName":"Clínica Sorriso","displayNameStatus":"approved","pendingDisplayName":null,"autoRead":false,"externalId":"cliente-8841","label":"Atendimento Pinheiros","orientacao":"Número conectado e operando. Mensagens já entram e saem por ele.","awaitingPaymentSince":null,"waba":{"id":"102290129340398","restricted":false,"disabled":false,"credentialExpiresAt":null,"credentialNeverExpires":true,"paymentMethodOnMeta":true,"currency":"BRL"},"ready":true,"connection":{"status":"connected","canSend":true,"reasons":[],"steps":[{"key":"authorized","label":"Autorização do negócio","status":"done"},{"key":"receiving","label":"Recebimento das mensagens","status":"done"},{"key":"registered","label":"Número registrado","status":"done"},{"key":"ready","label":"Pronto para usar","status":"done"}]},"allowedActions":["disconnect","edit_label"],"blockedActions":[],"createdAt":"2026-08-07T11:28:14.597Z","updatedAt":"2026-08-07T11:28:28.703Z","tetoDeVazaoPorSegundo":null,"sincronizacaoDoHistorico":null,"sincronizacaoPrazo":null,"sincronizacaoProgresso":null,"subscriptionConfirmedAt":"2026-08-07T11:27:47.141Z","credentialStatus":"active","podeReconectar":false,"coexistence":false}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/plan-and-numbers#rota-get-v1-numbers-id"}},"patch":{"summary":"Edit a number","tags":["Phone numbers"],"description":"Changes a number's externalId and label, and turns autoRead (mark every received message as read on its own) on or off. It is how you reuse a number for another customer of yours, or name a number that was connected through the console, without a link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"description":"O seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa.","anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]},"label":{"description":"Um nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa.","anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]},"autoRead":{"description":"true: a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando. false desliga. Ausente não muda. O padrão de um número é false.","type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaPhoneNumberId":{"type":"string"},"displayNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"retryNotBefore":{"anyOf":[{"type":"string"},{"type":"null"}]},"podeRetentar":{"type":"boolean"},"qualityRating":{"anyOf":[{"type":"string"},{"type":"null"}]},"throughputLevel":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A VELOCIDADE de envio que a Meta concede a este número: quantas mensagens por segundo ela aceita processar. Não é o volume que pode ser iniciado por dia, que é limiteDiarioDeConversas."},"limiteDiarioDeConversas":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele é do portfólio empresarial (business portfolio) e não do número: vale para todos os números do portfólio juntos, e o valor aqui é o que a Meta devolveu na leitura deste número. Conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, e não mensagens: conversas que o cliente final inicia, e respostas dentro da janela de 24 horas, não consomem este limite. Não é a velocidade de envio, que é throughputLevel. Nulo enquanto a plataforma ainda não verificou este número."},"codeVerificationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome de exibição do número: o nome verificado que o contato vê no topo da conversa. Nulo enquanto a plataforma ainda não leu o número, o que acontece em até cerca de uma hora."},"displayNameStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O estado da revisão do nome de exibição pela Meta: approved, pending_review, declined, expired ou none. Vale para o pedido mais recente, quando há um, e senão para o nome em uso. Novos valores podem aparecer: não trate a lista como fechada. Nulo enquanto a plataforma ainda não leu o número. Quando muda, o evento number.display_name_reviewed avisa. Para pedir um nome novo, use PATCH /v1/numbers/{id}/profile com displayName."},"pendingDisplayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome pedido que ainda não é o nome em uso: em revisão, recusado, ou aprovado à espera de um novo registro do número. Nulo quando não há pedido. A Meta não informa o motivo de uma recusa, e a Luna não devolve um."},"autoRead":{"type":"boolean","description":"Quando true, a Luna marca como lida, na Meta, cada mensagem que este número recebe, sem indicador de digitando. Vale false quando nunca foi ligado. Liga e desliga com PATCH /v1/numbers/{id}. Só vale para mensagem que chega depois de ligar, e a marcação sai alguns segundos depois da chegada: a Luna não a faz no caminho do webhook."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que você deu ao seu cliente ao criar o link de conexão (POST /v1/onboarding/links), devolvido sem alteração. Nulo quando o número foi conectado sem link, ou com um link sem rótulo. Use ?externalId= na listagem para achar os números de um cliente seu."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Um rótulo livre e curto (1 a 128 caracteres) que você dá ao número, por exemplo o nome do ponto de atendimento. Edite com PATCH /v1/numbers/{id}. Nulo quando não há. É diferente de externalId, que identifica o cliente seu a quem o número pertence."},"orientacao":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que está acontecendo com a conexão deste número e o que fazer a respeito, em português pronto para você repassar ao seu cliente sem reescrever. Existe para todos os estados, inclusive os que não são falha: um número operando traz a confirmação de que está tudo certo. Um número que a Meta recusou por falta de método de pagamento traz aqui a razão e onde ela se resolve. Nulo quando não há sessão de conexão registrada para este número."},"awaitingPaymentSince":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a Meta recusou um envio deste número por falta de método de pagamento do negócio final (erro 131042), em ISO-8601 UTC. Nulo quando não há espera. Num número desconectado (connection.status disconnected) é o último valor lido antes da desconexão: a Luna deixou de acompanhá-lo. A Meta não oferece consulta de pagamento nem avisa quando ele é regularizado: este campo só volta a nulo quando um envio seguinte é aceito, e é então que o evento number.payment_resolved sai. A Luna não cobra, não adianta e não intermedeia esse pagamento; quem resolve é o negócio dono da conta, no WhatsApp Manager da Meta."},"waba":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador da conta de negócio do número na Meta (WABA)."},"restricted":{"type":"boolean","description":"true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts."},"disabled":{"type":"boolean","description":"true quando a Meta avisou que desativou a conta."},"credentialExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. O evento number.credential_expiring avisa 14 dias antes."},"credentialNeverExpires":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida."},"paymentMethodOnMeta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a conta tem forma de pagamento na Meta. false: não tem, e a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. Nulo: a Luna ainda não leu. O pagamento é do negócio com a Meta, e a Luna não o intermedeia."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida."}},"required":["id","restricted","disabled","credentialExpiresAt","credentialNeverExpires","paymentMethodOnMeta","currency"],"additionalProperties":false,"description":"O estado de saúde da conta de negócio a que este número pertence, lido do último aviso da Meta (os eventos account.restricted, account.disabled e account.reinstated). A restrição e a desativação são da conta, e valem para todos os números dela."},"ready":{"type":"boolean","description":"true quando o número já pode enviar e receber: state é REGISTERED e a inscrição do aplicativo na conta foi confirmada. Use este campo em vez de combinar os dois você mesmo. É diferente de connection.canSend, que diz se enviar vai funcionar agora."},"connection":{"type":"object","properties":{"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido: connected (nada a fazer), connecting (a conexão está em curso e é automática), action_required (alguém precisa agir, e reasons diz o quê) ou disconnected (você desconectou o número)."},"canSend":{"type":"boolean","description":"Se o envio por este número vai funcionar agora. Pode ser true com status action_required: autorização vencendo e conta sem método de pagamento são avisos, e o número ainda envia."},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"O código do motivo, para o seu código comparar. Novos códigos podem aparecer."},"message":{"type":"string","description":"O que está acontecendo, em português, pronto para repassar ao seu cliente."},"solution":{"type":"string","description":"O que fazer a respeito, em português."},"action":{"anyOf":[{"type":"string","enum":["send_pin","reconnect","reconnect_link","meta_manager","wait","contact_helsen"]},{"type":"null"}],"description":"A ação que resolve o motivo: send_pin (informe o PIN em POST /v1/numbers/{id}/pin), reconnect (reconecte pela janela da Meta), reconnect_link (gere um link de reconexão para o seu cliente), meta_manager (o dono da conta resolve no WhatsApp Manager, em actionUrl), wait (só esperar) ou contact_helsen (fale com o comercial da Helsen). Nulo quando não há ação a oferecer."},"actionUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager."},"docsUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O guia do site que explica o motivo."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Desde quando o motivo vale, em ISO-8601 UTC. É o instante exato quando a Luna o conhece (espera por pagamento, vencimento da autorização, aviso da Meta sobre a conta, fim do teste, bloqueio) e, nos demais, o instante em que o número passou a precisar de ação. Nulo quando a Luna não tem instante nenhum."}},"required":["code","message","solution","action","actionUrl","docsUrl","since"],"additionalProperties":false},"description":"Por que o número precisa de ação. Vazio quando status é connected, connecting ou disconnected. Os motivos possíveis: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired e account_blocked."},"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["authorized","receiving","registered","ready"]},"label":{"type":"string","description":"O nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado."},"status":{"type":"string","enum":["done","current","pending"]}},"required":["key","label","status"],"additionalProperties":false},"description":"Os quatro passos da conexão, sempre nesta ordem: authorized (a autorização do cliente), receiving (a inscrição do aplicativo na conta, que traz os eventos), registered (o número registrado, ou vinculado em coexistência) e ready (pronto para enviar e receber). current é o primeiro que ainda não terminou, e com todos done nenhum é current. A tela só precisa desenhar a lista."}},"required":["status","canSend","reasons","steps"],"additionalProperties":false},"allowedActions":{"type":"array","items":{"type":"string","enum":["disconnect","reconnect","reconnect_link","send_pin","edit_label"]},"description":"O que a sua conta pode fazer com este número agora, decidido pela API: disconnect (DELETE /v1/numbers/{id}), reconnect (POST /v1/onboarding/reconnect), reconnect_link (POST /v1/onboarding/links com numberId), send_pin (POST /v1/numbers/{id}/pin) e edit_label (PATCH /v1/numbers/{id}). Mostre o botão quando o verbo está na lista, e não por state ou connection.status. A lista leva em conta o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano, e não leva em conta os escopos da chave que perguntou."},"blockedActions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["disconnect","reconnect","reconnect_link","send_pin","edit_label"]},"message":{"type":"string","description":"Por que a ação não está disponível agora, em português, pronto para mostrar."}},"required":["action","message"],"additionalProperties":false},"description":"As ações que fariam sentido neste número e a conta impede agora, cada uma com a razão. Um verbo que não se aplica ao estado do número não aparece aqui nem em allowedActions."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"tetoDeVazaoPorSegundo":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O teto de envio deste número em mensagens por segundo, quando ele é FIXO e não sobe. Números conectados em coexistência, que continuam funcionando no aplicativo de celular do negócio, têm esse teto fixo pela plataforma da Meta, e ele não acompanha a progressão de throughputLevel. Nulo significa o contrário: este número segue a progressão da Meta, e quem a descreve é throughputLevel. Não é contagem de nada e não muda com o que o número enviou: é a capacidade que a plataforma da Meta concede.","example":null},"sincronizacaoDoHistorico":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Em que pé está a importação das conversas anteriores do aparelho do negócio, num número conectado em coexistência. São quatro situações e cada uma pede uma reação diferente. Nulo significa que não há importação para este número, e não que ela parou. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele: não vai concluir, e pedir de novo não muda isso. Atenção ao ler sincronizacaoProgresso junto: cem por cento não significa sucesso, porque a recusa chega com o progresso que já havia sido registrado.","example":"em_curso"},"sincronizacaoPrazo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Até quando a importação precisa terminar. Passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. Sai sempre como instante em UTC, e nunca como texto do tipo faltam tantas horas: um texto desses fica errado na tela de quem a deixou aberta, e quem integra pela API precisa de um valor comparável com o próprio relógio. Nulo quando não há importação em curso conhecida.","example":"2026-09-19T09:00:00.000Z"},"sincronizacaoProgresso":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O rótulo de progresso que a plataforma da Meta atribui à importação, de 0 a 100. É um rótulo e não uma contagem: ele chega a 100 igualmente para um aparelho com poucas conversas antigas e para um com muitas, e nada nele cresce com o tamanho do que foi importado. Não use este campo para deduzir quantidade, porque ele não carrega nenhuma. Nulo quando a plataforma da Meta ainda não informou progresso para este número.","example":40},"subscriptionConfirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Nulo significa que os eventos deste número ainda não chegam. Num número desconectado é o último valor lido antes da desconexão."},"credentialStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O estado da autorização concedida pelo cliente. Nunca a credencial em si. Num número desconectado é o último valor lido antes da desconexão, e serve a quem decide reconectar (podeReconectar)."},"podeReconectar":{"type":"boolean","description":"Se a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui."},"coexistence":{"type":"boolean","description":"true quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo de celular do negócio. É a mesma regra do campo coexistence do evento number.connected, e pode passar de false para true depois da conexão. É true exatamente quando tetoDeVazaoPorSegundo tem valor."}},"required":["id","metaPhoneNumberId","displayNumber","state","retryNotBefore","podeRetentar","qualityRating","throughputLevel","limiteDiarioDeConversas","codeVerificationStatus","displayName","displayNameStatus","pendingDisplayName","autoRead","externalId","label","orientacao","awaitingPaymentSince","waba","ready","connection","allowedActions","blockedActions","createdAt","updatedAt","tetoDeVazaoPorSegundo","sincronizacaoDoHistorico","sincronizacaoPrazo","sincronizacaoProgresso","subscriptionConfirmedAt","credentialStatus","podeReconectar","coexistence"],"additionalProperties":false,"example":{"id":"ed404df1-b420-4ed6-8743-ba1609892e0a","metaPhoneNumberId":"1000000000000001","displayNumber":"+55 11 90000-0000","state":"REGISTERED","retryNotBefore":null,"podeRetentar":false,"qualityRating":"GREEN","throughputLevel":"STANDARD","limiteDiarioDeConversas":"TIER_10K","codeVerificationStatus":"VERIFIED","displayName":"Clínica Sorriso","displayNameStatus":"approved","pendingDisplayName":null,"autoRead":false,"externalId":"cliente-8841","label":"Atendimento Pinheiros","orientacao":"Número conectado e operando. Mensagens já entram e saem por ele.","awaitingPaymentSince":null,"waba":{"id":"102290129340398","restricted":false,"disabled":false,"credentialExpiresAt":null,"credentialNeverExpires":true,"paymentMethodOnMeta":true,"currency":"BRL"},"ready":true,"connection":{"status":"connected","canSend":true,"reasons":[],"steps":[{"key":"authorized","label":"Autorização do negócio","status":"done"},{"key":"receiving","label":"Recebimento das mensagens","status":"done"},{"key":"registered","label":"Número registrado","status":"done"},{"key":"ready","label":"Pronto para usar","status":"done"}]},"allowedActions":["disconnect","edit_label"],"blockedActions":[],"createdAt":"2026-08-07T11:28:14.597Z","updatedAt":"2026-08-07T11:28:28.703Z","tetoDeVazaoPorSegundo":null,"sincronizacaoDoHistorico":null,"sincronizacaoPrazo":null,"sincronizacaoProgresso":null,"subscriptionConfirmedAt":"2026-08-07T11:27:47.141Z","credentialStatus":"active","podeReconectar":false,"coexistence":false}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/plan-and-numbers#rota-patch-v1-numbers-id"}},"delete":{"summary":"Disconnect a number","tags":["Phone numbers"],"description":"Takes the number off Luna. It is how you open a slot in the plan capacity: the number stops counting from this instant, and your customer can be swapped for another.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/plan-and-numbers#rota-delete-v1-numbers-id"}}},"/v1/numbers/{id}/pin":{"post":{"summary":"Give a number's two step verification PIN","tags":["Phone numbers"],"description":"Gives the two step verification PIN of a number that is already registered on another provider's Cloud API, so Luna can register it without the end business having to turn verification off.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pin":{"type":"string","pattern":"^\\d{6}$","description":"O PIN de verificação em duas etapas deste número, com exatamente seis dígitos. Quando o número já tem verificação em duas etapas configurada em outro provedor, é o PIN existente dele, e apenas o negócio final o conhece: não existe endpoint para ler nem para desligar o PIN de um número. Quando o número não tem verificação em duas etapas, este valor passa a ser o PIN dele."}},"required":["pin"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador deste número na Luna."},"state":{"type":"string","description":"O estado do número depois da submissão. Ele volta ao ponto de onde o registro opera, e a próxima tentativa de conexão usa o PIN que você informou."}},"required":["id","state"],"additionalProperties":false,"example":{"id":"ed404df1-b420-4ed6-8743-ba1609892e0a","state":"PENDING"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"pin_not_applicable":{"summary":"The number does not ask for a PIN","value":{"error":"pin_not_applicable","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Este número não está aguardando o PIN de verificação em duas etapas. O campo state diz em que ponto ele está."}},"register_budget_reserved":{"summary":"Registration attempts reserved","value":{"error":"register_budget_reserved","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"As tentativas de registro que a Meta concede a este número em 72 horas estão perto do fim, e a plataforma guarda as últimas para não travar o número. Confirme o PIN com o negócio final antes de submeter de novo.","tentativasRestantes":1,"janelaVira":"2026-10-09T12:00:00.000Z"}},"number_capacity_reached":{"summary":"The account is already at its number capacity","value":{"error":"number_capacity_reached","message":"Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.","capacity":20,"activeNumbers":20}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-numbers-id-pin"}}},"/v1/onboarding/reconnect":{"post":{"summary":"Reconnect a number whose authorisation died","tags":["Phone numbers"],"description":"Opens a connection session for a number that already exists, when the authorisation granted by the customer expired or was revoked.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"numberId":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}},"required":["numberId"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string"},"configId":{"type":"string"},"sdkVersion":{"type":"string","description":"A versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código."},"csrfState":{"type":"string"},"expiresAt":{"type":"string"}},"required":["sessionId","state","configId","sdkVersion","csrfState","expiresAt"],"additionalProperties":false,"example":{"sessionId":"77012a00-f049-4523-a658-3a3a4b105de6","state":"STARTED","configId":"1234567890","sdkVersion":"v26.0","csrfState":"Xk3s...","expiresAt":"2026-08-26T18:30:00.000Z"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"connection_not_released":{"summary":"Account not yet released to connect","value":{"error":"connection_not_released","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.","faltando":["email_confirmado"]}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"reconnect_not_applicable":{"summary":"The authorization does not allow reconnection","value":{"error":"reconnect_not_applicable","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"A autorização deste número não admite reconexão.","credentialStatus":"active"}},"number_capacity_reached":{"summary":"The account is already at its number capacity","value":{"error":"number_capacity_reached","message":"Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.","capacity":20,"activeNumbers":20}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-reconnect"}}},"/v1/business-accounts":{"get":{"summary":"List business accounts","tags":["Phone numbers"],"description":"The WhatsApp Business accounts this customer has connected, newest first, each with its name at Meta, its WhatsApp Manager address and its numbers.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"wabaId":{"type":"string"},"numbers":{"type":"array","items":{"type":"string"}},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da conta de WhatsApp Business como a Meta o informa. Nulo enquanto a Luna ainda não o leu."},"managerUrl":{"type":"string","description":"O endereço desta conta no WhatsApp Manager da Meta, onde o dono da conta resolve pagamento, verificação e restrições."},"phoneNumbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O id do número na Luna, o mesmo de GET /v1/numbers."},"displayNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número como se lê no telefone, ou nulo enquanto a Luna não o leu."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O seu rótulo para o cliente dono do número."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que você deu ao número."}},"required":["id","displayNumber","externalId","label"],"additionalProperties":false},"description":"Os números desta conta, na ordem em que foram conectados. É o numbers de texto com o que a tela precisa para ligar cada número ao seu recurso."},"status":{"type":"object","properties":{"restricted":{"type":"boolean","description":"true quando o último aviso de restrição da Meta ainda vale. Uma restrição com prazo deixa de contar quando o prazo passa, porque a Meta não avisa o fim dela. Uma restrição sem prazo legível conta até um novo aviso."},"restrictions":{"type":"array","items":{"type":"object","properties":{"restrictionType":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiration":{"anyOf":[{"type":"string"},{"type":"null"}]},"remediation":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["restrictionType","expiration","remediation"],"additionalProperties":false},"description":"As restrições do último aviso, com o tipo, o prazo e a orientação como a Meta mandou. Vazia quando não há aviso."},"disabled":{"type":"boolean","description":"true quando o último aviso de desativação da Meta diz que a conta foi desativada. Volta a false se a Meta avisar a reativação."},"violationType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da última violação de política que a Meta avisou, ou nulo. É um aviso, e não um estado que expira."},"reportedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando chegou o aviso de saúde mais recente, ou nulo se nunca chegou."}},"required":["restricted","restrictions","disabled","violationType","reportedAt"],"additionalProperties":false,"description":"O último estado de saúde conhecido da conta."},"credentialExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. A Luna avisa 14 dias antes, no evento number.credential_expiring."},"credentialNeverExpires":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a Meta informou que a autorização não vence. false: ela vence, e credentialExpiresAt traz a data. Nulo: a Luna ainda não leu a validade desta conta."},"paymentMethodOnMeta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true quando a conta tem forma de pagamento cadastrada na Meta, false quando não tem, nulo quando a Luna ainda não leu. Sem forma de pagamento, a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. O pagamento é do negócio dono da conta com a Meta, e a Luna não o intermedeia."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando a Luna ainda não leu."},"createdAt":{"type":"string"}},"required":["id","wabaId","numbers","name","managerUrl","phoneNumbers","status","credentialExpiresAt","credentialNeverExpires","paymentMethodOnMeta","currency","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false,"example":{"data":[{"id":"ed404df1-b420-4ed6-8743-ba1609892e0a","wabaId":"102290129340398","numbers":["+55 11 90000-0000"],"name":"Padaria do Zé","managerUrl":"https://business.facebook.com/latest/whatsapp_manager/overview?asset_id=102290129340398","phoneNumbers":[{"id":"a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d","displayNumber":"+55 11 90000-0000","externalId":"cliente-8841","label":"Atendimento Pinheiros"}],"status":{"restricted":false,"restrictions":[],"disabled":false,"violationType":null,"reportedAt":null},"credentialExpiresAt":null,"credentialNeverExpires":true,"paymentMethodOnMeta":true,"currency":"BRL","createdAt":"2026-08-07T11:27:41.208Z"}]}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/connect-a-number#rota-get-v1-business-accounts"}}},"/v1/business-accounts/{id}/payment-method/check":{"post":{"summary":"Check the account payment method at Meta now","tags":["Phone numbers"],"description":"Reads from Meta whether the account has a payment method on file, without waiting for the hourly read, and returns the result. The webhook notice follows the usual path: number.action_required (reason payment_method_missing) when it is missing and number.action_resolved when it shows up. A read newer than 60 seconds is returned without calling Meta, and the call respects the account call budget.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"wabaId":{"type":"string"},"paymentMethodOnMeta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true: a conta tem forma de pagamento na Meta. false: não tem. Nulo: a Luna ainda não conseguiu ler."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda da conta na Meta, como ela informa. Nulo quando ainda não lida."},"checkedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a Luna leu a forma de pagamento da Meta pela última vez, em ISO-8601 UTC. Nulo se nunca leu."},"refreshed":{"type":"boolean","description":"true quando esta chamada leu na Meta agora. false quando devolveu a leitura que já existia."},"reason":{"type":"string","enum":["checked","recent","busy","failed"],"description":"checked: leu na Meta agora. recent: a leitura tem menos de 60 segundos e foi devolvida sem chamar a Meta. busy: o orçamento de chamadas da Meta para esta conta está no limite; tente de novo em alguns minutos. failed: a Meta não respondeu ou recusou; o valor devolvido é o anterior."}},"required":["id","wabaId","paymentMethodOnMeta","currency","checkedAt","refreshed","reason"],"additionalProperties":false,"example":{"id":"ed404df1-b420-4ed6-8743-ba1609892e0a","wabaId":"102290129340398","paymentMethodOnMeta":false,"currency":"BRL","checkedAt":"2026-11-05T14:02:11.000Z","refreshed":true,"reason":"checked"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"}},"/v1/onboarding/links":{"post":{"summary":"Create a connect link for your customer","tags":["Connection links"],"description":"Creates a link your customer opens to connect their own WhatsApp number, without being given your console login.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"description":"O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão."},"displayName":{"description":"O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra (\"Conectar o WhatsApp de ...\"). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada.","type":"string","minLength":1,"maxLength":120},"redirectUrl":{"description":"Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna.","type":"string","maxLength":2048,"pattern":"^https:\\/\\/[^\\s]+$"},"numberId":{"description":"O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova.","type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}}},{"type":"null"}]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","description":"O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta."},"expiresAt":{"type":"string"},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A redirectUrl do pedido, ou nulo."},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do seu cliente que a página do link mostra, ou nulo."}},"required":["id","url","expiresAt","externalId","redirectUrl","displayName"],"additionalProperties":false,"example":{"id":"5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10","url":"https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU","expiresAt":"2026-10-10T14:00:00.000Z","externalId":"cliente-8841","redirectUrl":"https://app.exemplo.com.br/whatsapp/conectado","displayName":"Escritório Silva & Filhos"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"connection_not_released":{"summary":"Account not yet released to connect","value":{"error":"connection_not_released","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.","faltando":["email_confirmado"]}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_capacity_reached":{"summary":"The account is already at its number capacity","value":{"error":"number_capacity_reached","message":"Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.","capacity":20,"activeNumbers":20}},"reconnect_not_applicable":{"summary":"The authorization does not allow reconnection","value":{"error":"reconnect_not_applicable","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"A autorização deste número não admite reconexão.","credentialStatus":"active"}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-onboarding-links"}},"get":{"summary":"List connect links","tags":["Connection links"],"description":"The links you created, newest first, revoked ones included. Filters: externalId (exact), q (start of the externalId) and status (open, used, expired or revoked).","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"q","required":false,"description":"O começo do rótulo do seu cliente: os links cujo externalId começa com este texto, sem diferenciar maiúscula. Use no lugar de externalId quando você só lembra do começo. Combina com os outros filtros."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","required":false,"description":"O rótulo que você deu ao seu cliente (externalId): só os links dele. Igualdade exata; um rótulo sem link devolve lista vazia."},{"schema":{"type":"string","enum":["open","used","expired","revoked"]},"in":"query","name":"status","required":false,"description":"Só os links neste estado: open, used, expired ou revoked."},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","maxLength":256},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","used","expired","revoked"],"description":"open: o cliente ainda pode abrir. used: uma conexão feita por este link já concluiu. expired: passou do prazo sem ser usado. revoked: você revogou, e revokedAt diz quando (vale mais que os outros)."},"createdAt":{"type":"string","description":"Quando você criou o link."},"purpose":{"type":"string","enum":["new","reconnect"],"description":"new: o link conecta um número novo. reconnect: o link renova a autorização de um número que já existe (foi criado com numberId). Links criados antes deste campo existir têm a finalidade deduzida: com número e ainda não usados são reconnect."},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando você revogou o link, ou nulo se não foi revogado."},"lastFailure":{"anyOf":[{"type":"object","properties":{"step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado."},"reason":{"type":"string","description":"Por que a última tentativa não deu certo: abandoned, error, failed, country_not_supported ou registration_blocked, os mesmos de onboarding.link.failed. Novos motivos podem aparecer."},"at":{"type":"string","description":"Quando a tentativa parou."}},"required":["step","reason","at"],"additionalProperties":false},{"type":"null"}],"description":"A última tentativa de conexão por este link que não deu certo, ou nulo quando a última tentativa não falhou ou não houve nenhuma. É a mesma regra do evento onboarding.link.failed."},"allowedActions":{"type":"array","items":{"type":"string","enum":["revoke","reissue"]},"description":"O que a sua conta pode fazer com o link agora, só num link aberto: revoke (DELETE /v1/onboarding/links/{id}) e reissue (POST /v1/onboarding/links/{id}/reissue, que gera a url de novo). Não leva em conta os escopos da chave que perguntou."},"expiresAt":{"type":"string"},"usedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Para onde a página do link leva o seu cliente ao terminar, ou nulo se ele fica na página."},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do seu cliente que a página do link mostra, ou nulo."},"numberId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O id do número que resultou da conexão, o mesmo de GET /v1/numbers. Nulo até a Luna registrar o número, e nulo quando a conta foi conectada sem número. Em um link de reconexão (criado com numberId), é o número que o link reconecta, desde a criação."}},"required":["id","externalId","status","createdAt","purpose","revokedAt","lastFailure","allowedActions","expiresAt","usedAt","redirectUrl","displayName","numberId"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-onboarding-links"}}},"/v1/onboarding/links/{id}":{"get":{"summary":"Read a connect link","tags":["Connection links"],"description":"A link's state: open, used, expired or revoked, with its purpose, its last failure and what the account can do with it.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","used","expired","revoked"],"description":"open: o cliente ainda pode abrir. used: uma conexão feita por este link já concluiu. expired: passou do prazo sem ser usado. revoked: você revogou, e revokedAt diz quando (vale mais que os outros)."},"createdAt":{"type":"string","description":"Quando você criou o link."},"purpose":{"type":"string","enum":["new","reconnect"],"description":"new: o link conecta um número novo. reconnect: o link renova a autorização de um número que já existe (foi criado com numberId). Links criados antes deste campo existir têm a finalidade deduzida: com número e ainda não usados são reconnect."},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando você revogou o link, ou nulo se não foi revogado."},"lastFailure":{"anyOf":[{"type":"object","properties":{"step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado."},"reason":{"type":"string","description":"Por que a última tentativa não deu certo: abandoned, error, failed, country_not_supported ou registration_blocked, os mesmos de onboarding.link.failed. Novos motivos podem aparecer."},"at":{"type":"string","description":"Quando a tentativa parou."}},"required":["step","reason","at"],"additionalProperties":false},{"type":"null"}],"description":"A última tentativa de conexão por este link que não deu certo, ou nulo quando a última tentativa não falhou ou não houve nenhuma. É a mesma regra do evento onboarding.link.failed."},"allowedActions":{"type":"array","items":{"type":"string","enum":["revoke","reissue"]},"description":"O que a sua conta pode fazer com o link agora, só num link aberto: revoke (DELETE /v1/onboarding/links/{id}) e reissue (POST /v1/onboarding/links/{id}/reissue, que gera a url de novo). Não leva em conta os escopos da chave que perguntou."},"expiresAt":{"type":"string"},"usedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Para onde a página do link leva o seu cliente ao terminar, ou nulo se ele fica na página."},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do seu cliente que a página do link mostra, ou nulo."},"numberId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O id do número que resultou da conexão, o mesmo de GET /v1/numbers. Nulo até a Luna registrar o número, e nulo quando a conta foi conectada sem número. Em um link de reconexão (criado com numberId), é o número que o link reconecta, desde a criação."}},"required":["id","externalId","status","createdAt","purpose","revokedAt","lastFailure","allowedActions","expiresAt","usedAt","redirectUrl","displayName","numberId"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-onboarding-links-id"}},"delete":{"summary":"Revoke a connect link","tags":["Connection links"],"description":"Revokes the link. The url stops working at once and answers 404 to whoever opens it, like one that never existed. A connection the customer had already started in Meta's window can no longer be completed through it. The link stays in your list, with status revoked and revokedAt. Revoking an already revoked link answers 404.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-delete-v1-onboarding-links-id"}}},"/v1/onboarding/links/batch":{"post":{"summary":"Create several connect links at once","tags":["Connection links"],"description":"Creates up to 100 links, each item in the same shape as POST /v1/onboarding/links and under the same rules, plan capacity included. Answers 200 with one result per item, with the url of each created link; an item that fails does not bring the others down.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"links":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"description":"O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão."},"displayName":{"description":"O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra (\"Conectar o WhatsApp de ...\"). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada.","type":"string","minLength":1,"maxLength":120},"redirectUrl":{"description":"Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna.","type":"string","maxLength":2048,"pattern":"^https:\\/\\/[^\\s]+$"},"numberId":{"description":"O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova.","type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}}},"description":"De 1 a 100 links, cada um no mesmo formato do corpo de POST /v1/onboarding/links: externalId, displayName, redirectUrl e numberId, todos opcionais."}},"required":["links"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"A posição do item em links, a partir de 0."},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"201 quando o link foi criado; senão o status do erro daquele item."},"link":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","description":"O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta."},"expiresAt":{"type":"string"},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A redirectUrl do pedido, ou nulo."},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do seu cliente que a página do link mostra, ou nulo."}},"required":["id","url","expiresAt","externalId","redirectUrl","displayName"],"additionalProperties":false,"example":{"id":"5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10","url":"https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU","expiresAt":"2026-10-10T14:00:00.000Z","externalId":"cliente-8841","redirectUrl":"https://app.exemplo.com.br/whatsapp/conectado","displayName":"Escritório Silva & Filhos"}},{"type":"null"}],"description":"O link criado, com a url (que aparece só aqui). Nulo quando houve erro."},"error":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":{}},{"type":"null"}],"description":"O erro deste item, no mesmo formato de erro da API. Nulo quando o link foi criado."}},"required":["index","status","link","error"],"additionalProperties":false},"description":"Um resultado por item de links, na mesma ordem."}},"required":["results"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"connection_not_released":{"summary":"Account not yet released to connect","value":{"error":"connection_not_released","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.","faltando":["email_confirmado"]}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write"}},"/v1/onboarding/links/{id}/reissue":{"post":{"summary":"Generate the url of a connect link again","tags":["Connection links"],"description":"Generates a new token for the same link (same id, label and expiry): the old url stops working at once and the new one appears only in this response. Only for an open link; used, expired or revoked answers 409. Use it when your customer lost the url, instead of revoking and creating another.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","description":"O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta."},"expiresAt":{"type":"string"},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A redirectUrl do pedido, ou nulo."},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do seu cliente que a página do link mostra, ou nulo."}},"required":["id","url","expiresAt","externalId","redirectUrl","displayName"],"additionalProperties":false,"example":{"id":"5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10","url":"https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU","expiresAt":"2026-10-10T14:00:00.000Z","externalId":"cliente-8841","redirectUrl":"https://app.exemplo.com.br/whatsapp/conectado","displayName":"Escritório Silva & Filhos"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"link_not_open":{"summary":"Link that is not open","value":{"error":"link_not_open","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Só um link aberto pode ser reemitido, e este está usado. Crie um link novo com POST /v1/onboarding/links.","status":"used"}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"onboarding:write"}},"/v1/public/onboarding-links/{token}":{"get":{"summary":"Read the connect link (customer page)","tags":["Console and public pages"],"description":"For the page your customer opens. Returns the name of the account that asked for the connection, the link status, and the public identifiers of the Meta app that the connection window uses. Nothing else about your account comes out here.","parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"accountName":{"type":"string","description":"O nome da conta que pediu a conexão."},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do cliente para quem o link foi criado (displayName do link), ou nulo. A página o mostra para o cliente reconhecer o pedido."},"status":{"type":"string","enum":["open","used","expired"]},"expiresAt":{"type":"string"},"metaAppId":{"type":"string"},"metaConfigId":{"type":"string"},"sdkVersion":{"type":"string","description":"A versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código."},"redirectUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Para onde a página leva o cliente quando a conexão termina, ou nulo para ficar na página."},"reconnect":{"type":"boolean","description":"true quando o link está aberto e reconecta um número que já existe (foi criado com numberId): a página deve falar em renovar a autorização, e não em conectar um número novo. Num link já usado é sempre false."}},"required":["accountName","displayName","status","expiresAt","metaAppId","metaConfigId","sdkVersion","redirectUrl","reconnect"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-public-onboarding-links-token"}}},"/v1/public/onboarding-links/{token}/sessions":{"post":{"summary":"Open the connection session through the link","tags":["Console and public pages"],"description":"Opens the session that Meta's window fills in, for the account that owns the link. It is the same opening as POST /v1/onboarding/sessions, through the token's door. On a reconnection link (created with numberId), the session is born bound to the number's account, as in POST /v1/onboarding/reconnect.","parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string"},"configId":{"type":"string"},"sdkVersion":{"type":"string","description":"A versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código."},"csrfState":{"type":"string"},"expiresAt":{"type":"string"}},"required":["sessionId","state","configId","sdkVersion","csrfState","expiresAt"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"account_at_capacity":{"summary":"The account that requested the link reached its maximum of numbers","value":{"error":"account_at_capacity","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"A conta que pediu esta conexão atingiu o máximo de números. Avise quem enviou este link: assim que ela abrir uma vaga, ele poderá enviar um link novo."}}}}}},"410":{"description":"The connect link expired or was already used. The error field says which of the two.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"link_expired":{"summary":"Link expired","value":{"error":"link_expired","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Este link venceu. Peça um novo a quem enviou este."}},"link_used":{"summary":"Link already used","value":{"error":"link_used","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions"}}},"/v1/public/onboarding-links/{token}/sessions/{sessionId}/complete":{"post":{"summary":"Complete the connection through the link","tags":["Console and public pages"],"description":"Exchanges the code from Meta's window for access to the customer's account. It is the same completion as POST /v1/onboarding/sessions/{id}/complete, through the token's door, and the same warning holds: the code lasts 30 seconds, so call it the moment it arrives.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1},"csrfState":{"type":"string","minLength":1},"wabaId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"phoneNumberId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"businessId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["code","csrfState"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"sessionId","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"state":{"type":"string"},"orientacao":{"type":"string"},"terminal":{"type":"boolean"},"motivo":{"anyOf":[{"type":"string"},{"type":"null"}]},"podeRetentar":{"type":"boolean"},"numberId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O número que resultou da conexão, quando a Luna já o registrou. Nulo logo depois de concluir: o registro acontece em seguida, e o seu servidor sabe quando ele fica pronto pelo evento number.connected."},"returnUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Para onde a página leva o cliente: a redirectUrl do link com status, numberId, externalId e signature na query. Nulo quando o link não tem redirectUrl ou a conexão ainda não aconteceu."}},"required":["sessionId","state","orientacao","terminal","motivo","podeRetentar","numberId","returnUrl"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"410":{"description":"The connect link expired or was already used. The error field says which of the two.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"link_used":{"summary":"Link already used","value":{"error":"link_used","docsUrl":"https://lunahia.com.br/docs/conectar-numero","message":"Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions-sessionid-complete"}}},"/v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon":{"post":{"summary":"Report an abandoned or failed flow through the link","tags":["Console and public pages"],"description":"Telemetry about what happened in Meta's window when the customer did not complete. It is the same report as POST /v1/onboarding/sessions/{id}/abandon, through the token's door, and it only applies to a session opened by this same link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csrfState":{"type":"string","minLength":1},"currentStep":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["csrfState"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"sessionId","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"state":{"type":"string"},"orientacao":{"type":"string"},"abandonedAtStep":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sessionId","state","orientacao","abandonedAtStep"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions-sessionid-abandon"}}},"/v1/operators/signup":{"post":{"summary":"Create an account","tags":["Console and public pages"],"description":"Creates the account and its first operator, in a single call and with no credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254},"password":{"type":"string","minLength":12,"maxLength":512},"tenantName":{"type":"string","minLength":1,"maxLength":120}},"required":["email","password","tenantName"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"nextStep":{"type":"string","enum":["login"]}},"required":["nextStep"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-signup"}}},"/v1/operators/confirm":{"get":{"summary":"Confirm an account's email","tags":["Console and public pages"],"description":"Destination of the link sent by email when the account is created. It answers with a redirect to the console, and not with JSON, because a person in a browser is what opens it.","parameters":[{"schema":{"type":"string","maxLength":512},"in":"query","name":"token","required":false}],"responses":{"200":{"description":"Success."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-operators-confirm"}}},"/v1/operators/password/forgot":{"post":{"summary":"Ask for a password reset","tags":["Console and public pages"],"description":"Asks for a link to choose a new password. It takes only the account email.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254}},"required":["email"]}}}},"responses":{"202":{"description":"Accepted: the request was recorded and will be processed.","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]}},"required":["accepted"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-password-forgot"}}},"/v1/operators/password/reset":{"post":{"summary":"Choose a new password","tags":["Console and public pages"],"description":"Changes the operator's password from the token in the link sent by email, and answers 204.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","maxLength":512},"password":{"type":"string","minLength":12,"maxLength":512}},"required":["token","password"]}}}},"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErroDeValidacao"},{"$ref":"#/components/schemas/Erro"}]},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}},"invalid_reset_token":{"summary":"Invalid reset link","value":{"error":"invalid_reset_token","docsUrl":"https://lunahia.com.br/docs/conta-e-chaves","message":"O link de redefinição não vale mais. Peça um novo."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-password-reset"}}},"/v1/operators/password/reset/check":{"post":{"summary":"Check the reset link","tags":["Console and public pages"],"description":"Answers 204 when the link token is still valid and 400 when it is not, without consuming it. Lets the screen warn before the person types the new password.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","maxLength":512}},"required":["token"]}}}},"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErroDeValidacao"},{"$ref":"#/components/schemas/Erro"}]},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}},"invalid_reset_token":{"summary":"Invalid reset link","value":{"error":"invalid_reset_token","docsUrl":"https://lunahia.com.br/docs/conta-e-chaves","message":"O link de redefinição não vale mais. Peça um novo."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[]}},"/v1/public/password-policy":{"get":{"summary":"Read the password rule","tags":["Console and public pages"],"description":"The minimum length of an operator password, the same at signup, reset and change. It asks for no credential.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"minLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"O mínimo de caracteres de uma senha de operador: no cadastro, na redefinição e na troca. Não há exigência de maiúscula, número ou símbolo."}},"required":["minLength"],"additionalProperties":false,"example":{"minLength":12}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[]}},"/v1/operators/password/change":{"post":{"summary":"Change the password","tags":["Console and public pages"],"description":"Changes the password of the operator behind the presented session, checking the current password, and answers 204. The operator's other sessions are ended and the presented one stays valid. A wrong current password, or a credential with no operator (an integration key), answers 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currentPassword":{"type":"string","maxLength":512,"description":"A senha de hoje do operador da sessão."},"newPassword":{"type":"string","minLength":12,"maxLength":512,"description":"A senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo)."}},"required":["currentPassword","newPassword"]}}}},"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"session:elevate"}},"/v1/account":{"get":{"summary":"Read your own account","tags":["Account and plan"],"description":"Returns the account behind the credential presented: identifier, name, whether the email has been confirmed, and when the account was created.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"emailConfirmed":{"type":"boolean"},"createdAt":{"type":"string"},"operatorEmail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","emailConfirmed","createdAt","operatorEmail"],"additionalProperties":false}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-account"}},"patch":{"summary":"Rename the account","tags":["Account and plan"],"description":"Changes the account name, the same one GET /v1/account returns. Returns the account with the new name. Only the console session does this.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro."}},"required":["name"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"emailConfirmed":{"type":"boolean"},"createdAt":{"type":"string"},"operatorEmail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","emailConfirmed","createdAt","operatorEmail"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"session:end"}},"/v1/operators/confirmation/resend":{"post":{"summary":"Resend the confirmation email","tags":["Console and public pages"],"description":"Sends the confirmation link again to the email of the operator behind the session, and invalidates the previous link if it had not been opened. The new link is valid for seven days and is accepted a single time.","responses":{"202":{"description":"Accepted: the request was recorded and will be processed.","content":{"application/json":{"schema":{"type":"object","properties":{"emailConfirmed":{"type":"boolean"}},"required":["emailConfirmed"],"additionalProperties":false}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"session:end","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-confirmation-resend"}}},"/v1/operators/login":{"post":{"summary":"Authenticate an operator","tags":["Console and public pages"],"description":"Exchanges email and password for an eight hour session credential, used by the web console.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","minLength":1,"maxLength":254},"password":{"type":"string","minLength":1,"maxLength":512}},"required":["email","password"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"operatorId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"token":{"type":"string"},"expiresAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["tenantId","operatorId","token","expiresAt","scopes"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"security":[],"externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-login"}}},"/v1/operators/step-up":{"post":{"summary":"Re-authenticate for a sensitive action","tags":["Console and public pages"],"description":"Confirms the password of the operator behind the session presented, and opens a two hour window in which that same session can create and revoke API keys.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","minLength":1,"maxLength":512}},"required":["password"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"elevatedUntil":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["elevatedUntil","scopes"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"session:elevate","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-step-up"}}},"/v1/operators/session":{"get":{"summary":"Read the presented session","tags":["Console and public pages"],"description":"When the presented credential expires, until when the elevation opened by POST /v1/operators/step-up lasts (null with no elevation or with the window closed) and the scopes it has now. It reads only the credential itself: the identifier comes from authentication and never from the path.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a credencial apresentada expira. Nulo numa chave de integração, que vale até ser revogada."},"elevatedUntil":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Até quando vale a elevação aberta por POST /v1/operators/step-up, que deixa a sessão criar e revogar chaves. Nulo sem elevação ou com a janela já fechada: nesse caso, peça a senha de novo."},"scopes":{"type":"array","items":{"type":"string"},"description":"Os escopos da credencial agora, já contando os emprestados pela elevação enquanto a janela está aberta."}},"required":["expiresAt","elevatedUntil","scopes"],"additionalProperties":false,"example":{"expiresAt":"2026-11-03T20:00:00.000Z","elevatedUntil":"2026-11-03T14:30:00.000Z","scopes":["numbers:read","session:end","session:elevate","keys:write"]}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"session:end"}},"/v1/operators/logout":{"post":{"summary":"End the session","tags":["Console and public pages"],"description":"Revokes the credential presented, and only it. The identifier comes from the authentication itself and never from the body, so this route cannot revoke someone else's key.","responses":{"204":{"description":"No content: the operation was done and the response has no body."},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"session:end"}},"/v1/numbers/{id}/health":{"get":{"summary":"Read the health of a phone number","tags":["Phone numbers"],"description":"The quality rating, throughput level and daily conversation limit Meta assigns to this number right now, and the changes the platform has observed over time.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"path","name":"id","required":true,"description":"O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"qualityRating":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"GREEN"},"throughputLevel":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"HIGH"},"tetoDeVazaoPorSegundo":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O teto de envio deste número em mensagens por segundo, quando ele é FIXO e não sobe. Números conectados em coexistência, que continuam funcionando no aplicativo de celular do negócio, têm esse teto fixo pela plataforma da Meta, e ele não acompanha a progressão de throughputLevel. Nulo significa o contrário: este número segue a progressão da Meta, e quem a descreve é throughputLevel. Não é contagem de nada e não muda com o que o número enviou: é a capacidade que a plataforma da Meta concede.","example":null},"sincronizacaoDoHistorico":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Em que pé está a importação das conversas anteriores do aparelho do negócio, num número conectado em coexistência. São quatro situações e cada uma pede uma reação diferente. Nulo significa que não há importação para este número, e não que ela parou. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele: não vai concluir, e pedir de novo não muda isso. Atenção ao ler sincronizacaoProgresso junto: cem por cento não significa sucesso, porque a recusa chega com o progresso que já havia sido registrado.","example":"em_curso"},"sincronizacaoPrazo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Até quando a importação precisa terminar. Passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. Sai sempre como instante em UTC, e nunca como texto do tipo faltam tantas horas: um texto desses fica errado na tela de quem a deixou aberta, e quem integra pela API precisa de um valor comparável com o próprio relógio. Nulo quando não há importação em curso conhecida.","example":"2026-09-19T09:00:00.000Z"},"sincronizacaoProgresso":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O rótulo de progresso que a plataforma da Meta atribui à importação, de 0 a 100. É um rótulo e não uma contagem: ele chega a 100 igualmente para um aparelho com poucas conversas antigas e para um com muitas, e nada nele cresce com o tamanho do que foi importado. Não use este campo para deduzir quantidade, porque ele não carrega nenhuma. Nulo quando a plataforma da Meta ainda não informou progresso para este número.","example":40},"limiteDiarioDeConversas":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"TIER_10K"},"codeVerificationStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"VERIFIED"},"checkedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"2026-08-26T12:00:00.000Z"},"transitions":{"type":"array","items":{"type":"object","properties":{"qualityRating":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"GREEN"},"throughputLevel":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"HIGH"},"limiteDiarioDeConversas":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"TIER_2K"},"codeVerificationStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"VERIFIED"},"observedAt":{"type":"string","example":"2026-08-24T10:00:00.000Z"}},"required":["qualityRating","throughputLevel","limiteDiarioDeConversas","codeVerificationStatus","observedAt"],"additionalProperties":false}}},"required":["id","qualityRating","throughputLevel","tetoDeVazaoPorSegundo","sincronizacaoDoHistorico","sincronizacaoPrazo","sincronizacaoProgresso","limiteDiarioDeConversas","codeVerificationStatus","checkedAt","transitions"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/account-health#rota-get-v1-numbers-id-health"}}},"/v1/templates":{"post":{"summary":"Create a template","tags":["Templates"],"description":"Creates the template in the customer's account and submits it to Meta for approval.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wabaId":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"name":{"type":"string","pattern":"^[a-z0-9_]{1,512}$"},"bodyText":{"type":"string","minLength":1,"maxLength":1024},"examples":{"example":{"primeiro_nome":"Maria","pedido":"88213"},"description":"Um valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo.","type":"object","propertyNames":{"type":"string","pattern":"^[a-z0-9_]+$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":512}},"header":{"type":"string","minLength":1,"maxLength":60,"description":"Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia."},"headerMedia":{"type":"object","properties":{"format":{"type":"string","enum":["IMAGE","VIDEO","DOCUMENT"],"description":"IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF."},"handle":{"type":"string","minLength":1,"maxLength":2048,"description":"O handle devolvido por POST /v1/template-assets."}},"required":["format","handle"],"additionalProperties":false,"description":"Cabeçalho de imagem, vídeo ou documento. O handle vem de POST /v1/template-assets, e não do identificador de mídia de mensagem. O arquivo é o exemplo que a Meta revisa, e não o conteúdo entregue: cada mensagem enviada fornece a própria mídia."},"footer":{"type":"string","minLength":1,"maxLength":60,"description":"Rodapé, exibido abaixo do corpo. Não aceita variável."},"buttons":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY"]},"text":{"type":"string","minLength":1,"maxLength":25}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["URL"]},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","minLength":1,"maxLength":2000},"example":{"maxItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}}},"required":["type","text","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["PHONE_NUMBER"]},"text":{"type":"string","minLength":1,"maxLength":25},"phone_number":{"type":"string","minLength":1,"maxLength":20}},"required":["type","text","phone_number"]},{"type":"object","properties":{"type":{"type":"string","enum":["COPY_CODE"]},"example":{"type":"string","minLength":1,"maxLength":20}},"required":["type","example"]}]},"description":"Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois."},"category":{"type":"string","enum":["MARKETING","UTILITY"],"example":"UTILITY","description":"A categoria do template. Ausente vale UTILITY, que é o comportamento de quem já integra e não manda o campo. A Meta pode reclassificar na criação: o template continua aprovado, com outra categoria, e a resposta traz a que ela atribuiu. Template de autenticação tem corpo próprio e ainda não é criado por esta rota."},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$","example":"pt_BR","description":"O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business."}},"required":["wabaId","name","bodyText"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaTemplateId":{"type":"string"},"wabaId":{"type":"string","description":"O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe."},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","metaTemplateId","wabaId","name","language","category","status","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-post-v1-templates"}},"get":{"summary":"List templates","tags":["Templates"],"description":"This customer's templates, newest first.","parameters":[{"schema":{"example":"PAUSED","type":"string","minLength":1,"maxLength":64},"in":"query","name":"status","required":false,"description":"Devolve apenas os templates cujo último estado observado é exatamente este valor. A comparação é literal e sensível a maiúsculas. Valores comuns: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, mas o campo é texto livre, porque a Meta acrescenta estado sem aviso e um conjunto fechado impediria você de filtrar pelo estado novo."},{"schema":{"example":"102290129340398","type":"string","minLength":1,"maxLength":64},"in":"query","name":"wabaId","required":false,"description":"Devolve apenas os templates desta conta de negócio na Meta (WABA), o wabaId que GET /v1/business-accounts devolve. Com um cliente seu por conta, é o jeito de ver só os templates dele. Comparação exata."},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"query","name":"phoneNumberId","required":false,"description":"Devolve apenas os templates da conta de negócio a que este número pertence. Aceita o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Template é da conta, e não do número: todos os números da conta compartilham os mesmos templates."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaTemplateId":{"type":"string"},"wabaId":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"bodyText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O corpo do template, com as variáveis na forma {{nome}}. Nulo quando a Luna não conhece o conteúdo: template criado antes de ela passar a guardá-lo, ou direto no painel da Meta. Nesse caso header, footer, buttons e variables também vêm vazios."},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cabeçalho de texto. Nulo quando não há."},"headerMedia":{"anyOf":[{"type":"object","properties":{"format":{"type":"string","description":"IMAGE, VIDEO ou DOCUMENT."}},"required":["format"],"additionalProperties":false},{"type":"null"}],"description":"O cabeçalho de imagem, vídeo ou documento: só o formato, porque o arquivo era o exemplo que a Meta revisou. Nulo quando não há."},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rodapé. Nulo quando não há."},"buttons":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY"]},"text":{"type":"string","minLength":1,"maxLength":25}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["URL"]},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","minLength":1,"maxLength":2000},"example":{"maxItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}}},"required":["type","text","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["PHONE_NUMBER"]},"text":{"type":"string","minLength":1,"maxLength":25},"phone_number":{"type":"string","minLength":1,"maxLength":20}},"required":["type","text","phone_number"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["COPY_CODE"]},"example":{"type":"string","minLength":1,"maxLength":20}},"required":["type","example"],"additionalProperties":false}]},"description":"Os botões, na mesma forma em que POST /v1/templates os recebe. Vazio quando não há, ou quando o conteúdo é desconhecido."},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"O nome da variável, o que está entre {{ e }} no corpo."},"example":{"type":"string","description":"O exemplo que foi mandado para a Meta junto com a variável."}},"required":["name","example"],"additionalProperties":false},"description":"As variáveis do corpo, na ordem em que aparecem, cada uma com o exemplo. A tela não precisa extrair {{nome}} do texto."},"rejectedReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Por que a Meta rejeitou o template, como ela informou (o valor entra como veio). Só tem valor enquanto status é REJECTED, e nulo quando a Meta não mandou a razão."},"qualityScore":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A nota de qualidade do template segundo o último aviso da Meta, como ela informou: GREEN, YELLOW, RED ou UNKNOWN, e valores novos podem aparecer. Nulo enquanto a Meta não avisou nenhuma."},"previousCategory":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou."},"allowedActions":{"type":"array","items":{"type":"string","enum":["edit","delete"]},"description":"O que a conta pode fazer com o template agora: edit (PATCH /v1/templates/{id}) e delete (DELETE /v1/templates/{id}). Vazio com a conta suspensa. Em quais estados a Meta aceita editar é decisão dela, e a recusa dela chega como erro."}},"required":["id","metaTemplateId","wabaId","name","language","category","status","createdAt","updatedAt","bodyText","header","headerMedia","footer","buttons","variables","rejectedReason","qualityScore","previousCategory","allowedActions"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false,"example":{"data":[{"id":"ae60f288-7565-4315-a440-3663e9c231e1","metaTemplateId":"1259544702043801","wabaId":"102290129340398","name":"numero_conectado","language":"pt_BR","category":"UTILITY","status":"APPROVED","createdAt":"2026-08-10T12:24:02.085Z","updatedAt":"2026-08-10T12:31:47.004Z","bodyText":"Olá {{primeiro_nome}}, o seu número foi conectado.","header":null,"headerMedia":null,"footer":null,"buttons":[],"variables":[{"name":"primeiro_nome","example":"Maria"}],"rejectedReason":null,"qualityScore":"GREEN","previousCategory":null,"allowedActions":["edit","delete"]}]}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-get-v1-templates"}}},"/v1/templates/{id}":{"get":{"summary":"Read a template","tags":["Templates"],"description":"The template's current state at Meta, the content you wrote, and what Meta announced about it.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaTemplateId":{"type":"string"},"wabaId":{"type":"string","description":"O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe."},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"bodyText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O corpo do template, com as variáveis na forma {{nome}}. Nulo quando a Luna não conhece o conteúdo: template criado antes de ela passar a guardá-lo, ou direto no painel da Meta. Nesse caso header, footer, buttons e variables também vêm vazios."},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O cabeçalho de texto. Nulo quando não há."},"headerMedia":{"anyOf":[{"type":"object","properties":{"format":{"type":"string","description":"IMAGE, VIDEO ou DOCUMENT."}},"required":["format"],"additionalProperties":false},{"type":"null"}],"description":"O cabeçalho de imagem, vídeo ou documento: só o formato, porque o arquivo era o exemplo que a Meta revisou. Nulo quando não há."},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rodapé. Nulo quando não há."},"buttons":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY"]},"text":{"type":"string","minLength":1,"maxLength":25}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["URL"]},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","minLength":1,"maxLength":2000},"example":{"maxItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}}},"required":["type","text","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["PHONE_NUMBER"]},"text":{"type":"string","minLength":1,"maxLength":25},"phone_number":{"type":"string","minLength":1,"maxLength":20}},"required":["type","text","phone_number"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["COPY_CODE"]},"example":{"type":"string","minLength":1,"maxLength":20}},"required":["type","example"],"additionalProperties":false}]},"description":"Os botões, na mesma forma em que POST /v1/templates os recebe. Vazio quando não há, ou quando o conteúdo é desconhecido."},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"O nome da variável, o que está entre {{ e }} no corpo."},"example":{"type":"string","description":"O exemplo que foi mandado para a Meta junto com a variável."}},"required":["name","example"],"additionalProperties":false},"description":"As variáveis do corpo, na ordem em que aparecem, cada uma com o exemplo. A tela não precisa extrair {{nome}} do texto."},"rejectedReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Por que a Meta rejeitou o template, como ela informou (o valor entra como veio). Só tem valor enquanto status é REJECTED, e nulo quando a Meta não mandou a razão."},"qualityScore":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A nota de qualidade do template segundo o último aviso da Meta, como ela informou: GREEN, YELLOW, RED ou UNKNOWN, e valores novos podem aparecer. Nulo enquanto a Meta não avisou nenhuma."},"previousCategory":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou."},"allowedActions":{"type":"array","items":{"type":"string","enum":["edit","delete"]},"description":"O que a conta pode fazer com o template agora: edit (PATCH /v1/templates/{id}) e delete (DELETE /v1/templates/{id}). Vazio com a conta suspensa. Em quais estados a Meta aceita editar é decisão dela, e a recusa dela chega como erro."}},"required":["id","metaTemplateId","wabaId","name","language","category","status","createdAt","updatedAt","bodyText","header","headerMedia","footer","buttons","variables","rejectedReason","qualityScore","previousCategory","allowedActions"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-get-v1-templates-id"}},"patch":{"summary":"Edit a template","tags":["Templates"],"description":"Changes the components of an existing template.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bodyText":{"type":"string","minLength":1,"maxLength":1024},"examples":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z0-9_]+$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":512}},"header":{"type":"string","minLength":1,"maxLength":60,"description":"Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia."},"footer":{"type":"string","minLength":1,"maxLength":60,"description":"Rodapé, exibido abaixo do corpo. Não aceita variável."},"buttons":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY"]},"text":{"type":"string","minLength":1,"maxLength":25}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["URL"]},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","minLength":1,"maxLength":2000},"example":{"maxItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}}},"required":["type","text","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["PHONE_NUMBER"]},"text":{"type":"string","minLength":1,"maxLength":25},"phone_number":{"type":"string","minLength":1,"maxLength":20}},"required":["type","text","phone_number"]},{"type":"object","properties":{"type":{"type":"string","enum":["COPY_CODE"]},"example":{"type":"string","minLength":1,"maxLength":20}},"required":["type","example"]}]},"description":"Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois."}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaTemplateId":{"type":"string"},"wabaId":{"type":"string","description":"O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe."},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","metaTemplateId","wabaId","name","language","category","status","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-patch-v1-templates-id"}},"delete":{"summary":"Delete a template","tags":["Templates"],"description":"Deletes the template at Meta and from your listing.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-delete-v1-templates-id"}}},"/v1/templates/rules":{"get":{"summary":"Read the template rules","tags":["Templates"],"description":"The categories, the suggested languages, the name format, the maximum lengths of body, header and footer, and the button limits. It is what POST /v1/templates enforces, served so you can show the same limit without copying the number.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"O que vai em category ao criar o template."},"label":{"type":"string","description":"O nome da categoria, em português."},"summary":{"type":"string","description":"Quando usar, em uma ou duas frases."}},"required":["value","label","summary"],"additionalProperties":false},"description":"As categorias que a criação aceita. A Meta pode reclassificar o template depois."},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}},"required":["code","label"],"additionalProperties":false},"description":"Idiomas sugeridos. Não é lista fechada: vale qualquer código que a Meta publique, no formato de language em POST /v1/templates."},"namePattern":{"type":"string","description":"A expressão regular que o name precisa cumprir, em sintaxe de JavaScript e sem as barras."},"nameExample":{"type":"string","description":"Um nome que cumpre namePattern."},"bodyMaxLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Caracteres do corpo."},"headerMaxLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Caracteres do cabeçalho de texto."},"footerMaxLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Caracteres do rodapé."},"buttonLimits":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Botões de todos os tipos, somados."},"byType":{"type":"object","properties":{"QUICK_REPLY":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"URL":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"PHONE_NUMBER":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"COPY_CODE":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE"],"additionalProperties":false,"description":"O máximo de cada tipo."}},"required":["total","byType"],"additionalProperties":false,"description":"Os limites de botões. Resposta rápida junto de outros tipos precisa formar dois grupos: as respostas rápidas de um lado, os outros do outro."}},"required":["categories","languages","namePattern","nameExample","bodyMaxLength","headerMaxLength","footerMaxLength","buttonLimits"],"additionalProperties":false,"example":{"categories":[{"value":"MARKETING","label":"Marketing","summary":"Promove, convida ou tenta reengajar: oferta, novidade, carrinho esquecido. A Meta pode reclassificar um template de utilidade para marketing."}],"languages":[{"code":"pt_BR","label":"Português (Brasil)"}],"namePattern":"^[a-z0-9_]{1,512}$","nameExample":"confirmacao_do_pedido","bodyMaxLength":1024,"headerMaxLength":60,"footerMaxLength":60,"buttonLimits":{"total":10,"byType":{"QUICK_REPLY":10,"URL":2,"PHONE_NUMBER":1,"COPY_CODE":1}}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:read"}},"/v1/templates/authentication":{"post":{"summary":"Create an authentication template","tags":["Templates"],"description":"Creates an authentication template with a copy code button, and submits it to Meta for approval.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wabaId":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"name":{"type":"string","pattern":"^[a-z0-9_]{1,512}$"},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$","example":"pt_BR","description":"O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business."},"addSecurityRecommendation":{"type":"boolean","example":true,"description":"Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso."},"codeExpirationMinutes":{"type":"integer","minimum":1,"maximum":1440,"example":10,"description":"Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela."},"buttonText":{"type":"string","minLength":1,"maxLength":25,"example":"Copiar código","description":"O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres."},"messageSendTtlSeconds":{"type":"integer","minimum":1,"maximum":9007199254740991,"example":60,"description":"Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe."}},"required":["wabaId","name","codeExpirationMinutes"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaTemplateId":{"type":"string"},"wabaId":{"type":"string","description":"O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe."},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","metaTemplateId","wabaId","name","language","category","status","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-post-v1-templates-authentication"}}},"/v1/templates/{id}/copy":{"post":{"summary":"Copy a template to other customers","tags":["Templates"],"description":"Creates a copy of the template in up to 50 destinations, each a business account (wabaId) or a customer of yours (externalId). Answers 200 with one result per destination, and a destination that fails does not bring the others down. The copy goes through the same path and the same rules as POST /v1/templates.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targets":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"wabaId":{"description":"A conta de negócio de destino, pelo id dela na Meta (wabaId).","type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"externalId":{"description":"O rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele.","type":"string","minLength":1,"maxLength":128}},"additionalProperties":false},"description":"Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }."},"headerMediaHandle":{"description":"O handle do arquivo de exemplo do cabeçalho de mídia, para template de origem que tem um. A Luna guarda só o formato do cabeçalho, não o arquivo.","type":"string","minLength":1,"maxLength":1024},"authentication":{"description":"Os parâmetros do template de autenticação, obrigatórios quando o template de origem é de autenticação: a Luna não os guarda.","type":"object","properties":{"addSecurityRecommendation":{"type":"boolean","example":true,"description":"Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso."},"codeExpirationMinutes":{"type":"integer","minimum":1,"maximum":1440,"example":10,"description":"Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela."},"buttonText":{"type":"string","minLength":1,"maxLength":25,"example":"Copiar código","description":"O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres."},"messageSendTtlSeconds":{"type":"integer","minimum":1,"maximum":9007199254740991,"example":60,"description":"Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe."}},"required":["codeExpirationMinutes"],"additionalProperties":false}},"required":["targets"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"target":{"type":"object","properties":{"wabaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["wabaId","externalId"],"additionalProperties":false,"description":"O destino pedido, como veio."},"wabaId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A conta de negócio onde a cópia foi tentada. Nulo quando o externalId não resolveu para nenhuma conta."},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"201 quando a cópia foi criada; senão o status do erro daquele destino."},"template":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"metaTemplateId":{"type":"string"},"wabaId":{"type":"string","description":"O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe."},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","metaTemplateId","wabaId","name","language","category","status","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}],"description":"O template criado nesta conta. Nulo quando houve erro."},"error":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":{}},{"type":"null"}],"description":"O erro deste destino, no mesmo formato de erro da API. Nulo quando a cópia foi criada."}},"required":["target","wabaId","status","template","error"],"additionalProperties":false},"description":"Um resultado por destino (por conta, quando um externalId tem mais de uma)."}},"required":["results"],"additionalProperties":false}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"template_content_unknown":{"summary":"Luna does not know the template content","value":{"error":"template_content_unknown","docsUrl":"https://lunahia.com.br/docs/templates","message":"A Luna não conhece o conteúdo deste template: ele foi criado direto no painel da Meta, ou antes de a Luna guardar o conteúdo. Sem o conteúdo não há o que copiar. Crie o template de novo por POST /v1/templates e copie o novo."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:write"}},"/v1/template-assets":{"post":{"summary":"Upload the example file for a media header","tags":["Templates"],"description":"Takes a file in multipart/form-data under the field file and returns the handle that template creation accepts in headerMedia.handle.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","description":"O identificador do arquivo de exemplo. Use-o em headerMedia.handle ao criar o template."}},"required":["handle"],"additionalProperties":false,"example":{"handle":"4:cGVkaWRvLnBuZw==:aW1hZ2UvcG5n:ARb0Xk:e:1790451084:1269849425120687:0"}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"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"}},"trial_expired":{"summary":"Free trial ended","value":{"error":"trial_expired","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."}},"account_blocked":{"summary":"Account blocked by Helsen","value":{"error":"account_blocked","docsUrl":"https://lunahia.com.br/docs/plano-e-numeros","message":"Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"413":{"description":"The file is over the size ceiling, which is the same for every customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"file_too_large":{"summary":"File over the ceiling","value":{"error":"file_too_large","docsUrl":"https://lunahia.com.br/docs/enviar-mensagens","message":"O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"templates:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/templates#rota-post-v1-template-assets"},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload, in the file field."}},"required":["file"]}}}}}},"/v1/usage":{"get":{"summary":"Read the Meta usage of a number or a customer","tags":["Phone numbers"],"description":"The usage Meta measures for a number (numberId) or for all the numbers of one of your customers (externalId), passed through as Meta reports it, with each account's currency and no sums. format=csv returns text/csv. Luna only reads and shows it: none of it goes into the Luna subscription.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"in":"query","name":"numberId","required":false,"description":"O número a consultar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. Mande este ou externalId, nunca os dois."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","required":false,"description":"O rótulo do seu cliente (o externalId do link de conexão): lê o consumo de todos os números dele, cada um na moeda da conta dele. Mande este ou numberId, nunca os dois."},{"schema":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}]},"in":"query","name":"start","required":false,"description":"O começo do período, em ISO 8601 (data ou data e hora, em UTC). Ausente, o primeiro dia do mês corrente."},{"schema":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}]},"in":"query","name":"end","required":false,"description":"O fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos)."},{"schema":{"default":"DAILY","type":"string","enum":["HALF_HOUR","DAILY","MONTHLY"]},"in":"query","name":"granularity","required":false,"description":"O tamanho de cada ponto, no vocabulário da Meta: HALF_HOUR, DAILY (o padrão) ou MONTHLY. A Meta limita o período de cada um, e recusa o que passa do limite dela."},{"schema":{"default":"json","type":"string","enum":["json","csv"]},"in":"query","name":"format","required":false,"description":"json (o padrão) ou csv. O csv vem em text/csv, uma linha por ponto, com numberId, phoneNumberId e currency em cada linha, para planilha."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"numberId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O id do número na Luna, quando você consultou por numberId. Nulo quando consultou por externalId."},"phoneNumberId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id do número na Meta, quando você consultou por numberId. Nulo quando consultou por externalId."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente, quando você consultou por externalId. Nulo quando consultou por numberId."},"start":{"type":"string","description":"O começo do período consultado, em ISO 8601."},"end":{"type":"string","description":"O fim do período consultado, em ISO 8601."},"granularity":{"type":"string","enum":["HALF_HOUR","DAILY","MONTHLY"]},"readAt":{"type":"string","description":"Quando a Luna leu isto na Meta; com vários números, a leitura mais antiga. A mesma consulta repetida em até cinco minutos devolve a mesma leitura."},"notice":{"type":"string","description":"O aviso que acompanha o consumo: é aproximação, a Meta cobra direto do negócio, e nada daqui entra na assinatura da Luna. Mostre-o junto dos valores."},"numbers":{"type":"array","items":{"type":"object","properties":{"numberId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O id do número na Luna."},"phoneNumberId":{"type":"string","description":"O id do número na Meta."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda da conta do negócio na Meta. Nulo quando a Luna ainda não a leu."},"read":{"type":"boolean","description":"true quando a Luna leu o consumo deste número. false quando ele ficou de fora, e reason diz por quê."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Por que o número não foi lido: number_disconnected (você o desconectou) ou phone_not_read_yet (a Luna ainda não leu o telefone dele na Meta). Nulo quando read é true."}},"required":["numberId","phoneNumberId","currency","read","reason"],"additionalProperties":false},"description":"Os números cobertos pela consulta, inclusive os que ficaram de fora e os que não tiveram nenhum ponto."},"data":{"type":"array","items":{"type":"object","properties":{"numberId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O número da Luna a que este ponto pertence."},"phoneNumberId":{"type":"string","description":"O id do mesmo número na Meta."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda de cost, a da conta do negócio na Meta (por exemplo BRL). Nulo quando a Luna ainda não a leu. Contas de moedas diferentes nunca são somadas."},"start":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O começo do ponto, em ISO 8601. Nulo quando a Meta não informou."},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O fim do ponto, em ISO 8601. Nulo quando a Meta não informou."},"pricingCategory":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria de cobrança, como a Meta a nomeia (por exemplo MARKETING, UTILITY, SERVICE). Novos valores podem aparecer."},"pricingType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo de cobrança, como a Meta o nomeia (por exemplo REGULAR, FREE_CUSTOMER_SERVICE). Novos valores podem aparecer."},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A faixa de volume da Meta, no formato que ela manda (por exemplo \"0:750000\"). Nulo quando não veio."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O país do destinatário, como a Meta informou. Nulo quando não veio."},"volume":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O volume que a Meta mediu neste ponto. É dela, aproximado, e nunca é somado pela Luna."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"O custo aproximado que a Meta aplicou neste ponto, na moeda da conta do negócio na Meta. A fatura da Meta é a referência."}},"required":["numberId","phoneNumberId","currency","start","end","pricingCategory","pricingType","tier","country","volume","cost"],"additionalProperties":false},"description":"Os pontos que a Meta devolveu, de todos os números, cada um com o número e a moeda dele. Sem total: agrupe por numberId, e nunca some currency diferentes."}},"required":["numberId","phoneNumberId","externalId","start","end","granularity","readAt","notice","numbers","data"],"additionalProperties":false,"example":{"numberId":"5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b","phoneNumberId":"123456789012345","externalId":null,"start":"2026-11-01T00:00:00.000Z","end":"2026-11-03T15:00:00.000Z","granularity":"DAILY","readAt":"2026-11-03T15:00:12.000Z","notice":"Valores aproximados, como a Meta os informa, na moeda da conta do negócio na Meta. A Meta cobra o uso do WhatsApp direto do negócio dono do número, e a fatura dela é a referência: este consumo pode divergir dela. A Luna só repassa a leitura, e nada daqui entra na assinatura da Luna.","numbers":[{"numberId":"5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b","phoneNumberId":"123456789012345","currency":"BRL","read":true,"reason":null}],"data":[{"numberId":"5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b","phoneNumberId":"123456789012345","currency":"BRL","start":"2026-11-02T03:00:00.000Z","end":"2026-11-03T03:00:00.000Z","pricingCategory":"UTILITY","pricingType":"REGULAR","tier":null,"country":"BR","volume":12,"cost":0.5}]}}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"number_disconnected":{"summary":"Number disconnected from Luna","value":{"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)."}}}}}},"422":{"description":"The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"meta_rejected":{"summary":"Meta refused the operation","value":{"error":"meta_rejected","docsUrl":"https://lunahia.com.br/docs/numero-na-meta","message":"A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.","meta":{"codigo":131030,"categoria":"nao_entregavel","mensagem":"A Meta recusou o pedido.","acaoRecomendada":"Confira os campos enviados e tente de novo.","original":{"error":{"message":"Invalid parameter","type":"OAuthException","code":131030,"fbtrace_id":"AbCdEfGhIjK"}}}}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}},"management_busy":{"summary":"Account management busy","value":{"error":"management_busy","docsUrl":"https://lunahia.com.br/docs/erros","message":"As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"}},"/v1/account/overview":{"get":{"summary":"See the account summary","tags":["Account and plan"],"description":"What the account needs to look at now (alerts, most serious first), the four first steps, and the numbers by connection state. Everything is decided by the API, so a home screen has nothing to calculate.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"attention":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["number_action_required","number_credential_expiring","number_payment_missing","account_restricted","account_disabled","subscription_trial_ending","subscription_suspended","email_not_confirmed","webhook_endpoint_failing","webhook_no_endpoint","webhook_rejected_pending","template_paused","template_rejected","link_failed"],"description":"O tipo do aviso, para o seu código comparar."},"severity":{"type":"string","enum":["blocking","warning","info"],"description":"blocking: algo está parado e precisa de ação. warning: algo vai parar ou funciona pela metade. info: vale olhar."},"title":{"type":"string","description":"O aviso em poucas palavras, em português."},"message":{"type":"string","description":"O que está acontecendo, em português, pronto para mostrar."},"solution":{"type":"string","description":"O que fazer a respeito, em português."},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["number","link","webhook_endpoint","template","subscription","business_account","account"]},"id":{"type":"string","description":"O identificador do recurso na Luna. Para account e subscription é o da própria conta."}},"required":["type","id"],"additionalProperties":false,"description":"A que o aviso se refere."},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A ação que resolve o aviso, quando há: send_pin, reconnect, reconnect_link, meta_manager, wait, contact_helsen, confirm_email, add_webhook_endpoint, review_webhook_endpoint, requeue_webhook_events, edit_template ou create_link. Novos valores podem aparecer."},"actionUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager."},"since":{"type":"string","description":"Desde quando o aviso vale, em ISO-8601 UTC."}},"required":["code","severity","title","message","solution","resource","action","actionUrl","since"],"additionalProperties":false},"description":"O que a conta precisa olhar, na ordem em que deve aparecer: o que está parado primeiro, depois o mais antigo."},"checklist":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["connect_number","create_key","add_webhook_endpoint","send_message"]},"done":{"type":"boolean"},"doneAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o passo foi cumprido pela primeira vez. Nulo enquanto não foi."}},"required":["key","done","doneAt"],"additionalProperties":false},"description":"Os quatro primeiros passos, sempre nesta ordem: connect_number (há um número conectado), create_key (há uma chave de integração não revogada), add_webhook_endpoint (há um endereço de webhook) e send_message (já saiu uma mensagem)."},"numbers":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"byStatus":{"type":"object","properties":{"connected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"connecting":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"action_required":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"disconnected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["connected","connecting","action_required","disconnected"],"additionalProperties":false}},"required":["total","byStatus"],"additionalProperties":false,"description":"Os números da conta por estado de conexão (connection.status). A soma dos quatro estados é total."}},"required":["attention","checklist","numbers"],"additionalProperties":false,"example":{"attention":[{"code":"number_credential_expiring","severity":"warning","title":"Autorização do cliente perto de vencer (+55 11 90000-0000)","message":"A autorização que o seu cliente deu à Luna vence em até 14 dias. O número continua enviando até lá.","solution":"Gere um link de reconexão com POST /v1/onboarding/links informando numberId e envie ao seu cliente.","resource":{"type":"number","id":"ed404df1-b420-4ed6-8743-ba1609892e0a"},"action":"reconnect_link","actionUrl":null,"since":"2026-10-25T12:00:00.000Z"}],"checklist":[{"key":"connect_number","done":true,"doneAt":"2026-08-07T11:28:14.597Z"},{"key":"create_key","done":true,"doneAt":"2026-08-07T12:10:44.201Z"},{"key":"add_webhook_endpoint","done":true,"doneAt":"2026-08-08T09:00:00.000Z"},{"key":"send_message","done":false,"doneAt":null}],"numbers":{"total":1,"byStatus":{"connected":1,"connecting":0,"action_required":0,"disconnected":0}}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"numbers:read"}},"/v1/webhooks/endpoints":{"post":{"summary":"Register the webhook endpoint","tags":["Webhooks and events"],"description":"Registers your server's URL and returns the secret that signs the deliveries. headers, optional, carries up to 5 own HTTP headers that Luna sends on every delivery (for a gateway that requires a fixed token); the values are secret and no response returns them.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público."},"eventTypes":{"maxItems":30,"type":"array","items":{"type":"string","enum":["message.received","message.status","contact.identity_changed","contact.preferences_changed","backlog.dropped","history_sync.deadline_approaching","message.echo","template.status","number.connected","number.payment_required","number.payment_resolved","account.restricted","account.violation","account.disabled","account.reinstated","account.update","account.limit_changed","number.disconnected","number.quality_changed","number.display_name_reviewed","number.credential_expiring","account.alert","number.action_required","number.action_resolved","onboarding.link.completed","onboarding.link.opened","onboarding.link.failed","onboarding.link.expired","template.category","template.quality"]},"description":"Os tipos de evento que este endpoint recebe, por exemplo [\"message.received\", \"message.status\"]. Ausente ou vazio quer dizer todos, inclusive os tipos que a Luna criar depois. Com a lista preenchida, o endpoint só recebe esses tipos, e um tipo novo não chega até você incluí-lo. O filtro é só por tipo. O evento webhook.test não é filtrável: ele só sai quando você o pede. Os tipos estão no guia Receber eventos."},"externalIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Os clientes seus (externalId) de que este endpoint recebe eventos, por exemplo [\"cliente-42\"]. Ausente ou vazio quer dizer todos. Com a lista preenchida, o endpoint só recebe eventos de números com um destes externalId, inclusive os conectados depois, e dos links de conexão com ele. Eventos que não falam de um cliente (os de template, por exemplo) só chegam se a conta do template tem um número dele. O filtro é só por identificador."},"phoneNumberIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"description":"Os números de que este endpoint recebe eventos: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId), em qualquer mistura. A resposta devolve os ids da Meta, os mesmos que os eventos trazem em phone_number_id. Ausente ou vazio quer dizer todos. Um número que não é da conta responde 400. Para cobrir números que ainda serão conectados, use externalIds."},"headers":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":1024,"pattern":"^[ -~]+$"},"description":"Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { \"X-Token\": \"valor\" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos."}},"required":["url"],"additionalProperties":false,"description":"O cadastro do endpoint para onde a Luna entrega o que chega no seu número."}}},"description":"O cadastro do endpoint para onde a Luna entrega o que chega no seu número."},"responses":{"201":{"description":"O endpoint recém-criado, com o segredo de assinatura.\n\nEsta é a única resposta que carrega o segredo, junto com a da rotação. Guarde-o agora.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do endpoint, devolvido no cadastro."},"url":{"type":"string","maxLength":2048,"description":"A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público."},"createdAt":{"type":"string","description":"Quando o endpoint foi cadastrado, em UTC."},"updatedAt":{"type":"string","description":"Quando ele foi alterado pela última vez, em UTC."},"previousSecretExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo."},"paused":{"type":"boolean","description":"true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois."},"pausedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint foi pausado, em UTC, ou null se ele está ativo."},"eventTypes":{"type":"array","items":{"type":"string"},"description":"Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos."},"externalIds":{"type":"array","items":{"type":"string"},"description":"Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"phoneNumberIds":{"type":"array","items":{"type":"string"},"description":"Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"headerNames":{"type":"array","items":{"type":"string"},"description":"Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum."},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries."},"lastFailureAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico."},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint."},"deliveryStatus":{"type":"string","enum":["ok","failing","paused","never_delivered"],"description":"A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico."},"secret":{"type":"string","description":"O segredo que assina as entregas para este endpoint. Ele aparece nesta resposta e em mais nenhuma: guarde-o agora. A Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo."}},"required":["id","url","createdAt","updatedAt","previousSecretExpiresAt","paused","pausedAt","eventTypes","externalIds","phoneNumberIds","headerNames","lastDeliveryAt","lastFailureAt","lastHttpStatus","deliveryStatus","secret"],"additionalProperties":false,"description":"O endpoint recém-criado, com o segredo de assinatura.\n\nEsta é a única resposta que carrega o segredo, junto com a da rotação. Guarde-o agora.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"webhook_endpoint_limit":{"summary":"Endpoint limit","value":{"error":"webhook_endpoint_limit","docsUrl":"https://lunahia.com.br/docs/receber-eventos","message":"Este cliente já tem o máximo de endpoints de webhook, e o limite é o mesmo para todos. Remova um endpoint com DELETE /v1/webhooks/endpoints/{id} para liberar a vaga.","limit":25}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-endpoints"}},"get":{"summary":"List webhook endpoints","tags":["Webhooks and events"],"description":"The endpoints registered for this customer, newest first, with the endpoint limit and whether another can still be registered (limit and canCreate). Each endpoint carries deliveryStatus.","responses":{"200":{"description":"Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate).\n\nO segredo de assinatura NÃO vem aqui, e não vem de rota nenhuma: ele sai uma única vez, na resposta do cadastro e na da rotação. A Luna guarda apenas a forma cifrada dele. Se você o perdeu, rotacione para receber um novo: não existe caminho de recuperação.\n\nA resposta não traz total nem contagem, de propósito: nenhum número desta API alimenta cobrança.\n\nLista vazia com 200 é a resposta de quem ainda não cadastrou nenhum endpoint, e não um erro.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do endpoint, devolvido no cadastro."},"url":{"type":"string","maxLength":2048,"description":"A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público."},"createdAt":{"type":"string","description":"Quando o endpoint foi cadastrado, em UTC."},"updatedAt":{"type":"string","description":"Quando ele foi alterado pela última vez, em UTC."},"previousSecretExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo."},"paused":{"type":"boolean","description":"true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois."},"pausedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint foi pausado, em UTC, ou null se ele está ativo."},"eventTypes":{"type":"array","items":{"type":"string"},"description":"Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos."},"externalIds":{"type":"array","items":{"type":"string"},"description":"Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"phoneNumberIds":{"type":"array","items":{"type":"string"},"description":"Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"headerNames":{"type":"array","items":{"type":"string"},"description":"Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum."},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries."},"lastFailureAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico."},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint."},"deliveryStatus":{"type":"string","enum":["ok","failing","paused","never_delivered"],"description":"A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico."}},"required":["id","url","createdAt","updatedAt","previousSecretExpiresAt","paused","pausedAt","eventTypes","externalIds","phoneNumberIds","headerNames","lastDeliveryAt","lastFailureAt","lastHttpStatus","deliveryStatus"],"additionalProperties":false,"description":"A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health."}},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"O máximo de endpoints por cliente. É o mesmo para todos, e não depende do plano."},"canCreate":{"type":"boolean","description":"false quando você já chegou ao limite: POST /v1/webhooks/endpoints responderia 409. Remover um endpoint libera a vaga. A tela mostra o botão de cadastrar por este campo."}},"required":["data","limit","canCreate"],"additionalProperties":false,"description":"Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate).\n\nO segredo de assinatura NÃO vem aqui, e não vem de rota nenhuma: ele sai uma única vez, na resposta do cadastro e na da rotação. A Luna guarda apenas a forma cifrada dele. Se você o perdeu, rotacione para receber um novo: não existe caminho de recuperação.\n\nA resposta não traz total nem contagem, de propósito: nenhum número desta API alimenta cobrança.\n\nLista vazia com 200 é a resposta de quem ainda não cadastrou nenhum endpoint, e não um erro."}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-endpoints"}}},"/v1/webhooks/event-types":{"get":{"summary":"List the event types","tags":["Webhooks and events"],"description":"The event types Luna delivers, which eventTypes accepts when you register or update an endpoint. Each item carries the type, which is the value to send, a sentence that says what the event is, and the group it belongs to (group and groupLabel).","responses":{"200":{"description":"Os tipos de evento que a Luna entrega, na ordem do contrato. O evento webhook.test não está na lista: ele só sai quando você o pede.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"O tipo do evento, o valor que eventTypes aceita e que o campo event_type do evento traz."},"summary":{"type":"string","description":"Uma frase que diz o que o evento é."},"group":{"type":"string","enum":["messages","numbers","accounts","templates","links","system"],"description":"O grupo do tipo, para agrupar a lista: messages, numbers, accounts, templates, links ou system. Um tipo novo cai no grupo do seu prefixo, ou em system."},"groupLabel":{"type":"string","description":"O nome do grupo, em português."}},"required":["type","summary","group","groupLabel"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false,"description":"Os tipos de evento que a Luna entrega, na ordem do contrato. O evento webhook.test não está na lista: ele só sai quando você o pede."}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-event-types"}}},"/v1/webhooks/endpoints/{id}":{"get":{"summary":"Read the webhook endpoint","tags":["Webhooks and events"],"description":"The endpoint's configuration.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador do endpoint, devolvido no cadastro."}],"responses":{"200":{"description":"A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do endpoint, devolvido no cadastro."},"url":{"type":"string","maxLength":2048,"description":"A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público."},"createdAt":{"type":"string","description":"Quando o endpoint foi cadastrado, em UTC."},"updatedAt":{"type":"string","description":"Quando ele foi alterado pela última vez, em UTC."},"previousSecretExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo."},"paused":{"type":"boolean","description":"true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois."},"pausedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint foi pausado, em UTC, ou null se ele está ativo."},"eventTypes":{"type":"array","items":{"type":"string"},"description":"Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos."},"externalIds":{"type":"array","items":{"type":"string"},"description":"Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"phoneNumberIds":{"type":"array","items":{"type":"string"},"description":"Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"headerNames":{"type":"array","items":{"type":"string"},"description":"Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum."},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries."},"lastFailureAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico."},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint."},"deliveryStatus":{"type":"string","enum":["ok","failing","paused","never_delivered"],"description":"A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico."}},"required":["id","url","createdAt","updatedAt","previousSecretExpiresAt","paused","pausedAt","eventTypes","externalIds","phoneNumberIds","headerNames","lastDeliveryAt","lastFailureAt","lastHttpStatus","deliveryStatus"],"additionalProperties":false,"description":"A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-endpoints-id"}},"patch":{"summary":"Update the webhook endpoint","tags":["Webhooks and events"],"description":"Changes the URL, pauses or resumes the endpoint, or changes the event types it receives. Send url, paused, eventTypes, externalIds, phoneNumberIds, headers or any combination: a body with none of them answers 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"A URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo.","type":"string","maxLength":2048},"paused":{"description":"true pausa o endpoint: os eventos que ocorrerem enquanto ele estiver pausado não são entregues, nem depois. false o retoma, e ele passa a receber os eventos a partir desse momento.","type":"boolean"},"eventTypes":{"description":"Troca a lista de tipos que o endpoint recebe: a lista enviada substitui a anterior. Lista vazia volta a receber todos. O que ocorreu antes da troca e foi filtrado não é entregue depois.","maxItems":30,"type":"array","items":{"type":"string","enum":["message.received","message.status","contact.identity_changed","contact.preferences_changed","backlog.dropped","history_sync.deadline_approaching","message.echo","template.status","number.connected","number.payment_required","number.payment_resolved","account.restricted","account.violation","account.disabled","account.reinstated","account.update","account.limit_changed","number.disconnected","number.quality_changed","number.display_name_reviewed","number.credential_expiring","account.alert","number.action_required","number.action_resolved","onboarding.link.completed","onboarding.link.opened","onboarding.link.failed","onboarding.link.expired","template.category","template.quality"]}},"externalIds":{"description":"Troca a lista de clientes de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Vale daí em diante.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"phoneNumberIds":{"description":"Troca a lista de números de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Aceita o UUID da Luna ou o id da Meta.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}},"headers":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":1024,"pattern":"^[ -~]+$"},"description":"Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { \"X-Token\": \"valor\" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos."}},"additionalProperties":false,"description":"O que alterar no endpoint. Envie url, paused, eventTypes, externalIds, phoneNumberIds, headers ou qualquer combinação."}}},"description":"O que alterar no endpoint. Envie url, paused, eventTypes, externalIds, phoneNumberIds, headers ou qualquer combinação."},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador do endpoint, devolvido no cadastro."}],"responses":{"200":{"description":"A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do endpoint, devolvido no cadastro."},"url":{"type":"string","maxLength":2048,"description":"A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público."},"createdAt":{"type":"string","description":"Quando o endpoint foi cadastrado, em UTC."},"updatedAt":{"type":"string","description":"Quando ele foi alterado pela última vez, em UTC."},"previousSecretExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo."},"paused":{"type":"boolean","description":"true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois."},"pausedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint foi pausado, em UTC, ou null se ele está ativo."},"eventTypes":{"type":"array","items":{"type":"string"},"description":"Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos."},"externalIds":{"type":"array","items":{"type":"string"},"description":"Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"phoneNumberIds":{"type":"array","items":{"type":"string"},"description":"Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"headerNames":{"type":"array","items":{"type":"string"},"description":"Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum."},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries."},"lastFailureAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico."},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint."},"deliveryStatus":{"type":"string","enum":["ok","failing","paused","never_delivered"],"description":"A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico."}},"required":["id","url","createdAt","updatedAt","previousSecretExpiresAt","paused","pausedAt","eventTypes","externalIds","phoneNumberIds","headerNames","lastDeliveryAt","lastFailureAt","lastHttpStatus","deliveryStatus"],"additionalProperties":false,"description":"A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.\n\nA entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso.\n\nA ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra.\n\nA idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos.\n\nSe o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve.\n\nNovos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo.\n\nNum número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-patch-v1-webhooks-endpoints-id"}},"delete":{"summary":"Remove the webhook endpoint","tags":["Webhooks and events"],"description":"Removes the endpoint. The response is 204, and the endpoint stops receiving events.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador do endpoint, devolvido no cadastro."}],"responses":{"204":{"description":"No content: the operation was done and the response has no body."},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-delete-v1-webhooks-endpoints-id"}}},"/v1/webhooks/endpoints/{id}/deliveries":{"get":{"summary":"List the endpoint's deliveries","tags":["Webhooks and events"],"description":"The delivery attempts to the endpoint over the last 7 days, newest first: eventId, eventType, status, httpStatus (null when your server did not answer), durationMs, attempt and at. Filters: status (success or failed), eventType and since. It does not carry the body sent or what your server answered.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Quantos itens trazer. Padrão 50, máximo 100, igual para todos."},{"schema":{"type":"string","enum":["success","failed"]},"in":"query","name":"status","required":false,"description":"success: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta."},{"schema":{"type":"string","enum":["message.received","message.status","contact.identity_changed","contact.preferences_changed","backlog.dropped","history_sync.deadline_approaching","message.echo","template.status","number.connected","number.payment_required","number.payment_resolved","account.restricted","account.violation","account.disabled","account.reinstated","account.update","account.limit_changed","number.disconnected","number.quality_changed","number.display_name_reviewed","number.credential_expiring","account.alert","number.action_required","number.action_resolved","onboarding.link.completed","onboarding.link.opened","onboarding.link.failed","onboarding.link.expired","template.category","template.quality"]},"in":"query","name":"eventType","required":false,"description":"Só as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types)."},{"schema":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}]},"in":"query","name":"since","required":false,"description":"Só as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias."},{"schema":{"type":"string","maxLength":256},"in":"query","name":"cursor","required":false,"description":"O nextCursor da página anterior. Omita na primeira."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador do endpoint, devolvido no cadastro."}],"responses":{"200":{"description":"O histórico de entregas do endpoint nos últimos 7 dias, uma linha por tentativa. Não traz o corpo enviado nem o que o seu servidor respondeu: só o status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador desta tentativa."},"eventId":{"type":"string","description":"O event_id do evento, o mesmo que o seu servidor recebeu no corpo. Tentativas do mesmo evento repetem o eventId."},"eventType":{"type":"string","description":"O tipo do evento."},"status":{"type":"string","enum":["success","failed"],"description":"success quando o seu servidor respondeu 2xx; failed no resto."},"httpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP que o seu servidor devolveu. Nulo quando ele não respondeu (tempo esgotado, conexão recusada, endereço recusado)."},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Quanto a chamada levou, em milissegundos."},"attempt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"A tentativa de entrega deste evento, a primeira é 1."},"at":{"type":"string","description":"Quando a tentativa aconteceu, em UTC."}},"required":["id","eventId","eventType","status","httpStatus","durationMs","attempt","at"],"additionalProperties":false},"description":"As tentativas desta página, da mais recente à mais antiga."},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mande este valor em cursor para pegar a página seguinte. Nulo é o fim. Não existe total: para saber quantas há, pagine até o fim."}},"required":["data","nextCursor"],"additionalProperties":false,"description":"O histórico de entregas do endpoint nos últimos 7 dias, uma linha por tentativa. Não traz o corpo enviado nem o que o seu servidor respondeu: só o status."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-endpoints-id-deliveries"}}},"/v1/webhooks/endpoints/{id}/test":{"post":{"summary":"Send a test event","tags":["Webhooks and events"],"description":"Sends ONE webhook.test event to the endpoint, now, and returns the result in the response itself. The event goes out signed, with the same headers, the same signature and the same destination defenses as a real delivery, so a test that passes proves that the URL and signature verification work. With eventType in the body, the event is an example of that type, with a made-up body and test: true in the envelope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"eventType":{"description":"Um tipo de GET /v1/webhooks/event-types. A Luna entrega ao endpoint um exemplo desse tipo, com corpo de mentira (identificadores que não existem) e test: true no envelope, para você exercitar o seu código sem esperar o evento de verdade. Ausente, o teste é o webhook.test de sempre. O exemplo não passa por nenhum número seu.","type":"string","enum":["message.received","message.status","contact.identity_changed","contact.preferences_changed","backlog.dropped","history_sync.deadline_approaching","message.echo","template.status","number.connected","number.payment_required","number.payment_resolved","account.restricted","account.violation","account.disabled","account.reinstated","account.update","account.limit_changed","number.disconnected","number.quality_changed","number.display_name_reviewed","number.credential_expiring","account.alert","number.action_required","number.action_resolved","onboarding.link.completed","onboarding.link.opened","onboarding.link.failed","onboarding.link.expired","template.category","template.quality"]}},"additionalProperties":false},{"type":"null"}]}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador do endpoint, devolvido no cadastro."}],"responses":{"200":{"description":"O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"delivered":{"type":"boolean","description":"true quando o seu servidor respondeu 2xx. É o mesmo critério de uma entrega real."},"statusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP que o seu servidor devolveu, ou null quando não houve resposta."},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Quanto tempo a chamada levou, em milissegundos."},"failure":{"anyOf":[{"type":"string","enum":["timeout","connection","destination_not_allowed","response_too_large","http_status"]},{"type":"null"}],"description":"Por que não foi entregue, ou null quando foi. timeout: o servidor não respondeu a tempo. connection: não foi possível conectar (DNS, TLS ou porta fechada). destination_not_allowed: a URL deixou de apontar para um endereço público. response_too_large: a resposta passou do tamanho que a Luna lê. http_status: o servidor respondeu, mas com status fora de 2xx, inclusive redirecionamento, que a Luna não segue; o status vem em statusCode."}},"required":["delivered","statusCode","durationMs","failure"],"additionalProperties":false,"description":"O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-endpoints-id-test"}}},"/v1/webhooks/endpoints/{id}/rotacionar":{"post":{"summary":"Rotate the signing secret","tags":["Webhooks and events"],"description":"Mints a new secret and returns it once. Store it now, as on registration.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"revokePrevious":{"description":"Com true, o segredo anterior deixa de valer no mesmo instante, em vez de seguir válido por sete dias. Use quando o segredo anterior vazou. As entregas que já saíram assinadas só com ele falham na verificação do seu lado.","type":"boolean"}},"additionalProperties":false},{"type":"null"}]}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador do endpoint, devolvido no cadastro."}],"responses":{"200":{"description":"O endpoint com o segredo novo. O anterior continua válido até previousSecretExpiresAt, então você pode trocar a configuração do seu lado sem pressa e sem perder entrega.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do endpoint, devolvido no cadastro."},"url":{"type":"string","maxLength":2048,"description":"A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público."},"createdAt":{"type":"string","description":"Quando o endpoint foi cadastrado, em UTC."},"updatedAt":{"type":"string","description":"Quando ele foi alterado pela última vez, em UTC."},"previousSecretExpiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo."},"paused":{"type":"boolean","description":"true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois."},"pausedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint foi pausado, em UTC, ou null se ele está ativo."},"eventTypes":{"type":"array","items":{"type":"string"},"description":"Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos."},"externalIds":{"type":"array","items":{"type":"string"},"description":"Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"phoneNumberIds":{"type":"array","items":{"type":"string"},"description":"Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos."},"headerNames":{"type":"array","items":{"type":"string"},"description":"Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum."},"lastDeliveryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries."},"lastFailureAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico."},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint."},"deliveryStatus":{"type":"string","enum":["ok","failing","paused","never_delivered"],"description":"A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico."},"secret":{"type":"string","description":"O segredo que assina as entregas para este endpoint. Ele aparece nesta resposta e em mais nenhuma: guarde-o agora. A Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo."}},"required":["id","url","createdAt","updatedAt","previousSecretExpiresAt","paused","pausedAt","eventTypes","externalIds","phoneNumberIds","headerNames","lastDeliveryAt","lastFailureAt","lastHttpStatus","deliveryStatus","secret"],"additionalProperties":false,"description":"O endpoint com o segredo novo. O anterior continua válido até previousSecretExpiresAt, então você pode trocar a configuração do seu lado sem pressa e sem perder entrega."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"415":{"description":"The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unsupported_media_type":{"summary":"Content type not read","value":{"error":"unsupported_media_type","docsUrl":"https://lunahia.com.br/docs/erros","message":"Envie o corpo como application/json."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-endpoints-id-rotacionar"}}},"/v1/webhooks/dlq":{"get":{"summary":"List deliveries that failed for good","tags":["Webhooks and events"],"description":"The events Luna tried to deliver to your endpoint and gave up on, newest first, each with the number, the customer label, the attempts, the last HTTP status and what can be done with it (allowedActions). Filters: endpointId, externalId and requeued.","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"O cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página."},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Quantos itens trazer nesta página. Máximo 100, igual para todos."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"endpointId","required":false,"description":"Só os itens deste endpoint."},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","required":false,"description":"Só os itens dos números deste cliente seu (externalId do número). Igualdade exata; um rótulo sem item devolve lista vazia."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"requeued","required":false,"description":"true: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions)."}],"responses":{"200":{"description":"Uma página da fila de rejeitados. Sem total e sem contagem: a Luna não soma entregas, e nenhum número desta resposta alimenta cobrança. attempts e lastHttpStatus descrevem UMA entrega que falhou, e não um agregado.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador deste item na fila de rejeitados."},"endpointId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O endpoint para o qual a entrega falhou."},"eventType":{"type":"string","enum":["message.received","message.status","message.echo","template.status","number.payment_required","number.payment_resolved","account.restricted","account.violation","account.disabled","account.reinstated","account.update","account.limit_changed","number.disconnected","number.quality_changed","template.category","template.quality","number.credential_expiring","account.alert","contact.identity_changed","contact.preferences_changed"],"description":"O tipo do evento que não foi entregue."},"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador da mensagem na Meta, o mesmo que o evento carrega. Nulo em todos os tipos que não são de mensagem (template.*, number.* e account.*), que não têm mensagem."},"rejectedAt":{"type":"string","description":"Quando a plataforma desistiu de tentar entregar este evento, em UTC."},"failureReason":{"type":"string","enum":["http_4xx","http_5xx","timeout","conexao","destino_recusado","reenvio_pedido"],"description":"A classe da última falha. http_4xx é o seu servidor tendo entendido e recusado; http_5xx é ele tendo aceitado e quebrado; timeout é ele não ter respondido a tempo; conexao é não ter sido possível estabelecer a conexão; destino_recusado é a URL ter deixado de apontar para um endereço público; reenvio_pedido não é falha: é um reenvio que você mesmo pediu em POST /v1/messages/{id}/replay, e já nasce com requeuedAt preenchido."},"requeuedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando este item foi re-enfileirado, ou null se ainda não foi. Pedir o re-enfileiramento de um item que já tem este campo preenchido responde 409, e não republica de novo."},"numberId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O número da Luna por onde o evento passou, o mesmo id de GET /v1/numbers. Nulo nos eventos que não passam por número (template.*) e quando a mensagem já não está na Luna."},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O seu rótulo para o cliente dono desse número. Nulo quando não há número ou ele não tem rótulo."},"attempts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Quantas vezes a Luna tentou entregar este evento antes de desistir. Nulo nos itens anteriores a este campo e nos reenvios pedidos por você (reenvio_pedido), que não são falha."},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O status HTTP que o seu endpoint devolveu na última tentativa. Nulo quando ele não respondeu (tempo esgotado, conexão recusada) e nos itens anteriores a este campo."},"allowedActions":{"type":"array","items":{"type":"string","enum":["requeue"]},"description":"O que a sua conta pode fazer com o item agora: requeue (POST /v1/webhooks/dlq/{id}/reenfileirar), enquanto ele não foi re-enfileirado. Mostre o botão quando o verbo está na lista."}},"required":["id","endpointId","eventType","wamid","rejectedAt","failureReason","requeuedAt","numberId","externalId","attempts","lastHttpStatus","allowedActions"],"additionalProperties":false,"description":"Um evento que a plataforma tentou entregar e desistiu."},"description":"Os itens desta página, do mais recente ao mais antigo."},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Passe este valor em cursor para obter a página seguinte. null significa que esta é a última página. Não existe total: para saber quantos itens há, pagine até o fim."}},"required":["items","nextCursor"],"additionalProperties":false,"description":"Uma página da fila de rejeitados. Sem total e sem contagem: a Luna não soma entregas, e nenhum número desta resposta alimenta cobrança. attempts e lastHttpStatus descrevem UMA entrega que falhou, e não um agregado."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:read","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-dlq"}}},"/v1/webhooks/dlq/{id}/reenfileirar":{"post":{"summary":"Requeue a failed delivery","tags":["Webhooks and events"],"description":"Puts the event back on the delivery queue. The response is 202: the request was recorded, and delivery happens asynchronously.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"O identificador deste item na fila de rejeitados."}],"responses":{"202":{"description":"O item foi recolocado na fila de entrega. A entrega em si é assíncrona, como qualquer outra: se o seu endpoint ainda estiver fora do ar, ela será adiada e retentada pela mesma política de sempre.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador deste item na fila de rejeitados."},"requeuedAt":{"type":"string","description":"O instante em que o re-enfileiramento foi registrado, em UTC."}},"required":["id","requeuedAt"],"additionalProperties":false,"description":"O item foi recolocado na fila de entrega. A entrega em si é assíncrona, como qualquer outra: se o seu endpoint ainda estiver fora do ar, ela será adiada e retentada pela mesma política de sempre."}}}},"400":{"description":"The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroDeValidacao"},"examples":{"invalid_request":{"summary":"Field refused, with the reason","value":{"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."}]}}}}}},"401":{"description":"The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.","headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unauthorized":{"summary":"Key refused","value":{"error":"unauthorized","docsUrl":"https://lunahia.com.br/docs/erros","message":"Credencial ausente ou inválida."}}}}}},"403":{"description":"The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"forbidden":{"summary":"Insufficient scope","value":{"error":"forbidden","docsUrl":"https://lunahia.com.br/docs/erros","message":"Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.","requiredScope":"numbers:read"}},"test_key_not_allowed":{"summary":"Test key on a route outside test mode","value":{"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."}}}}}},"404":{"description":"The resource does not exist, or is not yours. The two answers are identical, byte for byte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"not_found":{"summary":"Does not exist, or is not yours","value":{"error":"not_found","docsUrl":"https://lunahia.com.br/docs/erros","message":"Recurso não encontrado."}}}}}},"409":{"description":"The request is well formed, but the resource state does not allow it. The error field says which case it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"already_requeued":{"summary":"Item already requeued","value":{"error":"already_requeued","docsUrl":"https://lunahia.com.br/docs/receber-eventos","message":"Este item já foi re-enfileirado.","reenfileiradoEm":"2026-10-06T12:00:00.000Z"}}}}}},"429":{"description":"Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.","headers":{"Retry-After":{"description":"Seconds to wait before repeating.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"rate_limited":{"summary":"Request limit","value":{"error":"rate_limited","docsUrl":"https://lunahia.com.br/docs/erros","message":"Requisições demais. Tente novamente em instantes."}}}}}},"503":{"description":"The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"examples":{"unavailable":{"summary":"Unavailable","value":{"error":"unavailable","docsUrl":"https://lunahia.com.br/docs/erros","message":"Não foi possível concluir a operação agora. Tente novamente em instantes."}}}}}}},"x-escopo":"webhooks:write","externalDocs":{"description":"Details and reasons for this route, in the guide","url":"https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-dlq-id-reenfileirar"}}}},"servers":[{"url":"https://api.lunahia.com.br","description":"A API pública da Luna"}],"security":[{"apiKey":[]}],"tags":[{"name":"Messages","description":"Send messages and read what came in and went out. Sending is asynchronous: the answer is 202 and delivery happens at the pace Meta allows."},{"name":"Conversations","description":"One row per contact per number, with the state of the 24 hour customer service window."},{"name":"Media","description":"Upload a file to Meta and download the media that arrived in a message."},{"name":"Templates","description":"Messages pre-approved by Meta, required to start a conversation outside the 24 hour window.\n\nApproved is not cleared for volume: Meta applies a pace of its own over the first sends of a new template, and publishes no deadline and no mechanics. Ramp up your first send instead of scheduling it for a date, and watch the state of the template.\n\nAbove three buttons, only two appear in the delivered message. Meta accepts the template with more and delivers two, so the arrangement has to be decided before the flow is designed."},{"name":"Phone numbers","description":"The connected numbers: connect, read state, quality and throughput, edit and disconnect.\n\nMigrating a number that is already on another provider's API is a supported path, and it needs no new number and loses no existing one. A number already registered on another provider's Cloud API almost always has two step verification configured there, and Meta requires the existing PIN to register it again: there is no endpoint to read or to turn that PIN off, so it has to come from the end business. Give the PIN at POST /v1/numbers/{id}/pin, or ask the end business to turn two step verification off in its WhatsApp Manager. The other prerequisites are on its side too: it has to own the WhatsApp Business account and have the number released by the previous provider.\n\nA number that today exists only in the WhatsApp Business App, the phone application, is the other case, and Meta calls it coexistence. It has never been through any API. The connection starts from the same Meta window, and the option only shows up once the end business account is enabled for it on Meta's side and the app on the device is version 2.24.17 or later.\n\nConnected this way, the number keeps working in the phone application, and the earlier conversations on the device are imported into the platform: they show up in GET /v1/messages next to the new ones. The import has a deadline to finish, and what tells you where it stands is GET /v1/numbers/{id}, in the fields sincronizacaoDoHistorico and sincronizacaoPrazo. The same resource carries tetoDeVazaoPorSegundo, which is the fixed sending speed ceiling of a number in coexistence and does not go up over time. And what the business owner answers from the phone application arrives too, in the recipient's conversation."},{"name":"Connection links","description":"A link your customer opens to connect their WhatsApp number, without receiving your console login. One link per customer of yours, tied to the externalId you chose."},{"name":"Webhooks and events","description":"Where Luna delivers what arrives at your number, the secret that signs those deliveries, and the event types, each with its schema and an example."},{"name":"Keys","description":"Create, list and revoke the credentials that authenticate your calls."},{"name":"Account and plan","description":"The credential's account, the plan, the number capacity and how many are in use in the period."},{"name":"Status","description":"Availability probes and the state of the platform. No authentication."},{"name":"Console and public pages","description":"Routes the Luna console and the public connection link page use: sign-up, login, session and completion of the flow. You normally do not need them. They exist here because the console is a client of this same API, with no privileged route."}],"webhooks":{"message.received":{"post":{"tags":["Webhooks and events"],"summary":"Message received","description":"A contact wrote to one of your numbers. It carries the text, and the content when the message is of another type (media, tapped button, location, contacts, reaction).\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"message.received"},"message":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem."},"wamid":{"type":"string","minLength":1,"description":"O identificador da mensagem na Meta."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador do interlocutor na Meta, em E.164 sem o sinal de mais: o telefone. Nulo quando o usuário escreveu sem que o telefone apareça (nome de usuário adotado): use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais."},"type":{"type":"string","minLength":1,"description":"O tipo da mensagem, no vocabulário da Meta."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title."},"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou."},"media":{"anyOf":[{"type":"object","properties":{"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do arquivo. Só documento tem."},"voice":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem."},"animated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a figurinha é animada. Só figurinha tem."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo."}},"required":["mime_type","sha256","caption","filename","voice","animated","url"],"additionalProperties":false},{"type":"null"}]},"interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow)."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do item da lista. Nula nos demais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do Flow. Só em nfm_reply."},"response_json":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply."}},"required":["type","id","title","description","name","response_json"],"additionalProperties":false,"description":"A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu."},{"type":"null"}]},"button":{"anyOf":[{"type":"object","properties":{"payload":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O payload que você definiu no botão de resposta rápida do template."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do botão."}},"required":["payload","text"],"additionalProperties":false,"description":"O clique num botão de resposta rápida de um template."},{"type":"null"}]},"location":{"anyOf":[{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A latitude, em graus decimais."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A longitude, em graus decimais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do lugar, quando o interlocutor escolheu um."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço, quando há."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço web do lugar, quando há."}},"required":["latitude","longitude","name","address","url"],"additionalProperties":false,"description":"A localização que o interlocutor compartilhou."},{"type":"null"}]},"contacts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"object","properties":{"formatted_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["formatted_name","first_name","last_name","middle_name","prefix","suffix"],"additionalProperties":false},{"type":"null"}],"description":"O nome do contato, nos campos da Meta."},"phones":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"wa_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","wa_id","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp."},"emails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os e-mails do contato."},"org":{"anyOf":[{"type":"object","properties":{"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"department":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["company","department","title"],"additionalProperties":false},{"type":"null"}],"description":"A organização do contato."}},"required":["name","phones","emails","org"],"additionalProperties":false}},{"type":"null"}],"description":"Os cartões de contato que o interlocutor compartilhou."},"reaction":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que recebeu a reação."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O emoji. Nulo quando o interlocutor retirou a reação."}},"required":["wamid","emoji"],"additionalProperties":false,"description":"A reação a uma mensagem, ou a retirada dela."},{"type":"null"}]},"context":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor citou ao responder."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem enviou a mensagem citada."},"forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada."},"frequently_forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada muitas vezes."}},"required":["wamid","from","forwarded","frequently_forwarded"],"additionalProperties":false,"description":"A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada."},{"type":"null"}]},"referral":{"anyOf":[{"type":"object","properties":{"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A origem do clique, como ad ou post."},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do anúncio ou da publicação na Meta."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do anúncio ou da publicação."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do anúncio."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do anúncio."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mídia do anúncio, como image ou video."},"ctwa_clid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do clique, para atribuição de conversão."}},"required":["source_type","source_id","source_url","headline","body","media_type","ctwa_clid"],"additionalProperties":false,"description":"O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever."},{"type":"null"}]},"unsupported":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta, como ela mandou (131051 é \"tipo de mensagem sem suporte\")."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o mandou."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O detalhe do erro, como a Meta o mandou."}},"required":["code","title","details"],"additionalProperties":false,"description":"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\"."},{"type":"null"}]},"edit":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que foi editada."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do conteúdo novo, como text."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto novo, quando o conteúdo novo é texto."}},"required":["wamid","type","text"],"additionalProperties":false,"description":"Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit)."},{"type":"null"}]},"revoke":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor apagou para todos."}},"required":["wamid"],"additionalProperties":false,"description":"Presente quando o interlocutor apagou uma mensagem para todos (type é revoke)."},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde veio o pedido."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto que o interlocutor escreveu junto com o pedido."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do produto no seu catálogo."},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A quantidade pedida, como a Meta mandou."},"item_price":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O preço unitário, como a Meta mandou."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda do preço."}},"required":["product_retailer_id","quantity","item_price","currency"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens do pedido."}},"required":["catalog_id","text","items"],"additionalProperties":false,"description":"O pedido que o interlocutor montou num catálogo e enviou (type é order)."},{"type":"null"}]}},"required":["id","wamid","wa_id","user_id","parent_user_id","username","type","text","profile_name","media","interactive","button","location","contacts","reaction","context","referral","unsupported","edit","revoke","order"],"additionalProperties":false,"description":"Uma mensagem que chegou de um interlocutor. Além de wamid, wa_id (que pode ser nulo), user_id, parent_user_id, username, type e text, ela traz o conteúdo que o tipo carrega (mídia, botão ou item clicado, resposta de Flow, localização, contatos, reação, pedido, edição, apagamento, aviso de tipo sem suporte), a citação, o anúncio de origem e o nome de perfil. Os nomes dentro desses campos são os da Meta. Todo campo está sempre presente, e é nulo quando não se aplica."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"message.status":{"post":{"tags":["Webhooks and events"],"summary":"State of a message you sent","description":"A message you sent changed state: sent, delivered, read or failed. On failed, the event carries the error. On sent and on one of delivered and read, it carries the pricing: the cost Meta applied to the message, with its names.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"message.status"},"message":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O identificador da mensagem na Luna, o mesmo que POST /v1/messages devolveu quando você a enviou. Nulo quando o status é de uma mensagem que a Luna não conhece."},"wamid":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador da mensagem na Meta. Nulo quando a Meta recusou o envio antes de aceitar a mensagem, caso em que ela nunca teve identificador: use id para correlacionar."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais."},"status":{"type":"string","minLength":1,"description":"O estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer."},"error_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta quando o estado é de falha. Nulo nos demais."},"error":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código do erro, como a Meta o informou."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o informou."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do erro, como a Meta a informou."}},"required":["code","title","message"],"additionalProperties":false},{"type":"null"}],"description":"O primeiro erro que a Meta informou quando o estado é de falha, com code, title e message. Nulo nos demais estados. O detalhe completo, com a causa e a ação recomendada, está em GET /v1/messages/{id}."},"pricing":{"anyOf":[{"type":"object","properties":{"billable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos."},"pricing_model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O modelo de preço da Meta, como ela informou (hoje PMP ou CBP)."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer."}},"required":["billable","pricing_model","type","category"],"additionalProperties":false},{"type":"null"}],"description":"O custo que a Meta aplicou à mensagem. A Meta o informa só no estado sent e em um entre delivered e read, então nos demais estados vem nulo. Não é a fatura da Meta: a fonte da verdade é o painel de cobrança dela."},"callback_data":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A etiqueta que você mandou em callbackData ao enviar a mensagem, devolvida como veio. Nulo quando o envio não trouxe etiqueta. Está em todos os estados da mensagem, inclusive failed."}},"required":["id","wamid","wa_id","user_id","parent_user_id","username","status","error_code","error","pricing","callback_data"],"additionalProperties":false,"description":"Uma mudança de estado de uma mensagem que você enviou."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"contact.identity_changed":{"post":{"tags":["Webhooks and events"],"summary":"Contact changed phone number or BSUID","description":"A contact changed phone number (user_changed_number) or BSUID (user_changed_user_id). Luna linked the new identity to the same conversation. Use previous_user_id and user_id to update the contact in your records.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"contact.identity_changed"},"contact":{"type":"object","properties":{"wamid":{"type":"string","minLength":1,"description":"O identificador, na Meta, da mensagem de sistema que avisou a troca."},"change_type":{"type":"string","minLength":1,"description":"O que mudou, como a Meta informou: user_changed_number (o telefone) ou user_changed_user_id (o BSUID). Novos valores podem aparecer."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário)."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do contato depois da troca, como a Meta mandou."},"previous_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do contato depois da troca, quando a Meta o informa."},"previous_parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai de antes da troca, quando a Meta o informa."}},"required":["wamid","change_type","wa_id","user_id","previous_user_id","parent_user_id","previous_parent_user_id"],"additionalProperties":false,"description":"O contato trocou de telefone ou de BSUID. A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro. Todo campo está sempre presente, e é nulo quando não se aplica."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","contact"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"contact.preferences_changed":{"post":{"tags":["Webhooks and events"],"summary":"Contact changed a preference","description":"A contact changed a preference at Meta, today the one about receiving marketing messages: they asked to stop (for example value stop) or accepted again. The values arrive as Meta sent them. Luna does not block any send because of the notice: your system decides, and should stop sending marketing to whoever asked. It only arrives if the user_preferences field is subscribed on the Meta app.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"contact.preferences_changed"},"contact":{"type":"object","properties":{"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário): use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do contato, como a Meta mandou."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do contato, quando a Meta o informa."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do contato, quando ele adotou um."},"profile_name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome que o contato exibe no WhatsApp, quando a Meta o manda."}},"required":["wa_id","user_id","parent_user_id","username","profile_name"],"additionalProperties":false,"description":"Quem mudou a preferência."},"preference":{"type":"object","properties":{"category":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer."},"value":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer."},"detail":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O texto que a Meta mandou para explicar a mudança."}},"required":["category","value","detail"],"additionalProperties":false,"description":"O que mudou."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","contact","preference"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"backlog.dropped":{"post":{"tags":["Webhooks and events"],"summary":"Events dropped by unavailability","description":"Your endpoint was down for too long, and the platform dropped what piled up. It says how many events and for what period. The notice is not dropped along with them.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"backlog.dropped"},"backlog":{"type":"object","properties":{"motivo":{"type":"string","enum":["idade","volume"],"description":"Qual limite foi atingido: idade, quando as mensagens ficaram velhas demais para serem acionáveis; volume, quando o acumulado deste endpoint passou do teto da plataforma."},"quantidade":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Quantos eventos foram descartados nesta ocorrência."},"janela_inicio":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"O evento mais antigo descartado nesta ocorrência."},"janela_fim":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"O evento mais recente descartado nesta ocorrência."}},"required":["motivo","quantidade","janela_inicio","janela_fim"],"additionalProperties":false,"description":"Eventos que a plataforma descartou sem entregar, e que não serão reenviados."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","backlog"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"history_sync.deadline_approaching":{"post":{"tags":["Webhooks and events"],"summary":"History import deadline approaching","description":"On a number connected in coexistence, the import of earlier conversations is still in progress and its deadline approaches. Once the deadline passes without completion, Meta disconnects the end business.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"history_sync.deadline_approaching"},"history_sync":{"type":"object","properties":{"prazo":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Até quando a importação precisa terminar, em UTC. É o mesmo instante que sincronizacaoPrazo devolve na rota de saúde do número."}},"required":["prazo"],"additionalProperties":false,"description":"A importação das conversas anteriores de um número em coexistência está em curso e o prazo dela se aproxima. O estado corrente, inclusive o progresso, está em GET /v1/numbers/{id}/health."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","history_sync"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"webhook.test":{"post":{"tags":["Webhooks and events"],"summary":"Test event","description":"The event POST /v1/webhooks/endpoints/{id}/test sends to your endpoint, so you can check the URL and the signature verification. It does not go through any number.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o evento de teste não passa por nenhum número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"webhook.test"},"webhook_test":{"type":"object","properties":{"endpoint_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu."}},"required":["endpoint_id"],"additionalProperties":false,"description":"Um evento de teste, enviado porque você pediu em POST /v1/webhooks/endpoints/{id}/test. Ele nunca aparece se você não pediu, não tem número nem conversa, e serve para conferir a URL e a verificação da assinatura."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","webhook_test"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"message.echo":{"post":{"tags":["Webhooks and events"],"summary":"Reply sent from the phone app","description":"The business owner answered a customer from the WhatsApp Business app on the phone. It only occurs on a number connected in coexistence. message.wa_id is the recipient.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"message.echo"},"message":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem."},"wamid":{"type":"string","minLength":1,"description":"O identificador da mensagem na Meta."},"wa_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O identificador do DESTINATÁRIO na Meta, em E.164 sem o sinal de mais: o cliente final para quem o dono do negócio escreveu. É a conversa onde o seu agente deve ficar quieto. Nulo quando a conversa é só de BSUID: use user_id."},"user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor."},"parent_user_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais."},"username":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais."},"type":{"type":"string","minLength":1,"description":"O tipo da mensagem, no vocabulário da Meta."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title."},"profile_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou."},"media":{"anyOf":[{"type":"object","properties":{"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do arquivo. Só documento tem."},"voice":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem."},"animated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a figurinha é animada. Só figurinha tem."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo."}},"required":["mime_type","sha256","caption","filename","voice","animated","url"],"additionalProperties":false},{"type":"null"}]},"interactive":{"anyOf":[{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow)."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do item da lista. Nula nos demais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do Flow. Só em nfm_reply."},"response_json":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply."}},"required":["type","id","title","description","name","response_json"],"additionalProperties":false,"description":"A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu."},{"type":"null"}]},"button":{"anyOf":[{"type":"object","properties":{"payload":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O payload que você definiu no botão de resposta rápida do template."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do botão."}},"required":["payload","text"],"additionalProperties":false,"description":"O clique num botão de resposta rápida de um template."},{"type":"null"}]},"location":{"anyOf":[{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A latitude, em graus decimais."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"A longitude, em graus decimais."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome do lugar, quando o interlocutor escolheu um."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço, quando há."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço web do lugar, quando há."}},"required":["latitude","longitude","name","address","url"],"additionalProperties":false,"description":"A localização que o interlocutor compartilhou."},{"type":"null"}]},"contacts":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"object","properties":{"formatted_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["formatted_name","first_name","last_name","middle_name","prefix","suffix"],"additionalProperties":false},{"type":"null"}],"description":"O nome do contato, nos campos da Meta."},"phones":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"wa_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","wa_id","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp."},"emails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","type"],"additionalProperties":false}},{"type":"null"}],"description":"Os e-mails do contato."},"org":{"anyOf":[{"type":"object","properties":{"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"department":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["company","department","title"],"additionalProperties":false},{"type":"null"}],"description":"A organização do contato."}},"required":["name","phones","emails","org"],"additionalProperties":false}},{"type":"null"}],"description":"Os cartões de contato que o interlocutor compartilhou."},"reaction":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que recebeu a reação."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O emoji. Nulo quando o interlocutor retirou a reação."}},"required":["wamid","emoji"],"additionalProperties":false,"description":"A reação a uma mensagem, ou a retirada dela."},{"type":"null"}]},"context":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor citou ao responder."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem enviou a mensagem citada."},"forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada."},"frequently_forwarded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Verdadeiro quando a mensagem foi encaminhada muitas vezes."}},"required":["wamid","from","forwarded","frequently_forwarded"],"additionalProperties":false,"description":"A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada."},{"type":"null"}]},"referral":{"anyOf":[{"type":"object","properties":{"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A origem do clique, como ad ou post."},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do anúncio ou da publicação na Meta."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O endereço do anúncio ou da publicação."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do anúncio."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto do anúncio."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da mídia do anúncio, como image ou video."},"ctwa_clid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do clique, para atribuição de conversão."}},"required":["source_type","source_id","source_url","headline","body","media_type","ctwa_clid"],"additionalProperties":false,"description":"O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever."},{"type":"null"}]},"unsupported":{"anyOf":[{"type":"object","properties":{"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro da Meta, como ela mandou (131051 é \"tipo de mensagem sem suporte\")."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O título do erro, como a Meta o mandou."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O detalhe do erro, como a Meta o mandou."}},"required":["code","title","details"],"additionalProperties":false,"description":"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\"."},{"type":"null"}]},"edit":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que foi editada."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do conteúdo novo, como text."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto novo, quando o conteúdo novo é texto."}},"required":["wamid","type","text"],"additionalProperties":false,"description":"Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit)."},{"type":"null"}]},"revoke":{"anyOf":[{"type":"object","properties":{"wamid":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O wamid da mensagem que o interlocutor apagou para todos."}},"required":["wamid"],"additionalProperties":false,"description":"Presente quando o interlocutor apagou uma mensagem para todos (type é revoke)."},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"catalog_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O catálogo de onde veio o pedido."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O texto que o interlocutor escreveu junto com o pedido."},"items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"product_retailer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador do produto no seu catálogo."},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A quantidade pedida, como a Meta mandou."},"item_price":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O preço unitário, como a Meta mandou."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A moeda do preço."}},"required":["product_retailer_id","quantity","item_price","currency"],"additionalProperties":false}},{"type":"null"}],"description":"Os itens do pedido."}},"required":["catalog_id","text","items"],"additionalProperties":false,"description":"O pedido que o interlocutor montou num catálogo e enviou (type é order)."},{"type":"null"}]}},"required":["id","wamid","wa_id","user_id","parent_user_id","username","type","text","profile_name","media","interactive","button","location","contacts","reaction","context","referral","unsupported","edit","revoke","order"],"additionalProperties":false,"description":"Uma mensagem que o dono do negócio escreveu pelo aplicativo WhatsApp Business do celular, num número conectado em coexistência. Só ocorre em número conectado em coexistência. É o sinal para um agente automatizado ficar quieto na conversa: um humano respondeu. A forma é a de message.received, e wa_id é o destinatário. Todo campo está sempre presente, e é nulo quando não se aplica."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"template.status":{"post":{"tags":["Webhooks and events"],"summary":"A template changed state","description":"Meta approved, rejected, paused or disabled a template, and the reason comes along when there is one. It has no number and no message.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o template pertence à conta de negócio, e não a um número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"template.status"},"template":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem."},"name":{"type":"string","minLength":1,"description":"O nome do template."},"language":{"type":"string","minLength":1,"description":"O idioma do template, no código da Meta."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts)."},"status":{"type":"string","minLength":1,"description":"O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer."},"category":{"type":"string","minLength":1,"description":"A categoria do template, no vocabulário da Meta."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O motivo que a Meta informou para a rejeição ou a pausa. Nulo quando ela não informa um, como nas aprovações."}},"required":["id","name","language","waba_id","external_id","status","category","reason"],"additionalProperties":false,"description":"O estado de um template mudou na Meta: aprovado, rejeitado, pausado, desativado ou outro. Não tem número nem conversa, porque o template pertence à conta de negócio."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","template"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.connected":{"post":{"tags":["Webhooks and events"],"summary":"Number connected","description":"A number finished connecting and is registered on the Cloud API. It is the signal that your customer completed the connection you opened with the connect link, and it carries their externalId.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"coexistence":{"type":"boolean","description":"true quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo do celular. Pode ser false no instante da conexão e passar a true depois. O estado corrente está no campo coexistence de GET /v1/numbers/{id}."}},"required":["id","phone_number_id","display_number","external_id","waba_id","coexistence"],"additionalProperties":false,"description":"Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão: você não precisa consultar a lista de números para descobrir. Para saber se o envio já está liberado, leia o campo ready de GET /v1/numbers/{id}."},"event_type":{"type":"string","const":"number.connected"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.payment_required":{"post":{"tags":["Webhooks and events"],"summary":"Number waiting for a payment method at Meta","description":"Meta refused a send from this number for lack of a payment method on the business that owns the account (error 131042). It is sent once, when the state begins, and not for every refused message. The account owner fixes it in Meta’s WhatsApp Manager: Luna does not intermediate that payment. The Payment at Meta guide explains what to tell your customer.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"awaiting_payment_since":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando a Meta recusou o primeiro envio por falta de método de pagamento. É o mesmo valor que GET /v1/numbers/{id} devolve em awaitingPaymentSince enquanto a espera durar."}},"required":["id","phone_number_id","display_number","external_id","awaiting_payment_since"],"additionalProperties":false,"description":"A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). O número continua conectado e os eventos de entrada seguem chegando, mas os envios são recusados até o dono da conta cadastrar ou regularizar o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. O evento sai uma vez ao entrar no estado, e não a cada mensagem recusada: as mensagens recusadas chegam como message.status com status failed."},"event_type":{"type":"string","const":"number.payment_required"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.payment_resolved":{"post":{"tags":["Webhooks and events"],"summary":"Number sending again after the payment wait","description":"A send from this number was accepted by Meta again after a wait for a payment method. It is the only signal that payment was fixed: Meta does not announce it and offers no lookup. Messages refused during the wait are not resent on their own.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."}},"required":["id","phone_number_id","display_number","external_id"],"additionalProperties":false,"description":"Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas; envie de novo o que ainda interessa."},"event_type":{"type":"string","const":"number.payment_resolved"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.restricted":{"post":{"tags":["Webhooks and events"],"summary":"Account restricted by Meta","description":"Meta restricted the number’s WhatsApp Business account. It carries Meta’s type, deadline and guidance in restrictions. The notice belongs to the account: one event goes out per connected number of it, all with the same waba_id. The account owner fixes it in WhatsApp Manager. The Account health guide covers each case.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.restricted"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"restrictions":{"type":"array","items":{"type":"object","properties":{"restriction_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da restrição, no vocabulário da Meta."},"expiration":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo."},"remediation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O que a Meta diz que resolve a restrição, quando informa."}},"required":["restriction_type","expiration","remediation"],"additionalProperties":false},"description":"As restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar."}},"required":["waba_id","number_id","display_number","external_id","restrictions"],"additionalProperties":false,"description":"A Meta restringiu a conta de WhatsApp Business deste número. O que a restrição impede depende do tipo: confira restrictions[].restriction_type e o prazo em expiration. A Luna não levanta restrição; quem resolve é o dono da conta, no WhatsApp Manager da Meta. A Meta não avisa quando uma restrição por prazo termina."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.violation":{"post":{"tags":["Webhooks and events"],"summary":"Policy violation on the account","description":"Meta recorded a policy violation on the number’s WhatsApp Business account. It is a warning: the account can be restricted or disabled if the violation is not handled. One event goes out per number of the account.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.violation"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"violation_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo da violação, no vocabulário da Meta."}},"required":["waba_id","number_id","display_number","external_id","violation_type"],"additionalProperties":false,"description":"A Meta registrou uma violação de política na conta de WhatsApp Business deste número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. O dono da conta lê os detalhes no WhatsApp Manager da Meta."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.disabled":{"post":{"tags":["Webhooks and events"],"summary":"Account disabled by Meta","description":"Meta disabled the number’s WhatsApp Business account, and sends stop being accepted. Luna does not reinstate accounts: the owner asks Meta for a review. One event goes out per number of the account, and account.reinstated announces it if the account comes back.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.disabled"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"ban_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A data da desativação, como a Meta informou."}},"required":["waba_id","number_id","display_number","external_id","ban_date"],"additionalProperties":false,"description":"A Meta desativou a conta de WhatsApp Business deste número. Os envios param de ser aceitos. A Luna não reativa conta: o dono dela pede a revisão à Meta, e o evento account.reinstated avisa se a conta voltar."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.reinstated":{"post":{"tags":["Webhooks and events"],"summary":"Account reinstated by Meta","description":"Meta reinstated the number’s WhatsApp Business account after a deactivation. One event goes out per number of the account.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.reinstated"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"ban_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A data informada pela Meta junto com a reativação, quando houver."}},"required":["waba_id","number_id","display_number","external_id","ban_date"],"additionalProperties":false,"description":"A Meta reativou a conta de WhatsApp Business deste número depois de uma desativação."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.update":{"post":{"tags":["Webhooks and events"],"summary":"Another account notice from Meta","description":"An account notice from Meta that Luna does not translate into a type of its own, with Meta’s raw event field (for example ACCOUNT_DELETED, ACCOUNT_RECONNECTED or VOLUME_BASED_PRICING_TIER_UPDATE). If you do not use it, ignore it.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.update"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"event":{"type":"string","minLength":1,"description":"O campo event do aviso account_update da Meta, sem tradução: ACCOUNT_DELETED, ACCOUNT_RECONNECTED, VOLUME_BASED_PRICING_TIER_UPDATE, DISABLED_UPDATE com um estado que não é desativação nem reativação, e outros. Novos valores podem aparecer."},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"O restante do aviso da Meta, como ela mandou, sem o campo event."}},"required":["waba_id","number_id","display_number","external_id","event","details"],"additionalProperties":false,"description":"Um aviso de conta da Meta que a Luna não traduz em um tipo próprio. Chega com o event cru da Meta para que o seu sistema decida o que fazer com ele. Se você não usa, ignore."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.limit_changed":{"post":{"tags":["Webhooks and events"],"summary":"Account limit changed","description":"Meta changed the account limit: the messaging limit, which counts unique people outside the customer service window (TIER_250, TIER_2K, TIER_10K, TIER_100K or TIER_UNLIMITED), or the number ceiling. It is the granted ceiling, never how much was used. It holds for the whole portfolio, so one event goes out per number of the account.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.limit_changed"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"daily_conversation_limit":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Conta pessoas únicas a quem o negócio escreve fora da janela de atendimento, e é do portfólio empresarial. É o teto concedido, e nunca quanto foi usado. Nulo quando o aviso mudou só o limite de números."},"max_phone_numbers_per_waba":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Quantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas."}},"required":["waba_id","number_id","display_number","external_id","daily_conversation_limit","max_phone_numbers_per_waba"],"additionalProperties":false,"description":"A Meta mudou o limite desta conta. O limite é do portfólio de negócio, e vale para todos os números da conta. O valor corrente de cada número está em limiteDiarioDeConversas, em GET /v1/numbers."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.disconnected":{"post":{"tags":["Webhooks and events"],"summary":"Number disconnected","description":"The number is no longer connected to Luna: the customer removed the app, Luna was removed as the account’s partner, the account’s link to Luna was ended, or you disconnected it with DELETE /v1/numbers/{id} (reason requested_by_tenant). It is the pair of number.connected. To come back, your customer connects again with a new connect link. The reason is in the reason field.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"reason":{"type":"string","minLength":1,"description":"O motivo da desconexão: requested_by_tenant (você desconectou o número com DELETE /v1/numbers/{id}), ou o aviso da Meta que a causou, PARTNER_APP_UNINSTALLED (o cliente removeu o aplicativo), PARTNER_REMOVED (a Luna foi removida como parceira da conta) ou ACCOUNT_OFFBOARDED (o vínculo da conta com a Luna foi encerrado). Novos valores podem aparecer."},"disconnection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O motivo que a Meta informou em disconnection_info, quando informa."},"initiated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quem iniciou a desconexão, como a Meta informou."}},"required":["id","phone_number_id","display_number","external_id","waba_id","reason","disconnection_reason","initiated_by"],"additionalProperties":false,"description":"O número deixou de estar conectado à Luna. É o par de number.connected. Os envios deste número não funcionam mais; para voltar, o seu cliente precisa conectar de novo, com um novo link de conexão."},"event_type":{"type":"string","const":"number.disconnected"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.quality_changed":{"post":{"tags":["Webhooks and events"],"summary":"Number quality changed","description":"The number’s quality rating changed (GREEN, YELLOW, RED). Meta has no webhook for this: Luna checks quality periodically, so the event arrives with a delay of up to about an hour. The history is in GET /v1/numbers/{id}/health.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"previous_quality_rating":{"type":"string","minLength":1,"description":"A avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED."},"quality_rating":{"type":"string","minLength":1,"description":"A avaliação de qualidade atual, no vocabulário da Meta."}},"required":["id","phone_number_id","display_number","external_id","waba_id","previous_quality_rating","quality_rating"],"additionalProperties":false,"description":"A avaliação de qualidade do número mudou. A Meta não tem webhook para isso: a Luna confere a qualidade de cada número periodicamente, então o evento chega com atraso de até a cadência da conferência (cerca de uma hora). O histórico está em GET /v1/numbers/{id}/health."},"event_type":{"type":"string","const":"number.quality_changed"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.display_name_reviewed":{"post":{"tags":["Webhooks and events"],"summary":"Display name reviewed","description":"The review state of the number’s display name changed (status: approved, pending_review, declined, expired or none), for example from pending_review to approved or declined. name is the name the state refers to. Meta does not report the reason for a refusal in this query. Luna checks the name periodically, so the event arrives with a delay of up to about an hour. An approved name only takes effect after the number is registered again. The current state is in displayNameStatus, in GET /v1/numbers/{id}.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"status":{"type":"string","minLength":1,"description":"O estado da revisão do nome de exibição, o mesmo de displayNameStatus em GET /v1/numbers/{id}: approved, pending_review, declined, expired ou none. Novos valores podem aparecer."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome a que o estado se refere: o nome pedido, quando há um pedido, senão o nome em uso. Nulo quando a Meta não informou."}},"required":["id","phone_number_id","display_number","external_id","waba_id","status","name"],"additionalProperties":false,"description":"O estado da revisão do nome de exibição do número mudou, por exemplo de pending_review para approved ou declined. A Luna confere o nome de cada número periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo; o estado corrente está em displayNameStatus, em GET /v1/numbers/{id}."},"event_type":{"type":"string","const":"number.display_name_reviewed"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.credential_expiring":{"post":{"tags":["Webhooks and events"],"summary":"Customer authorization about to expire","description":"The authorization the customer gave Luna to operate the number expires within 14 days (credential_expires_at). To renew it, the customer reconnects: create a link with POST /v1/onboarding/links passing numberId and it opens the reconnection of this number directly, without counting a new number. It goes out once per expiry and per number of the account. An authorization issued without an expiry never produces this event.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"credential_expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. É o mesmo valor que GET /v1/business-accounts devolve em credentialExpiresAt. Depois dessa data a Meta recusa as chamadas da Luna nesta conta, e o número para de enviar e de receber."}},"required":["id","phone_number_id","display_number","external_id","waba_id","credential_expires_at"],"additionalProperties":false,"description":"A autorização que o cliente deu à Luna para operar este número vence em até 14 dias. Para renovar, o seu cliente refaz a conexão: abra um link com POST /v1/onboarding/links informando numberId, e ele cai direto na reconexão deste número, sem contar um número novo. O evento sai uma vez por vencimento e por número, e não se repete a cada dia. Se a autorização foi emitida sem prazo, ele não sai nunca."},"event_type":{"type":"string","const":"number.credential_expiring"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"account.alert":{"post":{"tags":["Webhooks and events"],"summary":"Alert from Meta about the account","description":"Meta sent an alert about the number’s WhatsApp Business account (the account_alerts field), for example a denied limit increase or a lost profile picture. The fields arrive as Meta sent them, untranslated. The alert belongs to the account: one event goes out per connected number of it, all with the same waba_id.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"account.alert"},"waba":{"type":"object","properties":{"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id."},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número)."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O identificador, na Meta, do que o alerta cita."},"alert_severity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A gravidade que a Meta atribuiu ao alerta, no vocabulário dela."},"alert_status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Se o alerta está ativo ou foi resolvido, no vocabulário da Meta."},"alert_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O tipo do alerta, no vocabulário da Meta: por exemplo INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED, INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO ou PROFILE_PICTURE_LOST. Novos valores podem aparecer."},"alert_description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A descrição do alerta, em texto, como a Meta mandou."},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"O restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia."}},"required":["waba_id","number_id","display_number","external_id","entity_type","entity_id","alert_severity","alert_status","alert_type","alert_description","details"],"additionalProperties":false,"description":"A Meta mandou um alerta sobre a conta de WhatsApp Business deste número (o campo account_alerts). Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager da Meta."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","waba"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.action_required":{"post":{"tags":["Webhooks and events"],"summary":"Number needs action","description":"This number now needs an action from you or your customer: the customer authorization expiring or expired, no payment method at Meta, a restricted or disabled account, a PIN requested, registration blocked or a suspended plan. It carries status, can_send and reasons, each cause with code, message and solution, ready to show to your customer. It goes out when the list of causes goes from empty to non-empty, and not at every change to it; it is the same calculation as connection in GET /v1/numbers/{id}. When the list empties, number.action_resolved goes out.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}."},"can_send":{"type":"boolean","description":"Se o envio por este número vai funcionar agora, o mesmo de connection.canSend."},"reasons":{"minItems":1,"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"O código do motivo, para o seu código comparar: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired, account_blocked. Novos códigos podem aparecer."},"message":{"type":"string","description":"O que está acontecendo, em português, pronto para repassar ao seu cliente."},"solution":{"type":"string","description":"O que fazer a respeito, em português."}},"required":["code","message","solution"],"additionalProperties":false},"description":"Os motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento."}},"required":["id","phone_number_id","display_number","external_id","status","can_send","reasons"],"additionalProperties":false,"description":"Este número passou a precisar de uma ação sua ou do seu cliente: autorização vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela. Mostra o motivo ao seu cliente com message e solution. Quando a lista esvazia, sai number.action_resolved. O estado corrente está em connection, em GET /v1/numbers/{id}."},"event_type":{"type":"string","const":"number.action_required"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"number.action_resolved":{"post":{"tags":["Webhooks and events"],"summary":"Number no longer needs action","description":"The number no longer needs action: the list of causes in connection emptied, after a number.action_required. It is its pair, as number.payment_resolved is the pair of number.payment_required. status says how the connection ended up. A number you disconnected does not produce this event: number.disconnected already announced it.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link."},"status":{"type":"string","enum":["connected","connecting","action_required","disconnected"],"description":"O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}."},"can_send":{"type":"boolean","description":"Se o envio por este número vai funcionar agora, o mesmo de connection.canSend."}},"required":["id","phone_number_id","display_number","external_id","status","can_send"],"additionalProperties":false,"description":"Este número não precisa mais de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou (connected, ou connecting se a conexão voltou a estar em curso)."},"event_type":{"type":"string","const":"number.action_resolved"}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"onboarding.link.completed":{"post":{"tags":["Webhooks and events"],"summary":"Connect link completed","description":"Your customer completed the connection through a link: the link becomes used. It carries the link externalId and, when Luna has already registered the number, number_id; the number.connected event announces when the number is ready to send. It goes out once per link.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão ou o que resultou da conexão, ou null quando o evento não tem número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"display_number":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."}},"required":["id","phone_number_id","display_number","external_id","waba_id"],"additionalProperties":false},{"type":"null"}],"description":"O número que resultou da conexão, no mesmo formato dos eventos number.*, com waba_id. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto."},"event_type":{"type":"string","const":"onboarding.link.completed"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"used_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}."},"waba_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A conta de WhatsApp Business que o seu cliente conectou, o mesmo id que GET /v1/business-accounts devolve em wabaId. Está preenchido mesmo quando a conta foi conectada sem número (number_id nulo). Nulo só se a Luna não a leu."},"number_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"O número que resultou da conexão, o mesmo id de GET /v1/numbers. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto."}},"required":["id","external_id","used_at","waba_id","number_id"],"additionalProperties":false,"description":"O seu cliente concluiu a conexão por um link: ele aceitou os termos da Meta e a Luna recebeu o acesso à conta dele. É o fim do link, que passa a used. O número pode ainda estar sendo registrado: quem avisa que ele ficou pronto para enviar é number.connected. Sai uma vez por link."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"onboarding.link.opened":{"post":{"tags":["Webhooks and events"],"summary":"Connect link opened","description":"Your customer opened the link for the first time. It goes out once per link, and not again when they come back to the page or try again. It carries the link externalId and opened_at. It is the start of the cycle: onboarding.link.completed, onboarding.link.failed or onboarding.link.expired follow. Whoever opened and never completed shows up here without a completed.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão, ou null quando o link é de uma conexão nova."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"onboarding.link.opened"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"opened_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o seu cliente abriu o link pela primeira vez."}},"required":["id","external_id","opened_at"],"additionalProperties":false,"description":"O seu cliente abriu o link pela primeira vez. Sai uma vez por link, na primeira abertura, e não de novo quando ele volta à página ou tenta outra vez. É o começo do ciclo: depois dele vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"onboarding.link.failed":{"post":{"tags":["Webhooks and events"],"summary":"A connect link attempt did not work out","description":"A connection attempt through a link did not work out. reason says why: abandoned (the customer closed Meta’s window, and step carries the screen where they stopped), error (Meta’s window reported an error, in error_code), failed (Luna tried to complete and could not), country_not_supported (the number is not +55) or registration_blocked (Meta blocked registration for 72 hours). The link stays open until it expires. It goes out once per attempt.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão, ou null quando o link é de uma conexão nova."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"onboarding.link.failed"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"session_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"A tentativa de conexão que não deu certo. Um link aberto admite várias."},"reason":{"type":"string","enum":["abandoned","error","failed","country_not_supported","registration_blocked"],"description":"Por que a tentativa não deu certo: abandoned (o cliente fechou a janela da Meta e a tela em que parou está em step), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir várias vezes e não conseguiu), country_not_supported (o número escolhido não é +55) ou registration_blocked (a Meta bloqueou o registro do número por 72 horas). Novos motivos podem aparecer."},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado."},"error_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"O código de erro que a janela da Meta relatou. Nulo quando não houve erro relatado."}},"required":["id","external_id","session_id","reason","step","error_code"],"additionalProperties":false,"description":"Uma tentativa de conexão por um link não deu certo: o cliente desistiu em alguma tela, a janela da Meta relatou um erro, ou a conexão parou. O link continua aberto até vencer, e o cliente pode tentar de novo. Sai uma vez por tentativa. O que o cliente deve fazer para cada reason está no guia Conectar um número."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"onboarding.link.expired":{"post":{"tags":["Webhooks and events"],"summary":"Connect link expired","description":"The link expired with nobody completing the connection. Create another with POST /v1/onboarding/links whenever you want. A used link never produces this event. It goes out once per link.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},{"type":"null"}],"description":"O número do link de reconexão, ou null quando o link é de uma conexão nova."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do número na Luna, o mesmo que GET /v1/numbers devolve."},"phone_number_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"O identificador do número na Meta, o mesmo que a listagem de números devolve."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes."}},"required":["id","phone_number_id","external_id"],"additionalProperties":false},{"type":"null"}],"description":"O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número."},"event_type":{"type":"string","const":"onboarding.link.expired"},"link":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do link, o mesmo que POST /v1/onboarding/links devolveu."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele."},"expired_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o link venceu, o mesmo expiresAt de GET /v1/onboarding/links/{id}."}},"required":["id","external_id","expired_at"],"additionalProperties":false,"description":"O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link que foi usado nunca gera este evento. Sai uma vez por link."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","link"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"template.category":{"post":{"tags":["Webhooks and events"],"summary":"A template category changed","description":"Meta changed, or announced it will change, a template category. The category sets the price Meta charges the business: from UTILITY to MARKETING, the price goes up. It arrives as an advance notice (correct_category and scheduled_for) and as a change made (previous_category and new_category). It has no number and no message.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o template pertence à conta de negócio, e não a um número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"template.category"},"template":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem."},"name":{"type":"string","minLength":1,"description":"O nome do template."},"language":{"type":"string","minLength":1,"description":"O idioma do template, no código da Meta."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts)."},"category":{"type":"string","minLength":1,"description":"A categoria do template, no vocabulário da Meta."},"previous_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio."},"new_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio."},"correct_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"No aviso prévio, a categoria para a qual a Meta vai mudar o template. Nulo quando a mudança já foi feita."},"scheduled_for":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},{"type":"null"}],"description":"No aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita."}},"required":["id","name","language","waba_id","external_id","category","previous_category","new_category","correct_category","scheduled_for"],"additionalProperties":false,"description":"A Meta mudou, ou vai mudar, a categoria de um template. Chega de duas formas: o aviso prévio (correct_category e scheduled_for preenchidos) e a mudança feita (previous_category e new_category preenchidos). A categoria define o preço que a Meta cobra do negócio por mensagem: de UTILITY para MARKETING, o preço sobe. Quem paga é o dono da conta, direto à Meta."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","template"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}},"template.quality":{"post":{"tags":["Webhooks and events"],"summary":"A template quality changed","description":"A template quality score changed (GREEN, YELLOW, RED). A low score comes before Meta pauses the template. It has no number and no message.\n\nLuna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.","security":[],"parameters":[{"name":"x-luna-signature","in":"header","required":true,"description":"The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","const":"2026-11-10","description":"A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir."},"event_id":{"type":"string","minLength":64,"maxLength":64,"description":"O identificador estável deste evento. Use-o para descartar repetições."},"occurred_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","description":"Quando o evento ocorreu, em UTC."},"phone_number_id":{"type":"null","description":"Sempre null neste tipo: o template pertence à conta de negócio, e não a um número."},"test":{"description":"Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.","type":"boolean","const":true},"number":{"type":"null","description":"Sempre null neste tipo: o evento não passa por um número."},"event_type":{"type":"string","const":"template.quality"},"template":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem."},"name":{"type":"string","minLength":1,"description":"O nome do template."},"language":{"type":"string","minLength":1,"description":"O idioma do template, no código da Meta."},"waba_id":{"type":"string","minLength":1,"description":"A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId."},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts)."},"previous_quality_score":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN."},"new_quality_score":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A nota de qualidade de agora, no vocabulário da Meta."}},"required":["id","name","language","waba_id","external_id","previous_quality_score","new_quality_score"],"additionalProperties":false,"description":"A nota de qualidade de um template mudou. Nota baixa antecede a pausa do template pela Meta: é o momento de revisar o conteúdo ou o público."}},"required":["version","event_id","occurred_at","phone_number_id","number","event_type","template"],"additionalProperties":false}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery. Luna does not read the response body."}}}}}}