LunaDocumentaçãoEntrar

Vindo da Z-API ou da Evolution: migrar para a Luna

A Z-API e a Evolution API são camadas sobre biblioteca não-oficial; a Luna opera exclusivamente sobre a WhatsApp Cloud API oficial da Meta, na condição de Tech Provider aprovado. Elas fazem coisas parecidas por caminhos diferentes, e a diferença de caminho é o assunto deste documento. Na Luna, a instância é o número, e o externalId é o fio que amarra o cliente do seu produto ao número, à chave, ao webhook, ao evento e ao link.

Leia as três diferenças abaixo antes da tabela. Elas são o que quebra uma migração no meio: quem começa pela tabela descobre a primeira delas no primeiro cliente que responde no dia seguinte, com o desenho já pronto.

Três coisas que vão mudar o seu desenho

1. A janela de 24 horas existe, e não há como contorná-la

Na Cloud API oficial, texto livre só sai para quem falou com você nas últimas 24 horas. Passado esse prazo, o único caminho é um template aprovado pela Meta. Numa biblioteca não-oficial essa restrição não aparece, porque ela conversa pelo mesmo canal de um aparelho. O desenho que funcionava lá presume uma liberdade que aqui não existe.

Leia `GET /v1/conversations` antes de decidir como responder. Cada linha traz `windowOpen`, `windowExpiresAt` e `windowSource`: a plataforma avisa **antes** de você gastar a chamada, em vez de devolver um erro depois. Com a janela fechada, o caminho é enviar um template, e a mensagem livre volta quando o contato responder.

2. O envio responde `202`, e o identificador da Meta não vem junto

O `POST /v1/messages` devolve `202` com um identificador da Luna e o estado `queued`. Ele não devolve o `wamid`, porque nesse instante a Meta ainda não o emitiu. Quem integrou esperando o identificador definitivo na resposta precisa mudar o desenho, e essa é a segunda coisa que quebra uma migração.

A razão é honesta e vale saber: o limite que mais aperta na Cloud API é o do mesmo destinatário: passada uma rajada curta, uma mensagem a cada seis segundos. Um agente que responde em rajada dispara esse limite sozinho, e a resposta certa a isso é fila, nunca um erro devolvido a você. Guarde o identificador da Luna, e receba o `wamid` e o estado de entrega pelo seu webhook, no evento `message.status`.

3. Não há QR Code, e não pode haver

Conectar um número lendo um QR Code com o aparelho é o modelo de uma biblioteca que se apresenta como um WhatsApp Web. A plataforma oficial não funciona assim: cada negócio final precisa da própria conta de WhatsApp Business na Meta, com o método de pagamento dele, e a conexão acontece pelo fluxo que a Meta chama de Embedded Signup: dentro do seu produto, mas contra a Meta.

Esta é a diferença que **não tem contorno**, e ela é a razão de a Luna existir na forma que existe. É também o que separa uma conexão que sobrevive de uma que é desligada: o número é do seu cliente, na conta dele, e a Helsen opera como Tech Provider aprovado pela Meta. O ciclo começa em `POST /v1/onboarding/sessions` e termina em `POST /v1/onboarding/sessions/{id}/complete`.

O ciclo de vida da instância, na Luna

Se o seu produto cria uma instância por cliente, o caminho é este: cada verbo do ciclo de vida tem um par na Luna, ou a razão de não ter. O passo a passo completo de um produto com muitos clientes, com código que roda, está no guia SaaS com N clientes da documentação.

