# Integra com WhatsApp

> Você conecta o WhatsApp em Configurações, na área Integrações, por QR code (Conexão padrão) ou pela WhatsApp Cloud API da Meta, com um token e dois IDs. Conectado, o número envia e recebe mensagens no Atendimento da IDX e, se você ativar, cadastra os novos contatos como leads no CRM.

Publicado em 29 de outubro de 2026. Endereço: https://idxbr.com/blog/conectar-whatsapp

## Pontos principais

- A Conexão padrão usa QR code e exige a conta verificada na IDX
- A WhatsApp Cloud API pede token, ID do número de telefone e ID da conta do WhatsApp Business
- Na Cloud API, depois de 24 horas sem mensagem do cliente, só sai modelo aprovado pela Meta
- Com Contatos no CRM ativo, quem manda mensagem vira lead no funil de entrada
- O Atendimento faz parte dos planos Profissional e Avançado

## O que a integração com o WhatsApp faz na IDX

A integração leva as conversas do WhatsApp para o Atendimento da IDX, onde a equipe envia e recebe mensagens sem sair da plataforma. Cada conversa fica ligada ao contato e, quando o contato tem lead, ao lead e ao funil dele no CRM.

A integração tem dois recursos, com estes nomes na tela:

- **Conversas na IDX**: enviar e receber mensagens pela plataforma
- **Contatos no CRM**: com o recebimento ativado, os novos contatos seguem para o fluxo de entrada configurado

Cada contato tem uma conversa por número conectado. Se o mesmo cliente escrever de novo, a mensagem entra na conversa que já existe, em vez de abrir outra.

Veja o que a equipe faz depois de conectar em [como aceitar e atender leads no Atendimento](/blog/aceitar-e-atender-leads).

## Qual conexão escolher: padrão ou Cloud API

A diferença está em como o número se liga à IDX e no que a Meta permite enviar. A tabela resume o que muda.

| Item                   | Conexão padrão                  | WhatsApp Cloud API                                |
| ---------------------- | ------------------------------- | ------------------------------------------------- |
| Como conecta           | Lendo um QR code no celular     | Com token e dois IDs de um app da Meta            |
| Pré-requisito na IDX   | Conta verificada                | Só a permissão de gerenciar o atendimento         |
| Mensagem livre         | A qualquer momento              | Até 24 horas depois da última mensagem do cliente |
| Fora da janela         | Não existe janela               | Só modelo de mensagem aprovado pela Meta          |
| Áudio gravado na IDX   | Convertido em MP3 antes de sair | Enviado como foi gravado                          |
| Ligações pelo WhatsApp | Só na conexão por QR code nova  | Não                                               |

A própria tela descreve a Conexão padrão como "prática e econômica, mas pode ter limitações conforme as regras do WhatsApp".

Ligações só funcionam nas conexões por QR code feitas pelo provedor novo. Nas outras, o botão de ligar fica desativado e a conversa mostra "Ligações só estão disponíveis na conexão por QR Code nova."

## O que você precisa ter antes de conectar

Os requisitos dependem do tipo de conexão. Em qualquer caso, quem conecta precisa da permissão de gerenciar o atendimento. Sem ela, o cartão do WhatsApp mostra "Conectar e desconectar o WhatsApp exige a permissão de gerenciar o atendimento." e não mostra o botão.

### Na Conexão padrão

- O celular com o WhatsApp do número que vai atender, para ler o QR code
- A conta da IDX verificada. Sem a verificação, o lugar do QR code mostra "A conexão padrão fica disponível depois que a conta é verificada." e o botão **Verificar conta**
- Um número de trabalho: a tela recomenda usar um número profissional

### Na WhatsApp Cloud API

O formulário pede "os dados do app da Meta com acesso à API do WhatsApp Business". Do lado da Meta, você precisa ter:

- Um app da Meta com acesso à API do WhatsApp Business
- Uma conta do WhatsApp Business com o número cadastrado nela
- O token de acesso desse app
- Os modelos de mensagem aprovados na conta, para iniciar ou retomar conversas fora da janela de 24 horas

A IDX só lista modelos com status aprovado. Ela lê esses modelos direto da sua conta do WhatsApp Business, pelo ID que você informa.

## Os campos da WhatsApp Cloud API, um por um

A aba **WhatsApp Cloud API** tem três campos, todos obrigatórios. A tela confere o formato de cada um antes de enviar.

| Campo                                | O que é                                          | O que a IDX recusa                                    |
| ------------------------------------ | ------------------------------------------------ | ----------------------------------------------------- |
| **Token**                            | O token de acesso do app da Meta                 | Campo vazio ou token com espaço no meio               |
| **ID do número de telefone**         | O identificador do número na Meta                | Qualquer coisa além de dígitos, ou menos de 5 dígitos |
| **ID da conta do WhatsApp Business** | O identificador da conta, de onde vêm os modelos | Qualquer coisa além de dígitos, ou menos de 5 dígitos |

As mensagens de erro dizem o que corrigir:

- "Informe o token de acesso."
- "O token não tem espaços. Copie de novo no painel da Meta."
- "Use só os números do ID do número de telefone, como aparece no painel da Meta."
- "Use só os números do ID da conta do WhatsApp Business, como aparece no painel da Meta."

Espaços antes, depois ou no meio dos IDs são removidos sozinhos. O token fica mascarado enquanto você digita, e o navegador não oferece senhas salvas nesses campos.

## Como conectar pela Conexão padrão

Você conecta por QR code na área de Integrações. Se o Atendimento estiver sem número, o botão **Conectar número** da tela do Atendimento abre o mesmo lugar.

1. Abra o menu da conta, no pé da barra lateral, e clique em **Configurações**.
2. Clique em **Integrações** e abra o cartão do **WhatsApp**.
3. Clique em **Conectar**.
4. Na aba **Conexão padrão**, clique em **Gerar QR code**.
5. No celular, abra o WhatsApp do número, toque em **Aparelhos conectados** e leia o QR code.
6. Espere a mensagem **WhatsApp conectado**.

[Vídeo: Como conectar pela Conexão padrão](https://idxbr.com/videos/blog/conectar-whatsapp.mp4)

![Diálogo Conectar WhatsApp com a aba Conexão padrão selecionada e o botão Gerar QR code sobre o quadro do QR](https://idx-main-prod-files.s3.us-east-1.amazonaws.com/docs/lp-blog-conectar-whatsapp-conexao-padrao.jpg 'O QR code só é gerado quando você clica no botão')

### O que o quadro do QR code mostra em cada momento

O QR code só é gerado quando você pede. O quadro muda de estado assim:

| Estado              | O que aparece                                                                           |
| ------------------- | --------------------------------------------------------------------------------------- |
| Antes de gerar      | Um desenho desfocado com **Gerar QR code** e "O QR code é gerado só quando você pedir." |
| Gerando             | O botão carregando e "Gerando o QR code."                                               |
| Esperando a leitura | O QR code nítido e a instrução de ler em **Aparelhos conectados**                       |
| Vencido             | "O QR code venceu. Gere um novo para continuar." e **Gerar novo QR code**               |
| Erro                | A mensagem do erro e **Tentar de novo**                                                 |
| Conectado           | "Número conectado. As mensagens chegam ao Atendimento da IDX."                          |

O QR code vale por cerca de 40 segundos. O desenho desfocado não é um QR de verdade e nenhum leitor consegue lê-lo.

Ao conectar, você confirma os **Termos de Uso** e a **Política de Privacidade**, com links logo abaixo do quadro.

## Como conectar pela WhatsApp Cloud API

Você conecta pela Cloud API no mesmo diálogo, em outra aba.

1. Em **Configurações**, abra **Integrações** e o cartão do **WhatsApp**.
2. Clique em **Conectar** e escolha a aba **WhatsApp Cloud API**.
3. Preencha **Token**, **ID do número de telefone** e **ID da conta do WhatsApp Business**.
4. Clique em **Conectar** e espere a mensagem **WhatsApp Cloud API conectado**.

Depois de conectado, a aba mostra "Conectado pela API oficial da Meta. O token fica guardado na IDX e não é exibido." e o número conectado. Para reconectar, você informa o token outra vez.

Se a tela recusar algum campo, o erro aparece embaixo dele. Outras falhas aparecem num aviso.

## Como o membro com número próprio conecta o WhatsApp dele

O membro que pode gerenciar o atendimento, mas não as configurações, conecta pelo Atendimento. Ele não passa pela área de Integrações. Se o cargo dele tem a opção **WhatsApp próprio**, em Membros, o QR code conecta o número dele.

1. Abra **Atendimento**.
2. Clique em **Conectar número**.
3. No painel **Integrar com WhatsApp**, escolha **Conexão Padrão** e clique em **Gerar QR Code**.
4. Leia o QR code com o WhatsApp do celular.

A conexão pela Cloud API é feita por quem administra a conta, na área de Integrações.

Quem não pode conectar vê, no lugar do botão, "Peça a quem administra a conta para conectar o WhatsApp da empresa."

## O que muda com a janela de 24 horas

Na Cloud API, passadas 24 horas da última mensagem do cliente, a Meta só aceita modelo de mensagem aprovado. A IDX mostra isso na conversa, em vez de deixar o envio falhar.

### Como a janela abre e renova

A janela abre quando o cliente manda uma mensagem e renova a cada mensagem nova dele. A sua resposta não renova a janela. Uma conversa que você inicia sem o cliente ter escrito começa com a janela fechada.

### O que a conversa mostra com a janela fechada

O campo de texto fica bloqueado com o aviso "Envie um template para reiniciar a conversa". O botão ao lado vira **Iniciar conversa**. Com a janela aberta, o mesmo botão se chama **Templates** e permite enviar um modelo a qualquer momento.

### Como enviar um modelo

1. Clique em **Iniciar conversa** (ou **Templates**).
2. No painel **Iniciar conversa no WhatsApp**, escolha o modelo em **Selecionar Template**.
3. Preencha cada **Parâmetro** que o modelo pede. Se o cabeçalho do modelo tiver imagem, vídeo ou documento, informe o endereço do arquivo, começando por http ou https.
4. Confira o texto em **Preview da Mensagem**.
5. Clique em **Enviar**.

Sem todos os parâmetros, a IDX avisa "Preencha todos os parâmetros obrigatórios". Se a conta ainda não tem modelos aprovados, o painel mostra "Você ainda não tem templates" e o botão **Criar template**, que abre a Meta.

> [!IMPORTANTE] Só na Cloud API
> A janela de 24 horas não vale para a Conexão padrão.

## Como ligar o recebimento de contatos no CRM

O recebimento decide se quem escreve para o número vira lead. A chave fica no próprio cartão do WhatsApp, no recurso **Contatos no CRM**.

![Cartão do WhatsApp em Integrações, com os recursos Conversas na IDX e Contatos no CRM e a chave do recebimento ligada](https://idx-main-prod-files.s3.us-east-1.amazonaws.com/docs/lp-blog-conectar-whatsapp-integracao-whatsapp.jpg 'A chave de Contatos no CRM fica salva mesmo com o número desconectado')

| Situação                       | O que acontece com quem escreve                                                  |
| ------------------------------ | -------------------------------------------------------------------------------- |
| Chave ligada, contato novo     | Vira lead na primeira coluna de entrada do funil de entrada, com origem WhatsApp |
| Chave ligada, contato sem nome | O lead nasce com o nome "Lead WhatsApp"                                          |
| Contato que já tem lead        | A conversa vai para o lead dele. Nenhum lead novo é criado                       |
| Chave desligada                | A conversa aparece no Atendimento sem lead, com a etapa "Primeiro Contato"       |
| Contato bloqueado              | A mensagem é ignorada                                                            |

Ao mudar a chave, a IDX confirma com **Recebimento no CRM ativado** ou **Recebimento no CRM desativado**. Sem número conectado, a chave fica bloqueada com "Conecte um número para ativar o recebimento no CRM." Se o número cair com a chave ligada, a IDX mantém a escolha e avisa "Preferência salva. O recebimento depende da conexão do WhatsApp."

Com a chave desligada, você ainda cria o lead pela própria conversa, no botão **Criar lead** do painel **Opções**.

## O que o status da integração quer dizer

O cartão do WhatsApp mostra um de três status, sempre lido da conexão real, nunca de uma configuração salva.

| Status                 | O que significa                                           | O que fazer                                 |
| ---------------------- | --------------------------------------------------------- | ------------------------------------------- |
| **Conectado**          | O número está com a sessão aberta                         | Nada                                        |
| **Precisa de atenção** | O WhatsApp está configurado, mas a sessão não está aberta | Abrir **Gerenciar integração** e reconectar |
| **Desconectado**       | Nenhum número ativo                                       | Clicar em **Conectar**                      |

### O que o Atendimento mostra quando o número cai

O Atendimento separa uma queda curta de uma desconexão de verdade.

- **Queda curta**: até 2 minutos com a sessão fechada, ou até 10 minutos reconectando, contados da primeira queda. O chat continua aberto com a faixa **WhatsApp sem conexão** e "As conversas continuam aqui. Mensagens novas chegam quando a conexão voltar."
- **Desconexão**: passado esse prazo, ou se o número nunca foi conectado ou foi desconectado de propósito, o Atendimento troca o chat pela tela de conexão, com **Conectar número**

Quando a conexão volta, o chat reaparece sem você precisar recarregar a página. Em qualquer tela da IDX, uma queda também mostra o aviso **Instância desconectada**.

## Como desconectar ou trocar o tipo de conexão

Você desconecta em **Gerenciar integração**, no cartão do WhatsApp.

1. Clique em **Gerenciar integração**.
2. Clique em **Desconectar**.
3. Em **Desconectar o WhatsApp?**, clique em **Desconectar** de novo.

A IDX para de enviar e receber por aquele número, e as conversas e os contatos continuam no CRM. A confirmação é **WhatsApp desconectado**.

Para trocar de Conexão padrão para Cloud API, ou o contrário, desconecte a atual primeiro. Com uma conexão ativa, a outra aba fica bloqueada e a tela avisa "Para usar o outro tipo, desconecte o atual primeiro."

## Como o WhatsApp se conecta com o resto da IDX

O número conectado é a saída de quase tudo que a IDX manda para o cliente. Veja cada ligação:

- **CRM, leads e contatos**: uma conversa por contato e número. Se o contato já tem lead, a mensagem nova continua na conversa dele e não cria outro lead. Do lead no CRM, o botão **Conversar** abre ou cria a conversa
- **Roleta**: o lead criado pelo WhatsApp passa pela roleta. A exceção é o número próprio de um membro: o lead fica direto com ele
- **Automações por funil**: as mensagens das automações de coluna saem por um número conectado. Sem número conectado, a automação não envia e tenta de novo no próximo movimento do lead para a coluna
- **Chatbot de triagem**: o roteiro de perguntas da coluna também sai pelo WhatsApp. Quando a triagem começa, a automação da coluna de entrada não dispara. O agente de IA não pausa durante a triagem
- **Agente de IA**: responde no WhatsApp por funil, com a sua chave da OpenAI, e só no número da organização, nunca no número próprio de um membro
- **Mensagens prontas**: você cadastra em Automações e usa no chat digitando "/"
- **Marketing e Meta Ads**: a integração com o Meta Ads não conecta o WhatsApp. A Cloud API usa os dados do seu próprio app da Meta
- **Propostas**: o painel **Opções** da conversa tem **Nova proposta**
- **Contratos e Agenda**: não têm atalho no Atendimento
- **Membros e permissões**: conectar exige gerenciar o atendimento. O cargo com **WhatsApp próprio** obriga o membro a conectar o número dele, e ele passa a ver só as conversas desse número
- **Notificações**: mensagem nova toca um som e mostra um aviso na tela. Se o número cair, aparece o aviso **Instância desconectada**. Veja o guia de [notificações da IDX](/blog/notificacoes)

Na Cloud API, o bloqueio da janela de 24 horas vale para as mensagens que a equipe envia pelo chat. A triagem e o agente de IA enviam texto livre e não conferem a janela antes do envio.

## Qual plano libera o WhatsApp

O Atendimento, e com ele a conexão do WhatsApp, está nos planos Profissional e Avançado. No Essencial, o cartão do WhatsApp aparece em Integrações, mas **Conectar** abre os planos em vez do diálogo. Quem já tinha uma conexão continua vendo **Gerenciar integração**. A roleta, as automações e o agente de IA também começam no Profissional.

## Perguntas frequentes

### Posso usar a Conexão padrão e a Cloud API ao mesmo tempo?

Não no mesmo número. Com uma conexão ativa, a outra aba fica bloqueada e a IDX avisa para desconectar a atual antes de trocar de tipo.

### Se eu desconectar o WhatsApp, perco as conversas?

Não. A IDX para de enviar e receber mensagens por aquele número, mas as conversas e os contatos já registrados continuam no CRM.

### Por que não consigo gerar o QR code?

A Conexão padrão só fica disponível depois que a conta é verificada. A tela mostra o aviso com o botão Verificar conta, que leva aos seus dados na IDX.

### Cada corretor pode ter o próprio número?

Pode, se o cargo dele tiver a opção WhatsApp próprio marcada em Membros. Nesse caso ele conecta o número dele, e os leads que escrevem para esse número ficam direto com ele, sem passar pela roleta.