Pular para o conteúdo principal
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. 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. 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. checkedAt é o horário da última validação concluída. status é: 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. 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}. 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. Você pode criar o mesmo link hospedado em três lugares.
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 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.

​
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: 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:
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.

​
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 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:
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: 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. 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, whatsapp_payment_method_required ou whatsapp_number_not_registered. As verificações de credenciais continuam como descrito em Verificar e renovar as credenciais da Meta Cloud API. 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 e Update QuickLink 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 ou Request a pairing code. Sem esse acesso, esses métodos retornam 403. Use o QuickLink.

​
Próximos passos

Sessões

Gerencie o número conectado depois que ele chega ao seu projeto.

Links de pareamento de clientes

Atribua números conectados a clientes com links duráveis e revogáveis.

Webhooks

Acompanhe o ciclo de vida da sessão resultante.

Tokens de cliente

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. 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 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:
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.