Na Z-API ou na EvolutionNa LunaO que saber
Criar uma instância para o cliente.Criar um link de conexão com o `externalId` do cliente: `POST /v1/onboarding/links`.Não existe objeto antes do número. O mais perto é o link: o seu cliente o abre, aceita os termos da Meta e conecta o número dele. Você ouve o fim da conexão no evento `number.connected` e acompanha o link por `onboarding.link.completed`, `onboarding.link.failed` e `onboarding.link.expired`, todos com o `externalId`. O `redirectUrl` leva o cliente de volta ao seu produto.
Mostrar o QR Code e esperar a leitura com o aparelho.A janela da Meta, aberta pela página do link. Não há equivalente em código seu.Conectar leva alguns minutos, e não dois: o cliente precisa de uma conta no Facebook, do portfólio de negócios dele e, depois, do método de pagamento dele na Meta. Quem usa o aplicativo WhatsApp Business no celular pode manter o aplicativo e o histórico (coexistência). A diferença de modelo do QR Code está explicada acima.
Perguntar o estado da conexão da instância (`connectionState`, `open` ou `close`).Ler `connection.status` e `connection.reasons` do número: `GET /v1/numbers/{id}` ou `GET /v1/numbers`.O `connection.status` é `connected`, `connecting`, `action_required` ou `disconnected`, o `connection.canSend` diz se enviar vai funcionar agora, e cada motivo traz `code`, `message` e `solution` em português para repassar ao cliente. Você não precisa consultar: os eventos `number.action_required` e `number.action_resolved` avisam. A lista aceita `?state=`, `?ready=`, `?canSend=` e `?externalId=`.
Reiniciar, desconectar a sessão (logout) ou pôr a instância para dormir.Nada a fazer: não há sessão para reiniciar.A Cloud API não tem sessão que caia. O número fica registrado na Meta, e o que muda é a autorização que o cliente deu à Luna: quando ela vence ou morre, o número pede ação (`credential_expiring` ou `credential_invalid`) e você abre um link de reconexão com `numberId`.
Configurar um webhook por instância.Um endpoint com `externalIds` para uma URL por cliente, ou um endpoint só e o `number.external_id` de cada evento: `POST /v1/webhooks/endpoints`.O endpoint é da conta e ganha filtro por cliente (`externalIds`) e por número (`phoneNumberIds`), aplicado onde os eventos são publicados. A assinatura, a ordem, o reenvio e a fila de rejeitados são os de qualquer endpoint, por URL. O caminho recomendado é um endpoint só, separando por `external_id`.
Um token por instância, que o seu cliente usa.Uma chave de API com `externalId`: `POST /v1/api-keys`.A chave com `externalId` só lê e envia pelos números daquele cliente, inclusive os conectados depois, só cria link com o `externalId` dele e não lista nem cria endpoint de webhook nem chave. O número de outro cliente responde `404`. A chave sem `externalId` é a da conta e enxerga todos.
Apagar a instância.Desconectar o número: `DELETE /v1/numbers/{id}`.O número sai da Luna, para de contar na capacidade e o evento `number.disconnected` avisa. A Luna não chama `deregister`, para não derrubar o número do cliente em outro provedor ou no aplicativo. O histórico não é apagado.
A instância para quando a assinatura dela vence.O número pede ação: `payment_required` em `connection`, e o evento `number.payment_required`.O pagamento do uso da plataforma é do negócio dono do número, direto à Meta, e a Luna não o intermedeia. Quando a Meta recusa um envio por falta de método de pagamento, o número fica conectado e sem enviar até o cliente resolver na Meta. A capacidade do plano da Luna (`GET /v1/subscription`) é outra coisa: quantos números a conta mantém ativos.

Capacidade a capacidade

O mapa é por capacidade, e não por assinatura de rota: prometer que uma chamada vira outra seria prometer paridade, e não é o caso. Onde não há equivalente, a razão está escrita, e quase sempre ela é uma regra da plataforma oficial, não uma escolha da Luna.

