> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # QuickLink > Conecte um número de WhatsApp com um único link hospedado. Um QuickLink é uma página hospedada da Polymorfa por trás de uma URL persistente. Quem abre o link confirma o próprio número de telefone, escolhe um tipo de conexão permitido e conclui o cadastro ou pareia um dispositivo vinculado para o seu projeto. Use o QuickLink para conexões pela Meta Cloud API ou por Dispositivos vinculados. Os endpoints diretos de código QR e de código de pareamento exigem acesso de pareamento direto para a equipe dona do número. A API retorna `403` quando esse acesso não existe. Toda equipe ativa pode criar QuickLinks para números de teste. QuickLinks para números reais exigem Pay-As-You-Go; consulte [Limites de equipes Free](#limites-de-equipes-free). Criar um link não financia um número: o pareamento verifica o financiamento do número antes de iniciar a conexão. Equipes congeladas e projetos inativos não podem iniciar o onboarding. A Meta Cloud API e os números de teste mantêm os próprios requisitos de acesso. Os links continuam ativos até o número conectar ou até você cancelá-los. Eles não concedem acesso a mensagens. O onboarding pela Meta Cloud API exige acesso da equipe ao beta e um projeto ativo. Configurar apenas os IDs de app da Meta não o ativa. Opções opcionais indisponíveis da Meta Cloud API ficam ocultas; um projeto que impõe a Meta Cloud API não consegue emitir um link sem acesso. Retirar o acesso interrompe novos pedidos de onboarding e de histórico, mas mantém a reconciliação das operações já aceitas pela Meta. Um convite pendente pode informar `cloud_onboarding_unavailable`; isso não indica sucesso nem exclui ativos da Meta. ## Apps da Meta da própria equipe Equipes com o adicional Branded QuickLink ativo e acesso ao onboarding pela Meta Cloud API podem configurar o próprio app da Meta e a própria configuração de Embedded Signup para os QuickLinks. O seu app precisa das permissões e aprovações da Meta exigidas para os números que você conecta. Salvar as credenciais não concede essas aprovações nem ativa o acesso ao onboarding. O segredo do app é enviado uma única vez e não é retornado pela página de configurações. Substituir uma configuração vale para novos convites; os convites existentes mantêm o app salvo neles. Desconectar revoga as configurações salvas para os onboardings não concluídos. Isso não exclui ativos da Meta que pertencem ao cliente nem desconecta números já estabelecidos. Uma contestação de pagamento bloqueia o uso do app salvo até ser resolvida; as configurações dele continuam disponíveis para consulta. ### Quando o Branded QuickLink termina O app da sua equipe continua em uso enquanto o adicional está ativo, depois que você cancela a renovação até o fim do período pago e durante o período de recuperação de pagamento de três dias após uma falha no pagamento da renovação. Quando o acesso termina: * Novos QuickLinks e convites de cliente usam o app da Meta e a apresentação padrão da Polymorfa. A criação deles não falha por causa do seu app salvo. * Convites não concluídos que foram emitidos com o app da sua equipe param antes da próxima etapa da Meta. Envie um novo link. * Os números conectados continuam funcionando. A Polymorfa não para, não desconecta nem exclui um número porque o adicional terminou ou porque você desconectou o seu app. * A configuração salva do seu app é mantida até você desconectá-la. Ela volta a poder ser usada quando o adicional fica ativo de novo. Os membros da equipe recebem um aviso de cobrança quando um cancelamento é agendado, quando um pagamento de renovação falha e quando o acesso termina. O aviso de falha no pagamento informa o prazo de recuperação. A entrega segue as suas preferências de notificação. ## Verificar e renovar as credenciais da Meta Cloud API A Polymorfa valida periodicamente as credenciais da Meta salvas para cada número conectado pela Meta Cloud API. Cada verificação confirma que o token de acesso é válido, que ele tem as permissões `whatsapp_business_messaging` e `whatsapp_business_management` para a conta do WhatsApp Business, que a Meta informa o número de telefone como conectado e que o app está inscrito nos webhooks da conta. As verificações de números que compartilham a mesma conta do WhatsApp Business são espaçadas. Uma verificação apenas lê dados da Meta; ela nunca para nem reinicia o número. Leia o resultado mais recente com [`GET /messaging/{session}/cloud-credentials`](/api-reference/messaging/sessions/get-cloud-credential-health). `checkedAt` é o horário da última validação concluída. `status` é: | Status | Significado | | - | - | | `healthy` | Todas as verificações passaram. | | `action_required` | Uma verificação falhou. `failureCode` indica a primeira falha. | | `unknown` | Não foi possível acessar a Meta, ou ela retornou uma resposta incompleta. A verificação é tentada novamente mais cedo. | | `pending` | As credenciais não foram verificadas desde que foram salvas. | `failureCode` é um destes: `token_expired`, `token_invalid`, `token_app_mismatch`, `app_credentials_rejected` (o segredo do app salvo não corresponde mais ao app da Meta), `permission_missing`, `phone_not_registered`, `webhook_not_subscribed`, `credentials_unreadable`, `meta_unavailable` ou `meta_response_invalid`. Para renovar a autorização, pare o número e depois use um token de projeto com `quicklink:manage` para chamar [`POST /messaging/{session}/cloud-credentials/reauthorize`](/api-reference/messaging/sessions/reauthorize-cloud-credentials). A resposta contém um QuickLink vinculado ao mesmo número e ao mesmo número de telefone. Ele sempre usa a Meta Cloud API e o app da sua equipe enquanto o Branded QuickLink estiver ativo. Compartilhe o link com a pessoa que gerencia os ativos da Meta do número. Depois que ela conclui o Embedded Signup, o número inicia com as credenciais renovadas e é verificado de novo em poucos minutos. Acompanhe o progresso com [`GET /messaging/quicklinks/{id}`](/api-reference/messaging/quicklink/get-quick-link). O link de renovação tem a finalidade `reauthorization` no status do QuickLink. Você pode cancelá-lo antes de o trabalho na Meta começar, e o número existente continua na Polymorfa. Depois que o trabalho na Meta começa, o endpoint de cancelamento retorna `409`; confira o status do link antes de tomar outra ação. A reautorização retorna `409 state_conflict` enquanto o número está em execução e `501 operation_not_supported` para um número que também tem uma conexão de dispositivo vinculado. Os dois endpoints exigem acesso ao beta de onboarding pela Meta Cloud API e retornam `403 feature_unavailable` sem ele. Um adicional Branded QuickLink ativo também permite ocultar o Powered by Polymorfa. Cancelar a renovação mantém esse benefício até o fim do tempo pago. Depois que o direito expira, os QuickLinks voltam a mostrar a marca d'água; a sua preferência salva é mantida. O direito de marca vigente vale quando a página carrega e depois de atualizações de histórico ou de configuração de teste, inclusive para links criados antes de o direito mudar. Salvar `hideWatermark: true` sem o adicional retorna `402` com o código `addon_required`. Salvar um app da Meta da própria equipe sem ele retorna `403`. ## Financiar o pareamento de dispositivo vinculado A sua equipe precisa de crédito pré-pago suficiente para a primeira janela de 24 horas do número. O crédito é reservado antes de o material de pareamento ser emitido e consumido quando o WhatsApp confirma a conexão. Se o financiamento não estiver disponível, a página pede ao destinatário que entre em contato com quem enviou o link. Adicione crédito ou revise a prioridade de cobrança do projeto e depois envie um novo link. O endpoint de código de pareamento retorna `402` com `billing_credit_required`; a leitura do estado da página informa `failed` com esse código de erro. ## Limites de equipes Free Equipes Free não podem criar QuickLinks para números reais. Criar um retorna `409` com o código de erro `payg_required`. QuickLinks para números de teste e **Vincular um número real agora** no Console continuam disponíveis. Vincular um número real além da cota da equipe também retorna `payg_required`. Faça o upgrade da equipe para usar esses links; consulte [Equipes Free e Pay-As-You-Go](/pt-br/console/teams-and-projects#free-and-pay-as-you-go-teams). ## Criar um QuickLink Você pode criar o mesmo link hospedado em três lugares. **Console** Abra um projeto, vá em **Números**, selecione **Novo número** e escolha **Enviar um QuickLink**. Revise as configurações desse link, gere o link e depois copie a URL, compartilhe ou mostre como código QR para a câmera de um celular. O Console mostra o link passando de **Aberto** para **Vinculado** e para **Conectado**, e adiciona o número à lista quando o destinatário confirma. Para um número da Meta Cloud API, o link fica em **Vinculado** enquanto as [verificações de prontidão](#verificações-de-prontidão-da-meta-cloud-api) são executadas, e o Console indica a etapa de recuperação quando uma verificação falha. Enquanto a Meta não responde a uma verificação, **Cancelar QuickLink** continua disponível. Para parear um celular que está com você, escolha **Vincular um número real agora**. O Console executa um fluxo de pareamento autenticado dentro da janela. Essa tentativa incorporada não pode ser compartilhada nem aberta fora do Console. **API** Chame `POST /messaging/quicklinks` a partir do seu backend com uma chave de equipe que tenha `quicklink:manage`, ou com um token de projeto que tenha o mesmo escopo. ```bash theme={null} curl -X POST https://api.polymorfa.com/messaging/quicklinks \ -H "Authorization: Bearer $POLYMORFA_KEY" \ -H "Content-Type: application/json" \ -d '{ "projectId": "00000000-0000-4000-8000-000000000001" }' ``` ```json theme={null} { "success": true, "data": { "id": "ql_0c1d8f2a3b4c5d6e7f80", "url": "https://www.polymorfa.com/connect/…", "session": "739182640518203", "expiresAt": null } } ``` Envie `url` para a pessoa que está com o celular. Não registre a URL em logs. **Clientes** Abra um cliente e gere um link de pareamento. Esse link é durável e pode ser restrito a um telefone esperado. Quando o destinatário o abre, a Polymorfa emite um novo QuickLink e atribui o número verificado ao cliente. Consulte [Links de pareamento de clientes](/pt-br/guides/customers/pairing-links). ## Campos da solicitação Comece com `projectId`. Um token de projeto já identifica o projeto dele, então pode enviar um objeto JSON vazio. Uma chave de equipe precisa informar `projectId` quando a equipe tem mais de um projeto. O QuickLink começa confirmando o número do destinatário antes de iniciar uma conexão. A configuração salva **Permitir que o destinatário altere o número de telefone preenchido** controla se um número preenchido pode ser substituído; convites sem número preenchido aceitam um número informado pelo destinatário. Trocar de número espera qualquer tentativa por Dispositivos vinculados parar. Uma operação da Meta não resolvida precisa terminar antes da troca. Números de celular brasileiros são verificados com e sem o nono dígito. O número informado continua sendo o número usado na configuração da Meta; Dispositivos vinculados usa a identidade do WhatsApp resolvida. Quando as duas formas estão registradas, o destinatário seleciona a própria conta. As dicas da consulta não provam a titularidade nem a elegibilidade na Meta. Editar o número informado limpa as opções de conta; o destinatário verifica o novo número antes de selecionar uma conta. Um número confirmado como não registrado no WhatsApp pode usar a configuração dedicada da Meta Cloud API apenas quando essa conexão é permitida. Sem um número informado, os links elegíveis podem abrir a configuração de número da Meta; a Meta decide quais opções de número ficam disponíveis. A Polymorfa não garante um número informado. `configuration.connectionPreference: "both"` permite que o destinatário escolha uma conexão permitida. Ele não conecta os dois transportes. O QuickLink tira um snapshot das configurações salvas do seu projeto. Antes de criar um link, escolha o tipo de conexão, os métodos de pareamento, o número preenchido opcional e a política de sincronização do histórico. A criação pela API aceita essas escolhas em `configuration`. O texto da página, a aparência, o suporte, a privacidade, os termos e as URLs de retorno vêm das configurações salvas e não podem ser alterados em um link individual. A criação aceita estes campos do convite: | Para… | Adicione… | | - | - | | Oferecer apenas a leitura do código QR ou o pareamento pelo celular | `configuration.methods: ["qr"]` ou `methods: ["pairing"]` | | Escolher o primeiro método de Dispositivos vinculados | `configuration.defaultMethod: "qr"` ou `"pairing"`; envie `null` para escolher pelo dispositivo do destinatário | | Preencher o número de telefone do destinatário | `configuration.prefillPhone: "+15550001111"` | | Acompanhar a sessão resultante | `externalId` opcional, separado dos IDs gerados pela Polymorfa | | Preferir ou exigir um tipo de conexão | `configuration.connectionPreference` e `configuration.connectionEnforcement` | | Alterar o consentimento de histórico deste link | `configuration.historySync.consent` | | Atribuir o número a um cliente | `customerId`, com Clientes ativado para o projeto | Os campos de configuração omitidos herdam os padrões salvos. Defina `configuration.defaultMethod` como `null` para escolher códigos de pareamento em celulares e códigos QR em notebooks. Configure o texto e a aparência da página nas configurações de QuickLink da equipe ou do projeto. Configure a privacidade, os termos e as URLs de retorno nas configurações de QuickLink do projeto. Por exemplo, para oferecer pareamento pelo celular com o histórico desativado: ```json theme={null} { "projectId": "00000000-0000-4000-8000-000000000001", "configuration": { "prefillPhone": "+15550001111", "connectionPreference": "linked", "connectionEnforcement": "prefer", "methods": ["pairing"], "historySync": { "consent": "force_off" } } } ``` Para as opções de conexão, as opções de sincronização do histórico e os limites dos campos, consulte [Create a QuickLink](/api-reference/messaging/quicklink/create-quick-link). ## O que o destinatário vê A página hospedada mostra o nome da sua empresa, o logo e a cor de destaque, e oferece os métodos ativados: * **Ler QR code** em um notebook ou em um segundo dispositivo. A página atualiza o código automaticamente até o WhatsApp vincular. * **Inserir código** no próprio celular. O destinatário digita o número dele, recebe um código de uso único e o insere em **Conectar com número de telefone** no WhatsApp. Por padrão, celulares abrem no método de código de pareamento e notebooks no código QR; um método padrão salvo substitui essa escolha. O destinatário pode alternar entre os métodos permitidos antes de a conexão terminar. Antes de o pareamento começar, a página explica a entrega de histórico configurada e registra a escolha do destinatário. Depois que o WhatsApp vincula, a página pede a confirmação da conexão. Cancelar antes da confirmação desvincula o dispositivo de novo. Para a Meta Cloud API, a página continua mostrando o progresso da configuração depois do cadastro na Meta enquanto as [verificações de prontidão](#verificações-de-prontidão-da-meta-cloud-api) são executadas, e só pede a confirmação depois que o número inicia. Quando uma verificação falha, a página indica a etapa de recuperação. Enquanto a Meta não responde a uma verificação, a página informa que a configuração vai verificar de novo e mantém **Cancelar** disponível; ela não oferece o cadastro de novo. ## Acompanhar e concluir a conexão Use qualquer um destes caminhos para saber o resultado. **URLs de retorno.** Configure as URLs de sucesso e de falha nas configurações de QuickLink do projeto. Cada convite tira um snapshot desses destinos quando é criado. As solicitações de criação não podem substituí-los nem limpá-los. A confirmação usa a URL de sucesso. O cancelamento usa a URL de falha com `status=cancelled` e `reason=cancelled`; falhas de conexão usam `status=failed` e um motivo como `phone_mismatch` ou `connection_failed`. A página hospedada redireciona depois de exibir o aviso de falha. Depois de uma conexão pela Meta Cloud API ou Hybrid, a página hospedada informa que a Meta confirmou as verificações da configuração e espera o destinatário selecionar **Continuar** antes de abrir a URL de sucesso. As verificações não enviam mensagens, então envie e receba uma mensagem de teste antes de usar o número. Links que não podem ser resolvidos não conseguem fornecer uma URL de retorno confiável e continuam na página de link indisponível. Por exemplo: ```text theme={null} https://app.acme.example/whatsapp/connected?quicklinkId=ql_example&session=739182640518203&status=connected&historySync=true https://app.acme.example/whatsapp/failed?quicklinkId=ql_example&reason=cancelled&session=739182640518203&status=cancelled ``` Quando informado, o `externalId` do QuickLink é incluído na URL de retorno e na resposta da sessão resultante. Ele pode se repetir entre convites. A correlação com o cliente continua separada, em `externalCustomerId`. Trate a query string como uma indicação e confirme o estado da sessão com `GET /platform/sessions/{session}` ou com os webhooks de sessão. **Consulta de status.** `GET /messaging/quicklinks/{id}` retorna o status atual para quem criou o link: | Status | Significado | | - | - | | `pending` | O link existe e ainda não foi aberto. | | `opened` | O destinatário abriu a página; a confirmação do telefone pode ainda estar pendente. | | `linked` | Dispositivos vinculados: o WhatsApp informa que o dispositivo foi vinculado e o destinatário ainda não confirmou. Meta Cloud API: o número está conectado à Meta e ainda está sendo preparado para enviar. | | `connected` | O destinatário confirmou. `phone` contém o número conectado em E.164. Para a Meta Cloud API, todas as [verificações de prontidão](#verificações-de-prontidão-da-meta-cloud-api) passaram antes. | | `failed` | Não foi possível concluir a conexão. `errorCode` explica o motivo. | | `cancelled` | O destinatário ou quem criou o link o cancelou. | Um link expirado retorna `404`. ### Verificações de prontidão da Meta Cloud API Depois que a Meta aceita a entrega de eventos para a conta do WhatsApp Business, a Polymorfa verifica o número antes de iniciá-lo. O link fica `linked` enquanto as verificações são executadas. A primeira verificação que falha leva o link para `failed` com o próprio `errorCode`, e o número não inicia. O link só fica `connected` depois que todas as verificações passam e o destinatário confirma. | Verificação | Passa quando a Meta informa | `errorCode` quando falha | Recuperação | | - | - | - | - | | Acesso | O token de acesso salvo é válido, pertence ao app da Meta e concede `whatsapp_business_messaging` e `whatsapp_business_management` para esta conta. | `meta_credentials_invalid` | O proprietário da equipe confere as permissões do app no Meta Business Suite e depois cria um novo link. | | Registro do telefone | O status do número é `CONNECTED` na Cloud API. Um número `FLAGGED` falha na verificação de qualidade. | `meta_phone_not_registered` (status `BANNED`, `DELETED`, `DISCONNECTED`, `MIGRATED`, `RESTRICTED` ou `RATE_LIMITED`, ou outra plataforma) | O proprietário da conta confere o número no WhatsApp Manager e depois um novo link é criado. | | Inscrição no webhook | O app da Meta está inscrito na conta com a URL de retorno da Polymorfa. | `meta_webhook_not_subscribed` | O proprietário da equipe confere a inscrição do app no webhook e depois cria um novo link. | | Forma de pagamento | A conta do WhatsApp Business tem uma forma de pagamento. | `meta_payment_method_missing` | O proprietário da conta adiciona uma forma de pagamento no WhatsApp Manager, em **Overview**, e depois um novo link é criado. | | Qualidade | O número não está `FLAGGED` e a classificação de qualidade não é `RED`. Um número novo sem classificação passa. | `meta_quality_flagged` | O proprietário da conta confere a classificação de qualidade no WhatsApp Manager e, depois que a Meta remove a sinalização, um novo link é criado. | Quando a Meta não responde a uma verificação, por exemplo durante uma indisponibilidade da Meta, a verificação não passa nem falha. O link fica `linked` e `onboarding.errorCode` é `meta_readiness_unknown`. A Polymorfa verifica de novo a cada dois minutos e continua quando a Meta responde. Você pode cancelar o link enquanto ele espera. Se o link expirar antes, ele falha com `meta_readiness_unknown`. Um link de reautorização verifica o acesso, o registro do telefone e a inscrição no webhook. Ele não verifica a forma de pagamento nem a qualidade de um número que já está em uso. As verificações são executadas uma vez, durante a configuração. Depois disso, os envios do número retornam um erro específico quando a Meta informa um problema: [`whatsapp_authorization_required`](/api/errors#whatsapp-authorization-required), [`whatsapp_payment_method_required`](/api/errors#whatsapp-payment-method-required) ou [`whatsapp_number_not_registered`](/api/errors#whatsapp-number-not-registered). As verificações de credenciais continuam como descrito em [Verificar e renovar as credenciais da Meta Cloud API](#verificar-e-renovar-as-credenciais-da-meta-cloud-api). ## Cancelar um QuickLink `DELETE /messaging/quicklinks/{id}` invalida um link pendente. Para um link inicial de número real, uma resposta `202` significa que a limpeza do número foi solicitada. O número continua no seu projeto até a limpeza terminar; confira o status dele antes de criar um substituto. Cancelar um link complementar mantém o número existente. O Console não gera um substituto enquanto o link atual está ativo. Cancele o link primeiro ou espere até ele conectar ou falhar. Links conectados não podem ser cancelados; gerencie o número. Links criados no Console só podem ser consultados e cancelados pelo membro que os criou. ## Configurações salvas No Console, abra **Configurações → QuickLink** da equipe ou do projeto. Você pode: * ativar ou desativar os QuickLinks para esse escopo; * permitir que os destinatários substituam um número de telefone preenchido ou mantê-lo bloqueado; * escolher os métodos oferecidos e qual deles abre primeiro; * escrever o título, a descrição e a mensagem de sucesso que a pessoa lê; * adicionar um link de suporte e links de privacidade e de termos para a etapa de confirmação; * enviar um logo, reutilizar o logo da equipe ou o ícone do projeto e definir a cor de destaque, o tema, o formato dos cantos e o rodapé; * definir as URLs de retorno de sucesso e de falha do projeto e escolher o comportamento do histórico de conversas. As configurações do projeto substituem os padrões da equipe, e a prévia mostra a página hospedada como o destinatário a vê enquanto você digita. Os campos deixados vazios mantêm o texto padrão. Use [Get QuickLink settings](/api-reference/platform/quicklink/get-quick-link-settings) e [Update QuickLink settings](/api-reference/platform/quicklink/update-quick-link-settings) para gerenciar esses padrões a partir do seu backend. ## Pareamento direto Acesso de pareamento direto Se você precisa construir (build) a sua própria interface de pareamento, o acesso de pareamento direto precisa abranger o número antes de você chamar [Get QR code](/api-reference/messaging/pairing/get-qr-code) ou [Request a pairing code](/api-reference/messaging/pairing/request-pair-code). Sem esse acesso, esses métodos retornam `403`. Use o QuickLink. ## Próximos passos > **[Sessões](/pt-br/console/sessions)** > > Gerencie o número conectado depois que ele chega ao seu projeto. > **[Links de pareamento de clientes](/pt-br/guides/customers/pairing-links)** > > Atribua números conectados a clientes com links duráveis e revogáveis. > **[Webhooks](/api/webhooks)** > > Acompanhe o ciclo de vida da sessão resultante. > **[Tokens de cliente](/pt-br/console/client-tokens)** > > Credenciais seguras para o navegador, para mensagens, separadas do pareamento. ## Preferência de conexão `connectionPreference` e `connectionEnforcement` são separados dos `methods` de Dispositivos vinculados. As configurações salvas do projeto fornecem os padrões. Uma solicitação normal de criação de QuickLink pode substituir os campos seguros do convite em `settings`; o Console apresenta esses campos antes da geração. As configurações resolvidas são registradas em snapshot na emissão. O padrão é `cloud` com `prefer`. As configurações são copiadas para cada link quando ele é criado; editar as configurações salvas não altera os links existentes. | Preferência | Imposição | Experiência do destinatário | | - | - | - | | `cloud` | `prefer` | Cloud acima de Dispositivos vinculados, com cartões de altura 60/40 | | `linked` | `prefer` | Dispositivos vinculados acima de Cloud, com cartões de altura 60/40 | | `both` | `prefer` | Dois cartões do mesmo tamanho | | `cloud` | `force` | Abre diretamente o cadastro na Cloud | | `linked` | `force` | Abre diretamente o pareamento de dispositivo vinculado | Selecione um cartão de conexão e depois escolha **Continuar** para começar a conectar. O cartão preferido aparece primeiro e já vem selecionado. Alternar entre os tipos de conexão mantém fixos a altura do cartão e o rodapé de ações. Instruções mais longas rolam dentro do cartão. As duas visualizações de conexão colocam **Usar Meta Cloud API** ou **Usar dispositivos vinculados** no canto inferior esquerdo quando a troca é permitida, e **Cancelar** no canto inferior direito. As ações usam botões preenchidos, com um estilo secundário para a troca e um leve tom vermelho para Cancelar. O rodapé da página mostra **Powered by Polymorfa**. Os visitantes podem alternar entre os temas claro e escuro e selecionar inglês (ENG) ou português do Brasil (BR) pelos menus de tema e de idioma, só com ícones, abaixo do cartão à esquerda, com a atribuição à Polymorfa à direita. Essas escolhas não alteram a política de conexão do convite nem o texto personalizado de quem o criou. `both` não pode ser imposto. As opções opcionais de Cloud ficam ocultas quando o cadastro hospedado na Cloud não está disponível. Nesse caso, criar um link com Cloud imposta falha. A configuração da Meta Cloud API oferece **Continuar usando o app WhatsApp Business** para um número existente e elegível do app, ou **Usar o WhatsApp sem o app Business** para um número novo ou existente da Meta Cloud API. Os clientes conectam os próprios números e pagam a Meta diretamente pelas mensagens. ## Histórico com coexistência Configure uma inscrição de webhook do projeto para `history.sync`, `contact.sync` e `message.echo`. As configurações de QuickLink lembram você de configurar um destino. Ative o HMS separadamente se também quiser que a Polymorfa armazene as mensagens compatíveis. A sincronização do histórico nunca ativa o armazenamento automaticamente. Uma empresa pode recusar o compartilhamento do histórico no WhatsApp, inclusive quando a configuração de histórico do link está ativada. `history.sync` entrega a recusa da Meta, o progresso e os lotes de histórico. As cargas de histórico da Cloud contêm `kind: "history"` e `value`; o histórico de dispositivo vinculado mantém o formato de blocos compactados. `contact.sync` contém `kind: "contacts"` e `value`. `message.echo` contém `source: "whatsapp_business_app"` e `value`. Confirmar a conexão não espera a importação do histórico. Acompanhe o progresso pelos webhooks ou pelo status `onboarding` do link. A aceitação de uma solicitação de sincronização é separada da conclusão da importação. O HMS armazena os metadados das mensagens compatíveis, preserva o ID original, o horário e a direção da mensagem e aplica a própria política de retenção. Referências de mídia marcadas com `mediaStorage: "not_fetched"` não significam que os bytes da mídia foram armazenados. Os contatos avulsos são entregues por webhooks. Se `onboarding.errorCode` for `sync_status_unknown`, a Meta não confirmou uma solicitação de contatos ou de histórico. A conexão pode continuar ativa enquanto o status da importação é incerto. Confira os eventos de histórico recebidos e entre em contato com o suporte informando o ID do QuickLink antes de tentar outro cadastro. Não crie outro convite para tentar a importação novamente: a solicitação original pode já ter sido aceita. O fluxo de Dispositivos vinculados centraliza o código QR e oferece **Ou use seu número de telefone para entrar** logo abaixo quando os dois métodos são permitidos. Navegadores de celular começam pelo pareamento com número de telefone quando ele é permitido. Redimensionar uma janela no computador não muda o método inicial. Por padrão, o tema segue o dispositivo. Um tema salvo no projeto define a aparência inicial; os visitantes podem substituí-lo escolhendo Sistema, Claro ou Escuro. O idioma começa pelo primeiro idioma compatível do navegador do visitante, inglês ou português. Se nenhum dos dois aparecer, a página começa em inglês. Os visitantes podem trocar de idioma na página. Quando você informa `externalId`, os webhooks nativos de ciclo de vida `session.*` incluem essa referência junto com o nome da sessão. Ela não substitui o ID do evento nem concede acesso à sessão. Os clientes identificam a pessoa ou a empresa responsável pelos números. Eles não armazenam um número de telefone; informe qualquer telefone esperado no convite individual. `meta_registration_rejected` significa que a Meta recusou explicitamente o registro do número. Corrija a restrição de registro antes de iniciar outra tentativa de conexão. Um resultado de solicitação incerto continua pendente até poder ser reconciliado. `existing_cloud_registration_unverified` significa que a Meta não informou o número nem como conectado à Cloud API nem como pronto para um novo registro. A Polymorfa para antes de enviar um PIN de registro, então um PIN mantido pelo provedor atual do número não é substituído. O proprietário da conta resolve o registro e o PIN do número com esse provedor e depois cria outro convite. Quando você informa `prefillPhone`, a criação tenta verificar se o número está registrado no WhatsApp. Primeiro ela seleciona um número conectado que já observou exatamente esse telefone, depois um número conectado com o mesmo código de país e, por fim, qualquer número conectado. O cliente e a conversa selecionados nunca são expostos. Um número confirmado como não registrado retorna `400` com `phone_not_registered`. Se nenhum número conectado puder responder, o estado de registro continua desconhecido e o convite segue com as opções de conexão permitidas pelo projeto. A mesma regra vale quando o destinatário informa ou altera o número depois de abrir o link. Números de telefone inválidos continuam parando na etapa do telefone. A falta de nome ou foto de perfil não invalida um número registrado. Os convites de cliente aplicam a mesma resolução a `expectedPhone`. `cloud_start_failed` significa que o runner informou que a conexão pela Meta Cloud API não pôde ser iniciada. Corrija a restrição de conexão informada antes de emitir um novo convite. Consultar o convite com falha não tenta iniciar novamente. Os convites de cliente salvam essas configurações quando o convite é criado, antes de ser aberto. A identidade de telefone resolvida é salva com o convite; abrir o convite não substitui essa identidade pelo resultado de uma consulta posterior. Para um número preenchido e resolvido, o destinatário vê **Entrando como**, o número internacional formatado e o tipo de conta do WhatsApp deduzido em um único cartão de identidade. A Polymorfa não reutiliza o nome de contato salvo nem o acesso à foto de perfil de outro cliente. Quando não há um nome de exibição global do provedor, o cartão usa o número e um ícone de perfil neutro. **Não é você?** cancela o convite pela URL de retorno de falha salva nele. O número conectado precisa corresponder ao de um convite com número preenchido, inclusive quando o destinatário lê um código QR. Uma divergência faz a confirmação falhar e não conclui o convite. `meta_subscription_rejected` significa que a Meta recusou explicitamente a inscrição de webhook da WABA. Corrija as permissões do app ou a restrição de acesso à WABA antes de criar um novo convite. Um resultado de inscrição incerto continua pendente até poder ser reconciliado. Enquanto a inscrição está pendente, `onboarding.errorCode` é `meta_subscription_status_unknown` quando a Meta informa outra URL de retorno de webhook para o app da Polymorfa nessa WABA. A Polymorfa não sobrescreve essa URL. Ela verifica de novo a cada 10 minutos e continua a configuração quando a Meta informa a URL de retorno da Polymorfa. Peça ao proprietário da conta para conferir a inscrição do app no webhook ou cancele o convite para interromper. Se o convite expirar antes, ele falha com o mesmo código; crie um novo convite depois que o proprietário resolver a URL de retorno. Se a confirmação retornar um erro temporário, tente confirmar novamente enquanto o convite for válido. Uma nova tentativa não repete o onboarding já concluído. Se o convite tiver expirado, confira o número resultante antes de criar outro convite. Uma sincronização de contatos incerta não pode ser confirmada por um evento posterior de alteração de contato. Entre em contato com o suporte antes de tentar novamente. Repetir a sincronização única da Meta pode exigir que o proprietário da empresa desconecte a conexão pela Meta Cloud API e conclua o Embedded Signup de novo; isso interrompe essa conexão e nunca é automático. ### Parear pelo celular Depois que um código de pareamento é solicitado, navegadores de celular oferecem **Abrir WhatsApp**. Abra **Dispositivos conectados** no app dono do número e digite o código. Se o link abrir uma conversa ou outro app instalado, abra o app correto do WhatsApp manualmente. O código de pareamento nunca é incluído no link externo. Navegadores compatíveis com picture-in-picture também oferecem **Manter código visível**. Ele só abre quando você o seleciona. Se o navegador recusar a solicitação, copie o código e mude para o WhatsApp. O código flutuante fecha quando o painel de pareamento é removido ou quando o código muda. Você pode abrir um código recém-emitido mesmo que a solicitação de picture-in-picture anterior ainda esteja carregando. O suporte varia conforme o navegador e o sistema operacional. Se o cadastro na Meta atingir o tempo limite antes de retornar o resultado completo, confira o status da conexão e recarregue a página antes de iniciar outro cadastro. Trocar de método de conexão na mesma página não reinicia a janela de cadastro expirada. Novos convites criados depois que uma equipe perde o acesso ao app da Meta da própria equipe usam o app da Meta da Polymorfa disponível ou Dispositivos vinculados, conforme a política de conexão do projeto. Os convites existentes mantêm o app salvo neles. ## Configuração da sessão As escolhas de onboarding ficam fixas quando o link é emitido. As configurações contínuas da sessão herdam os padrões da plataforma, da equipe e do projeto, a menos que a sessão substitua um campo. Um padrão alterado atualiza as sessões que ainda o herdam. Consulte [Configuração da sessão](/pt-br/console/sessions#configuração) para atualizações e redefinições. Campos de configuração desconhecidos são rejeitados. Apresentação, links legais e URLs de retorno não podem ser definidos em um link individual. A configuração nunca concede acesso ao HMS nem substitui a decisão do destinatário sobre o histórico. ## Conexões simuladas Para um número de teste, inclua `configuration.testing`. Defina um país e a configuração inicial da simulação e depois liste os campos que o destinatário pode personalizar: ```json theme={null} { "projectId": "00000000-0000-4000-8000-000000000001", "configuration": { "testing": { "country": "BR", "configuration": { "profile": { "name": "Demo support" }, "accountType": "business", "replyBehavior": "echo", "failureScenario": "none" }, "editable": ["profile.name", "replyBehavior"] } } } ``` O acesso e as cotas de teste se aplicam de forma independente do onboarding de números reais. O destinatário vê que a conexão é simulada. A lista `editable` aceita no máximo três campos. Uma lista vazia mantém fixas todas as configurações de quem criou o link. A simulação não se conecta a contas reais do WhatsApp. ## Configuração da Meta por servidor confiável Crie um QuickLink primeiro. Confirme o telefone com `POST /quicklink/{token}/phone`. Se os dois tipos de conexão forem oferecidos, selecione a API oficial com `POST /quicklink/{token}/connection` e `{ "connection": "cloud" }`; quando Cloud é a única conexão permitida, ela é selecionada depois da confirmação do telefone. Em seguida, chame `POST /messaging/cloud-api/embedded-signup` com o `quicklinkId` para avançar a configuração da Meta Cloud API. Inclua `result` ao enviar o resultado do Embedded Signup. Para um convite inicial com modo de histórico `ask` ou `force_on`, primeiro registre a escolha do destinatário com `POST /quicklink/{token}/history` e `{ "historySync": true | false }`. Um QuickLink que adiciona a API oficial a um número existente reutiliza a decisão de histórico desse número; o endpoint de histórico dele não fica disponível. O resultado do cadastro na Meta não registra esse consentimento; avançar enquanto ele está pendente retorna `409`. Para solicitar o histórico depois que o destinatário aceitar, defina também `result.historySync` como `true` na solicitação de Embedded Signup. Um indicador de resultado ausente ou falso não solicita o histórico. A chamada usa a sessão reservada do convite e as configurações salvas do app da Meta; ela não pode escolher outra sessão nem fornecer credenciais de app. Tentativas exclusivas do Console e números de teste não podem usar esse endpoint. Quem chama precisa de `quicklink:manage` e de acesso ao projeto do convite. Acompanhe a etapa do onboarding com `GET /messaging/quicklinks/{id}`. Para um QuickLink de conexão única, chame `POST /quicklink/{token}/confirm` quando a etapa chegar a `connected`. Para um Hybrid Link elegível, conclua o pareamento por Dispositivos vinculados do mesmo número e espere `hybridPhase: "ready"` antes de confirmar. A confirmação conclui o convite, conclui qualquer pareamento de cliente vinculado e retorna a URL de redirecionamento de sucesso. A resposta do Embedded Signup sozinha não confirma o QuickLink. ## Fixtures de histórico de teste Envie mensagens de fixture com `POST /messaging/testing/{projectId}/history-fixtures`. O corpo contém `messages`, cada uma com `id`, `senderPhone`, `text`, `timestamp` e `fromMe`. Envie no máximo 100 mensagens em uma solicitação de até 512 KiB. Os IDs das mensagens precisam ser únicos e os remetentes precisam pertencer ao pool de números de teste do projeto. É preciso ter acesso de teste e `sandbox:write`. Passe o `fixtureId` retornado como `configuration.testing.configuration.historyFixtureId` ao criar um QuickLink de teste. As fixtures fornecem histórico simulado para a consulta de mensagens; enviar uma fixture não publica eventos de mensagem ao vivo nem ativa o HMS. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.