WhatsApp

Este guia mostra como integrar seu Quickchat AI Agent ao WhatsApp. O processo é dividido em 2 etapas simples:

• Etapa 0 – Pré-requisitos
• Etapa 1 – Conectar WhatsApp

Se tiver problemas durante a integração, consulte Solução de problemas e FAQ ou entre em contato conosco.

Ferramentas opcionais de configuração

• Verificar pré-requisitos do WhatsApp. Revise os dados declarados do número e do provedor com base nos requisitos documentados. Não acessa nem conecta contas do WhatsApp.

• Verificar uma janela de serviço do WhatsApp. Verifique a janela de 24 horas com os horários de entrada e resposta fornecidos, incluindo o deslocamento de fuso horário. Não verifica modelos, consentimento ou permissões da conta, nem envia mensagens.

• Estimar custos de uso. Calcule os créditos de modelos do Quickchat AI e um total separado das taxas fornecidas. Não consulta tarifas de provedores, soma créditos a dinheiro nem verifica sua conta.

Os formulários estão em inglês.

Assista ao vídeo

Play

Etapa 0 – Pré-requisitos

A. Número de telefone comercial

Defina qual número de telefone você usará no WhatsApp. Leia mais na documentação do WhatsApp ou verifique as FAQs abaixo:

Qual número pode ser usado na WhatsApp Cloud API?

• Use um número comercial dedicado que possa receber SMS ou chamadas de voz para verificação.
• O número precisa ser válido, de sua propriedade e ter código do país e da área.

Posso usar um número que já esteja no WhatsApp Messenger?

• Não. Você pode continuar usando-o para chamadas e SMS, mas não no WhatsApp Messenger.
• Se o número já estiver no Messenger, remova-o primeiro. Lembre-se de fazer backup do histórico de conversas.
• Números banidos precisam ser desbloqueados antes do registro.

Posso usar um número que já está no aplicativo WhatsApp Business?

• O fluxo de conexão atual da Quickchat AI não oferece um caminho verificado de Coexistence para um número já usado no aplicativo WhatsApp Business. A Meta explica como funciona a Coexistence nas integrações compatíveis em seu guia de onboarding do aplicativo WhatsApp Business.
• Se você precisa manter seu número atual, sua conta no aplicativo WhatsApp Business e seu histórico de conversas, envie um e-mail para support@quickchat.ai antes de continuar. Não exclua nem desconecte a conta do aplicativo WhatsApp Business, nem migre o número, como tentativa de solucionar o problema.

Posso usar um novo número?

• Sim. Se não quiser usar seu número atual, adquira um novo número (SIM físico ou número virtual). Serviços como Hushed vendem números virtuais.

B. Informações da empresa

Tenha os seguintes dados em mãos (serão usados no fluxo de integração da Meta):

• Nome da empresa
• Site da empresa
• Categoria da empresa
• Descrição da empresa

Cuidado

Mesmo que pareçam opcionais, preencha todos os campos com precisão. Informações incorretas ou ausentes podem atrasar a aprovação ou gerar restrições.

Etapa 1 – Conectar WhatsApp

Abra o Quickchat AI App → Aplicativos externos → WhatsApp → clique no botão Conectar WhatsApp e siga o pop-up da Meta:

Você também pode começar pelo ChatGPT, Claude ou outro aplicativo de AI conectado: peça um link para conectar este Agent ao WhatsApp. O link é válido por 10 minutos e funciona uma única vez, apenas para a conta Quickchat que o solicitou. Abra-o em um navegador em que você tenha feito login nessa conta, siga a configuração da Meta e conclua qualquer seleção de conta ou número de telefone quando o Quickchat reabrir. Depois, peça ao seu aplicativo de AI para verificar a configuração e envie uma mensagem real pelo WhatsApp para confirmar que a resposta da AI chega. Teste cada número ativo se conectar mais de um. Você aprova o acesso da Meta no navegador, sem compartilhar tokens no chat.

1. Faça login na sua conta Meta (Facebook).
2. Revise as permissões que você compartilhará com o Quickchat AI (acesso à conta do WhatsApp Business e acesso ao portfólio empresarial) e continue.
3. Forneça dados empresariais corretos (Business Portfolio, Business Name, Business Website, país etc.).
4. Crie ou selecione sua conta WhatsApp Business.
5. Escolha um nome de exibição e uma categoria para o WhatsApp Business.
6. Adicione seu número comercial e verifique-o via SMS/ligação, conforme solicitado.
7. Clique em Confirm para conceder os acessos necessários ao Quickchat AI.
8. Quando a Meta confirmar que a configuração foi concluída, clique em Finish. O pop-up exibirá uma confirmação do Quickchat AI informando que a conta do WhatsApp foi conectada, e a janela será fechada automaticamente.

Se a Meta conceder ao Quickchat AI acesso a mais de uma conta, o painel do WhatsApp exibirá Escolha a sua conta do WhatsApp Business em vez de conectar uma conta imediatamente. Escolha a conta que o seu AI Agent deve usar para responder e clique em Usar esta conta. Se você estiver reconectando, a configuração atual do WhatsApp permanecerá inalterada até que você confirme.

De volta ao Quickchat AI App, o painel do WhatsApp mostra Concluir configuração até que uma troca de mensagens bem-sucedida seja verificada no seu próprio número comercial. Se o painel não tiver sido atualizado após cerca de 30 segundos, clique no ícone de atualizar.

Conectar-se à Meta e receber uma mensagem são apenas parte da configuração. O painel mostra o próximo passo para cada número ativado:

• Aguardando a sua primeira mensagem: envie uma mensagem do WhatsApp para o número exibido a partir de outro telefone e depois clique em Atualizar. Certifique-se de enviar a mensagem para o número comercial que seus clientes usarão.
• Aguardando a entrega da resposta da AI: o Quickchat recebeu sua mensagem, mas o WhatsApp ainda não confirmou a entrega da resposta da AI. Confira se a resposta chegou ao outro telefone. Se não chegou, verifique seus créditos AI e os avisos no painel e depois envie outra mensagem de teste.
• Resposta da AI entregue: o WhatsApp confirmou que a resposta da AI a uma mensagem recebida foi entregue neste número comercial.
• A verificação precisa de atenção: resolva os avisos de conexão, mantenha o número desejado ativado e envie uma nova mensagem de teste.
• Nome de exibição: cada número listado mais abaixo no painel traz o status do seu nome de exibição na Meta (Aprovado, Em análise, Recusado, Expirado ou Sem nome de exibição). Uma análise em andamento não exige nada de você e costuma terminar em alguns dias. Se o nome de exibição foi recusado, expirou ou está faltando, envie um novo no WhatsApp Manager.
• Número de teste da Meta: números +1 555 atribuídos pela Meta e números de sandbox não verificam a ativação no seu número comercial. Adicione seu próprio número no WhatsApp Manager, ative-o no Quickchat e depois teste esse número.

O painel mostra Em funcionamento quando cada número comercial ativado tem uma troca de mensagens verificada e as verificações de conexão estão em ordem. Se você ativar vários números comerciais, teste cada um. Uma troca bem-sucedida com um número de teste, um template enviado ou um aviso sobre o limite de mensagens não concluem essa verificação.

Dica

Mantenha a integração ativada durante os testes. Envie uma mensagem de outro telefone para cada número comercial que pretende usar, confirme que a resposta da AI chegou e clique em Atualizar. A conversa também deve aparecer na caixa de entrada do Quickchat AI App. Uma conexão existente pode solicitar uma nova troca de teste para verificar a entrega; ela pode continuar recebendo e respondendo a mensagens enquanto você conclui essa etapa.

Se ainda houver etapas de onboarding da Meta pendentes, conclua-as em Setup guidance no WhatsApp Manager. O Quickchat AI também envia um lembrete por e-mail ao proprietário da conta quando há etapas de configuração da Meta inacabadas.

Troubleshooting & FAQs

Como funciona a precificação da WhatsApp Business API?

• Respostas a solicitações iniciadas pelo usuário (inbound) são tratadas como Service messages pelo WhatsApp. Elas permitem atender clientes via agente humano ou bot conversacional.
• Quando um usuário envia mensagem para a empresa, abre-se uma janela de atendimento de 24 horas em que é possível responder com mensagens de serviço sem custo. Essa janela reinicia a cada mensagem do usuário.
• Após 24 horas, é obrigatório usar Message Templates aprovados (Marketing, Utility, Authentication etc.) e pagar por mensagem conforme as tarifas da plataforma WhatsApp Business.
• As conversas são classificadas e faturadas pela Meta. Garanta que sua conta WhatsApp Business tenha um método de pagamento válido para mensagens iniciadas pela empresa/templated.

O botão Conectar WhatsApp não funciona. O pop-up da Meta não aparece.

• Se o navegador bloquear o pop-up, permita pop-ups para o Quickchat AI App e clique em Tentar novamente. Você também pode clicar em Continuar no Meta nesta aba para concluir a mesma configuração sem um pop-up.

A Quickchat não conseguiu confirmar a conexão com o WhatsApp

A Quickchat mostra esta mensagem de recuperação quando a janela da Meta não retorna nenhum resultado e ainda não consegue verificar a conexão. Isso não significa que a Meta não tenha feito alterações.

1. Confirme que você é administrador da empresa na Meta que possui a conta do WhatsApp Business. Caso não seja, peça a um administrador para conectá-la usando a conta dele no Facebook.
2. Clique em Tentar novamente. Se um bloqueador interferir na janela da Meta, use uma janela privada com as extensões desativadas ou clique em Continuar no Meta nesta aba.
3. Se o número estiver ativo no WhatsApp Messenger, remova-o primeiro desse aplicativo ou use outro número. Se estiver ativo no aplicativo WhatsApp Business, pare aqui e envie um e-mail para support@quickchat.ai antes de continuar. O fluxo de conexão atual da Quickchat AI não oferece um caminho verificado de Coexistence. Não exclua nem desconecte a conta do aplicativo WhatsApp Business, nem migre o número, para tentar resolver essa mensagem.
4. Se a conta do WhatsApp Business usa Aircall, Twilio, 360dialog, MessageBird ou outro provedor, adicione a Quickchat AI como parceira no Meta Business Settings:
   1. Abra o Meta Business Settings e acesse Contas → Contas do WhatsApp.
   2. Selecione a conta do WhatsApp Business, abra Parceiros e clique em Adicionar parceiros.
   3. Insira o Business ID da Quickchat AI: 270696274483463.
   4. Conceda a permissão Gerenciar contas do WhatsApp, volte para a Quickchat AI e atualize o status.

Desconecte o outro provedor somente se a Meta não permitir ambos os parceiros nessa conta. Se tiver dúvidas, entre em contato com o suporte antes de desconectar um provedor de mensagens ativo.

A verificação do número falhou.

• Confira se o número pode receber SMS ou chamadas de voz.
• Uma mensagem genérica Ineligible ou o texto de ajuda This number can’t be shared with this app não permite determinar a causa nem confirmar se os requisitos de Coexistence da Meta foram atendidos. Envie um e-mail para support@quickchat.ai com a mensagem exata e a etapa em que ela apareceu.
• Se o número estiver em uso no aplicativo WhatsApp Business e você precisar manter essa conta e seu histórico, entre em contato com o suporte antes de continuar. Não exclua nem desconecte a conta, nem migre o número, para tentar eliminar o erro.

Conectei a conta errada.

• Reconectar mantém a conta que já está conectada. Para mover o AI Agent para outra conta do WhatsApp Business, clique em Desconectar no painel do WhatsApp, depois novamente em Conectar WhatsApp, e escolha a conta correta do Meta Business e a conta certa do WhatsApp na janela da Meta.

Não conseguimos identificar qual conta do WhatsApp Business conectar

• Seu login da Meta tem várias contas do WhatsApp Business com números de telefone e o Quickchat não conseguiu identificar qual você queria. Escreva para support@quickchat.ai informando o número que você quer conectar e nós concluiremos a configuração para você.

As mensagens não aparecem na caixa de entrada do Quickchat AI.

• Confirme se o pop-up exibiu o aviso final “WhatsApp account connected!”.
• Verifique se você vinculou a conta do WhatsApp correta e selecionou o AI Agent certo.
• O cartão Aguardando a sua primeira mensagem indica o número em que o seu AI Agent responde. Confirme que você enviou a mensagem exatamente para esse número e que ele está ativado no painel, depois clique em Atualizar.
• Ao enviar mensagens depois de 24 horas sem resposta do usuário, use templates aprovados e confirme se há um método de pagamento ativo no WhatsApp Manager.

As respostas do WhatsApp do meu AI estão a falhar ao enviar.

Se as respostas do seu AI não puderem ser entregues, o Quickchat AI exibe um aviso “As respostas do WhatsApp estão a falhar” no painel do WhatsApp em Aplicativos externos e uma notificação no seu dashboard. As causas e soluções mais comuns:

• Nome de exibição não aprovado em um número de teste da Meta: A Meta retém as respostas de um número +1 555 atribuído pela Meta até que o nome de exibição seja aprovado. O alerta do nome de exibição no painel fica vermelho e indica o número. Aguarde o fim da análise (costuma levar alguns dias) ou, se foi recusado, envie um novo nome de exibição no WhatsApp Manager e depois envie uma mensagem de teste. Um nome de exibição ainda em análise no seu próprio número não bloqueia as respostas por si só; o painel o mostra como uma observação.
• Conexão expirada ou revogada: sua conexão do WhatsApp já não é válida. Abra o painel do WhatsApp e clique em Reconectar para retomar o envio de respostas.
• Número restrito: A Meta restringiu o seu número de WhatsApp (qualidade ou políticas). Verifique o estado no WhatsApp Manager para restaurar o envio.
• Conta empresarial bloqueada (erro 131031): a Meta bloqueou as respostas da conta do WhatsApp Business. O erro de entrega na caixa de entrada e o painel do WhatsApp explicam a restrição. Abra o Business Support Home, selecione a conta do WhatsApp e a violação e solicite uma análise: a Meta só remove um bloqueio de conta por meio dessa análise. Reconectar o Quickchat não remove a restrição.