CapacidadeNa Evolution APINa LunaO que saber
Enviar uma mensagem de textoUma rota de envio de texto por instância, respondendo com o resultado do envio.POST /v1/messagesO corpo traz `from`, `to` e `text.body`. A resposta é `202` com o identificador da Luna e o estado `queued`; o `wamid` chega depois, pelo webhook. Um corpo sem `type` é interpretado como texto.
Enviar imagem, áudio, vídeo ou documentoUma rota de envio de mídia por instância, aceitando o arquivo em base64 ou por URL.POST /v1/numbers/{id}/media, depois POST /v1/messagesSão dois passos porque a Meta trabalha com identificador de mídia. Suba o arquivo em `multipart/form-data`, receba o identificador e use-o no envio. Enviar por `link` também funciona, e nesse caso a URL precisa responder sem autenticação. O identificador evita isso e pode ser reaproveitado em várias mensagens.
Iniciar conversa fora da janela de 24 horasNormalmente não existe como conceito: o envio de texto vale a qualquer momento.POST /v1/templates, depois POST /v1/messages com `type: template`É a consequência direta da primeira diferença de modelo. O template é criado, submetido à Meta e usado depois de aprovado, e o estado dele chega ao seu endpoint pelo evento `template.status`, sem que você precise ficar consultando.
Receber o que chega no númeroUm webhook configurado por instância, com os eventos escolhidos na configuração.POST /v1/webhooks/endpointsUm endpoint para o tenant inteiro, e não por número: os eventos dizem de que número vieram. Toda entrega é assinada, e o segredo pode ser rotacionado sem janela de indisponibilidade por `POST /v1/webhooks/endpoints/{id}/rotacionar`, que mantém o segredo anterior válido por um período.
Recuperar o que o seu servidor não recebeuDepende da instalação; frequentemente não há retentativa nem registro do que falhou.GET /v1/webhooks/dlq, POST /v1/webhooks/dlq/{id}/reenfileirarUm evento chega à fila de rejeitados depois de a política de retentativa se esgotar. Ele não é entregue de novo sozinho: ou você o re-enfileira, ou ele fica lá até a retenção expirar. A resposta não traz total, de propósito: para saber quantos itens há, pagine até `nextCursor` vir nulo.
Consultar o histórico de mensagensUma consulta ao armazenamento da própria instância, com filtros por chat.GET /v1/messages, GET /v1/conversationsFiltre por `phoneNumberId` ou por `conversationId`, e pagine com `nextCursor`. O cursor é opaco: ele carrega posição e não contagem, então não tente construir um à mão.
Saber se a mensagem foi entregue e lidaEventos de atualização de status entregues pelo webhook da instância.Evento `message.status` no seu webhook, e GET /v1/messages/{id}O estado chega por evento, e a consulta por identificador serve para reconciliar. É por aqui que o `wamid` da Meta se liga ao identificador que o `202` devolveu no envio.
Baixar a mídia que o cliente enviouA mídia costuma vir embutida no evento, ou é buscada no armazenamento da instância.GET /v1/messages/{id}/mediaA Luna guarda o arquivo e o serve por esta rota. A URL de download que a Meta emite expira em cinco minutos, e guardar essa URL é a forma mais comum de uma retentativa falhar sempre. Por isso ela nunca é repassada.
Marcar como lida e mostrar “digitando”Rotas de presença e de leitura por instância.POST /v1/messages/{id}/read, POST /v1/messages/{id}/typingExistem e funcionam, e são o que faz um agente automático parecer atendimento e não robô. Ambas agem sobre a mensagem recebida, e não sobre a conversa.
Conectar um número novoCriar uma instância e ler o QR Code com o aparelho que tem o número.POST /v1/onboarding/sessions e o fluxo Embedded Signup**Sem equivalente, e é a diferença que não tem contorno.** O onboarding é Embedded Signup porque cada negócio final precisa da própria conta de WhatsApp Business e do próprio método de pagamento na Meta, que é a condição de operar como Tech Provider. O número é do seu cliente, na conta dele, e é isso que faz a conexão sobreviver.
Listar os números conectados e o estado de cada umUma listagem de instâncias, com o estado da conexão de cada uma.GET /v1/numbers, GET /v1/numbers/{id}O identificador da Luna e o da Meta são campos distintos, e todas as rotas que recebem um número aceitam os dois (`id` da Luna e `metaPhoneNumberId`), então use o que o seu sistema já guarda.
Criar grupo, entrar em grupo, mandar para grupoRotas de grupo, herdadas de a biblioteca se apresentar como um aparelho.Sem equivalente**Sem equivalente.** A Cloud API oficial não expõe grupos a um número de negócio: o produto que a Meta publica é a conversa entre uma empresa e uma pessoa. Não é uma escolha da Luna, e nenhuma plataforma oficial oferece isso.
Ler a agenda, o perfil e a foto de quem escreveuRotas de contato e de perfil, pela mesma razão da linha acima.Sem equivalente**Sem equivalente.** Um número de negócio na plataforma oficial não tem agenda, e o perfil de quem escreve não é publicado. O que chega é o telefone do interlocutor e o nome que ele mesmo expôs no evento, e é sobre isso que dá para trabalhar.
Verificar se um número tem WhatsApp antes de mandarUma rota de verificação, respondendo se o número existe na rede.Sem equivalente**Sem equivalente.** A plataforma oficial não publica essa consulta. O envio para um número sem WhatsApp simplesmente não é entregue, e você fica sabendo pelo evento de status, que é a informação equivalente, um passo depois.
Autenticar as suas chamadasUma chave global da instalação, normalmente num cabeçalho próprio.POST /v1/api-keysA chave vai em `Authorization: Bearer hlsn_…` e carrega **escopos**: uma rota fora do conjunto responde `403`. Dê a cada chave só o que ela precisa: uma que só envia mensagem não deveria poder conectar número. Ela é mostrada uma única vez, e não há rota que a devolva depois.

O que a Helsen cobra, e o que a Meta cobra

A assinatura da Helsen é pela capacidade de números ativos do seu plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, diretamente do seu cliente final, no método de pagamento que ele cadastra na conta dele. A Helsen não intermedeia esse pagamento e não o repassa. É por isso que cada negócio final precisa de conta própria na Meta.

Por onde começar

A documentação da API traz o contrato de cada rota, com exemplos, e há um cliente TypeScript gerado dela, o mesmo que o console da Helsen usa. Se algo neste guia não bater com a documentação, é a documentação que vale: ela é derivada do código que valida as requisições.

O de-para de autenticação, envio, eventos e estados, e a lista do que não existe na API oficial, está no guia da documentação: Vindo da Z-API ou da Evolution API.

WhatsApp e Meta são marcas da Meta Platforms, Inc. Evolution API é projeto de terceiros, sem relação com a Helsen. Este documento descreve o modelo de cada plataforma para quem está migrando, e não é comparação comercial.