Visão geral
O SDK de conexão é um modal pronto que você embute no seu próprio software. O seu cliente clica em “conectar”, escaneia o QR Code (ou usa o número de telefone) e a instância Z-API dele conecta — tudo sem você construir nenhuma tela.- Carrega com uma única tag
<script>— expõewindow.ZAPIConnector. - Independente de framework (React, Vue, Angular, HTML puro…).
- Isolado via Shadow DOM: o CSS do seu site não afeta o modal, e o modal não afeta o seu.
- Personalizável (tema claro/escuro + cores) e traduzível (pt/en, ou seus próprios textos).
Testar no playground
Gere um token, escolha as opções e abra o conector ao vivo em
https://app.z-api.io/demo.html.O SDK cobre os mesmos cenários do painel Z-API: QR Code, número de telefone,
autenticação por chave de acesso (extensão) e migração de uma sessão do
WhatsApp Web já conectada.
Como funciona
A integração tem três partes: o seu backend gera um token de sessão, o seu site carrega o SDK e abre o conector com esse token.1
Seu backend gera o token
O seu servidor chama a Z-API (com o seu Client-Token) e recebe um token de sessão curto e descartável. Veja gerar token do SDK.
2
Seu site carrega o SDK
Inclua a tag
<script> que expõe window.ZAPIConnector.3
Seu site abre o conector
Chame
ZAPIConnector.open({ token }) com o token retornado pelo backend.1. Gere o token (no seu backend)
Quem fala com a Z-API é o seu backend, porque essa chamada usa o seu Client-Token, que nunca deve chegar ao navegador.token ao seu frontend, sem alterá-lo. Documentação completa do endpoint: Gerar token do SDK.
2. Carregue o SDK
Inclua a tag<script> na sua página. Essa URL sempre serve a versão mais recente — você não precisa atualizar nada quando lançarmos correções e melhorias.
window.ZAPIConnector globalmente.
3. Abra o conector
Quando o cliente clicar em conectar, busque o token no seu backend e chameopen(). Ele devolve uma Promise<boolean> que fica pendente até o modal fechar e resolve true se o canal conectou:
Opções
ZAPIConnector.open(options) aceita:
Temas
Passe um modo ("light" ou "dark"), ou um objeto ThemeOptions para sobrescrever cores específicas por modo:
ThemeColors, todos opcionais):
Idioma
Idiomas nativos:pt e en (detectados de navigator.language). Force um com locale:
messages — um mapa parcial mesclado sobre o idioma selecionado. Passe só as chaves que quer mudar:
Métodos de conexão
Por padrão o modal mostra QR Code, número de telefone e o link de migração. Usemethods para exibir só o que quiser:
Quando só um método fica ativo, as abas não aparecem (vai direto para ele). Se
você desativar QR e telefone ao mesmo tempo, o SDK reativa os dois para não
deixar o modal sem forma de conectar.
Fila de mensagens
Uma instância pode ter mensagens na fila (acumuladas enquanto esteve desconectada). Ao conectar, todas são enviadas de uma vez. Por isso, antes de conectar, o modal mostra quantas mensagens estão na fila e oferece a opção de limpar — evitando um disparo em massa no momento da conexão. A contagem é atualizada automaticamente a cada 10 segundos enquanto o modal está aberto. Para esconder esse aviso, passeshowQueue: false:
Instância expirada
Se o período de uso da instância acabar, o WhatsApp deixa de aceitar a conexão. Nesse caso, em vez de um QR Code que não carrega, o modal mostra uma tela de instância expirada. Reassinar é uma ação do seu backend (billing), então o botão “Assinar novamente” só aparece se você passar um callbackonSubscribe. Ao clicar, o modal chama o seu callback — nele você dispara o seu fluxo de assinatura (chamar o seu backend, redirecionar para a página de planos, etc.):
onSubscribe, a tela mostra apenas a mensagem de expiração. Em ambos os casos, o evento status é emitido com "expired". Se a instância for reassinada com o modal ainda aberto, ele se reconecta sozinho.
Eventos
Acompanhe o ciclo de vida da conexão comon / off:
Métodos
Mensagens
Todo texto do modal pode ser sobrescrito pormessages. Abaixo, cada chave, o valor padrão em português e para que serve. Passe apenas as chaves que quiser alterar.