Os demais avisos desaparecem automaticamente assim que uma resposta é enviada com sucesso novamente. Um alerta de bloqueio da conta continua visível até que uma nova mensagem real de um visitante receba uma resposta da AI totalmente entregue, porque a Meta pode aceitar uma resposta e mesmo assim não entregá-la. Se apenas números de teste da Meta (+1 555) estiverem ativos, a próxima resposta da AI enviada com sucesso remove o alerta. A Support AI também pode explicar uma falha recente de bloqueio da conta registrada no histórico, mas os registros anteriores não comprovam que a conta continua bloqueada.

Templates ou mensagens iniciadas pela empresa falham.

• Garanta que seus Message Templates estejam aprovados e que exista um método de pagamento ativo no WhatsApp Manager.
• Novos remetentes começam com limites de envio que aumentam conforme a qualidade e a verificação. Se atingir um limite, consulte o guia da Meta sobre Messaging Limits.
• Acompanhe os limites e a classificação de qualidade no WhatsApp Manager caso as entregas sejam reduzidas.

Como criar seu próprio link do WhatsApp e botão “Conversar no WhatsApp”?

• Siga este tutorial do WhatsApp.
• Ou baixe os botões oficiais de marca do WhatsApp e utilize um destes scripts em linha:

<!-- Botão de WhatsApp embutido -->
<!-- Atualize WHATSAPP_PHONE_NUMBER e o nome/caminho do arquivo conforme necessário -->
<a
  aria-label="Conversar no WhatsApp"
  href="https://wa.me/WHATSAPP_PHONE_NUMBER"
  target="_blank"
  rel="noopener noreferrer"
>
  <img
    alt="Conversar no WhatsApp"
    src="WhatsAppButtonGreenLarge.svg"
    style="
      width: 200px;
      height: auto;
      cursor: pointer;
      border-radius: 12px;
    "
  />
</a>

ou

<!-- Botão flutuante do WhatsApp -->
<!-- Atualize WHATSAPP_PHONE_NUMBER e o nome/caminho do arquivo conforme necessário -->
<a
  aria-label="Conversar no WhatsApp"
  href="https://wa.me/WHATSAPP_PHONE_NUMBER"
  target="_blank"
  rel="noopener noreferrer"
  style="position: fixed; right: 20px; bottom: 20px; z-index: 9999"
>
  <img
    alt="Conversar no WhatsApp"
    src="WhatsAppButtonGreenLarge.svg"
    style="
      width: 200px;
      height: auto;
      cursor: pointer;
      border-radius: 12px;
      box-shadow: rgba(0, 0, 0, 0.5) 0px 5px 15px 0px;
      transition: all 0.3s ease;
    "
    onmouseover="this.style.transform = 'scale(1.05)'"
    onmouseout="this.style.transform = 'scale(1)'"
  />
</a>

Como gerar seu próprio código QR do WhatsApp?

• Acesse o WhatsApp Manager → Números de telefone → selecione seu número comercial → Links de mensagem → Criar link de mensagem.
• Alternativamente, você pode gerar no app móvel WhatsApp Business. Siga este tutorial do WhatsApp.

Devo desconectar minha conta do aplicativo WhatsApp Business para corrigir a configuração?

• Não. Não exclua nem desconecte sua conta do aplicativo WhatsApp Business, nem migre o número dela, como tentativa de solucionar problemas. O fluxo de conexão atual da Quickchat AI não oferece um caminho verificado de Coexistence que preserve a configuração atual do seu aplicativo e seu histórico.
• Envie um e-mail para support@quickchat.ai antes de alterar uma conta ativa do aplicativo WhatsApp Business. O guia de onboarding do aplicativo WhatsApp Business da Meta descreve a Coexistence para integrações compatíveis, mas não confirma a disponibilidade para sua configuração na Quickchat AI.

Que acesso a Quickchat AI obtém à nossa conta do WhatsApp Business?

• Acesso restrito à API, não propriedade da conta. Sua conta do WhatsApp Business (WABA) fica no seu próprio Meta Business Manager. No modelo WABA Sharing da Meta, você possui os ativos, e a Quickchat AI é adicionada como uma parceira cujo acesso pode ser revogado a qualquer momento no Business Manager.
• Podemos enviar e receber mensagens pela Cloud API e receber eventos de mensagens via webhook enquanto a integração estiver ativa.
• Não podemos encerrar, transferir ou alterar a marca da sua conta, modificar o faturamento nem remover seus administradores.

Precisa de ajuda?

Converse com o Quickchat Support AI no WhatsApp:
📱 +1 302-405-9992 — Iniciar chat

Ou escaneie o QR code: