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.

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?

• Sim. Se o número estiver em uso no aplicativo WhatsApp Business, geralmente é possível migrá-lo para a Cloud API sem excluir a conta do aplicativo. Veja a documentação da Meta sobre onboarding por Coexistence.

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 → External Apps → WhatsApp → clique no botão Conectar WhatsApp e siga o pop-up da Meta:

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, siga o onboarding por Coexistence da Meta.
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 recebe SMS/ligação e se não está preso em outro fluxo de registro que a Meta não permita coexistir. Se o número estiver no aplicativo Business, tente o onboarding por Coexistence.

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 External Apps 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.

O aviso desaparece automaticamente assim que uma resposta é enviada com sucesso novamente.

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.

Se nos conectarmos por Coexistence, podemos desconectar mais tarde?

• Sim, a qualquer momento. No aplicativo WhatsApp Business, acesse Configurações → Conta → Plataforma empresarial → Desconectar.
• O número continua ativo no aplicativo WhatsApp Business, e seus contatos e o histórico de conversas existente não são afetados.
• O acesso da Quickchat AI à API termina imediatamente.
• Você também pode pausar a integração sem desconectá-la. Basta interromper as mensagens de saída da 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: