Conectar uma API externa de WhatsApp

Entender o que será conectado

Evolution, Wuzapi, Z-API e UazAPI são conectores externos usados para criar uma sessão de WhatsApp no atendimento. Este procedimento começa com um serviço já disponível e cobre somente seu credenciamento, a criação do canal e a validação da conversa.

• URL da API identifica o endereço base do serviço externo.
• Global Key é a credencial administrativa usada para validar a integração com o serviço.
• Instância ou sessão identifica a conexão que ficará vinculada ao número de WhatsApp.
• API Token e Number ID (Instance ID) identificam a instância nos formulários atuais de Z-API e UazAPI.
• QR Code ou código de pareamento, quando disponíveis, autorizam o dispositivo na sessão escolhida.

Preparar os dados sem expor segredos

1. 1

   Confirme qual dos quatro conectores foi aprovado para a operação.

2. 2

   Obtenha a URL base e a chave global diretamente no ambiente autorizado do serviço.

3. 3

   Quando a sessão já existir, separe o nome exato, o ID e o token que o formulário atual solicitar.

4. 4

   Defina um nome interno claro para o canal e confirme se ele precisará coincidir com uma instância existente.

5. 5

   Escolha a fila ou o usuário de teste que receberá a primeira conversa.

6. 6

   Mantenha uma pessoa responsável pelo serviço externo disponível durante a validação.

Credenciar o serviço nas Integrações

• Configuração > Configurações > Integrações apresenta atualmente Z-API, UazAPI, Evolution API, Evolution Go e WuzAPI quando esses recursos estão disponíveis para a empresa.
• Z-API, UazAPI, Evolution API e WuzAPI usam URL da API e Global Key em suas páginas de credenciamento.
• As alterações desses campos são salvas automaticamente; aguarde antes de atualizar ou trocar de seção.
• Somente Evolution API apresentou Verificar Status da API na interface atual. WuzAPI, Z-API e UazAPI exibiram apenas os campos com salvamento automático.
• Evolution Go é uma opção separada e não deve receber, por analogia, os campos ou credenciais descritos neste guia.

1. 1

   Abra a seção do conector escolhido.

2. 2

   Registre o estado atual sem copiar os valores existentes.

3. 3

   Preencha a URL da API e a Global Key nos campos correspondentes.

4. 4

   Aguarde o salvamento automático e observe se o formulário mantém os valores preenchidos.

5. 5

   Na Evolution API, selecione Verificar Status da API uma vez e aguarde o resultado.

6. 6

   Atualize a página e confirme novamente o estado antes de criar o canal.

Criar ou selecionar a instância do canal

1. 1

   Acesse Administração > Canais e selecione Adicionar Canal. Quando a gestão estiver em Configurações, use Configuração > Configurações > Sessões.

2. 2

   Escolha Evolution, Wuzapi, Z-API ou UazAPI conforme o serviço credenciado.

3. 3

   Informe um nome interno sem dados pessoais e revise as atribuições de fila ou usuário.

4. 4

   Preencha somente os campos exibidos para o conector escolhido.

5. 5

   Leia novamente nome, serviço, credenciais da instância e destino antes de salvar.

6. 6

   Salve uma única vez e aguarde a atualização da lista.

• Evolution API: o formulário atual solicita o nome do canal e permite informar um número de pareamento quando essa modalidade for usada.
• WuzAPI: o formulário atual apresenta um controle para usar código de pareamento; mantenha-o desligado quando a autorização ocorrer por QR Code.
• Z-API: para vincular uma instância preparada, informe API Token e Number ID (Instance ID) pertencentes ao mesmo ambiente.
• UazAPI: para reutilizar uma instância, informe API Token e Number ID (Instance ID). Deixe-os vazios somente quando a versão atual e o procedimento aprovado indicarem a criação de uma nova instância.
• Se a sua versão apresentar campos diferentes, siga somente os rótulos e orientações da tela; não adapte credenciais de outro conector.

Autorizar o dispositivo na sessão

1. 1

   Abra a sessão recém-criada ou vinculada.

2. 2

   Use Gerar QR Code ou a opção de código de pareamento quando ela estiver disponível para o conector.

3. 3

   No aparelho autorizado, abra o WhatsApp e acesse Dispositivos conectados.

4. 4

   Conecte um dispositivo e leia o código exibido na sessão.

5. 5

   Aguarde a mudança de estado antes de atualizar ou gerar outro código.

6. 6

   Confirme que o número apresentado corresponde ao aparelho de teste.

Validar entrada, resposta e roteamento

1. 1

   Atualize a lista e confirme que a sessão permanece conectada.

2. 2

   Envie uma mensagem simples do número de teste para o canal conectado.

3. 3

   Localize o novo ticket em Atendimento e confira canal, contato, fila e responsável.

4. 4

   Responda pelo Atendeu Rápido e confirme o recebimento no aparelho de teste.

5. 5

   Envie uma segunda mensagem depois de alguns minutos e confirme que o mesmo atendimento foi atualizado sem duplicidade.

6. 6

   Quando o serviço apresentar registros de eventos, confirme o processamento sem copiar mensagem, telefone completo ou credenciais.

7. 7

   Libere o canal somente depois que entrada, saída e roteamento forem aprovados.

Resolver falhas sem duplicar a sessão

• Conector não aparece: confirme se URL e Global Key foram preenchidas e salvas automaticamente na integração correta.
• Verificação de status falha: quando essa ação estiver disponível, revise o endereço base, a barra final quando aplicável, a chave usada e a disponibilidade do serviço externo.
• Acesso recusado: não troque chaves por tentativa; confirme no serviço qual credencial tem o escopo exigido.
• Instância não encontrada em Z-API ou UazAPI: confira se API Token e Number ID pertencem à mesma instância e ao mesmo ambiente.
• Pareamento não inicia em Evolution: revise o número informado e confirme se a modalidade está disponível para a conexão atual.
• WuzAPI não apresenta o código esperado: confirme se o controle de código de pareamento está no estado correspondente ao método escolhido.
• QR Code não conecta: atualize a sessão, gere um código novo e confirme que o aparelho pode adicionar outro dispositivo.
• Sessão desconecta: verifique primeiro o estado do serviço e do aparelho antes de excluir ou recriar o canal.
• Mensagens não chegam: valide sessão, atribuições e ticket de teste antes de alterar webhooks ou criar outra instância.