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õe window.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.
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 .
Seu site carrega o SDK
Inclua a tag <script> que expõe window.ZAPIConnector.
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.
curl --location ' https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/sdk-connector-token ' \ --header ' Client-Token: SEU_CLIENT_TOKEN '
Resposta: { " token " : " eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... " }
Devolva esse token ao seu frontend, sem alterá-lo. Documentação completa do endpoint: Gerar token do SDK .
O token é gerado pelo seu backend e é de uso único para o conector. Nunca
exponha o seu Client-Token nem as credenciais da instância (instanceId e
token) no frontend.
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.
< script src = " https://app.z-api.io/sdk.js " async ></ script >
Isso expõe window.ZAPIConnector globalmente.
3. Abra o conector Quando o cliente clicar em conectar, busque o token no seu backend e chame open(). Ele devolve uma Promise<boolean> que fica pendente até o modal fechar e resolve true se o canal conectou:
async function conectar ( instanceId ) { const { token } = await fetch ( ` /sdk-token/ ${ instanceId }` ). then (( r ) => r . json (), ); const conectado = await ZAPIConnector . open ({ token }); if ( conectado ) { atualizarInstancias (); } }
Opções ZAPIConnector.open(options) aceita:Opção Tipo Descrição tokenstring (obrigatório) Token de sessão retornado pelo seu backend. Passe como veio — o SDK escolhe a experiência de conexão a partir dele. theme"light" | "dark" | ThemeOptionsTema de cores. Padrão: "light". Veja Temas . locale"pt" | "en" | stringIdioma da interface. Detectado do navegador quando omitido. messagesPartial<Messages>Sobrescreve textos individuais ou traduz para outro idioma. Veja Mensagens . methods{ qr?, phone?, migrate? }Quais opções de conexão exibir. Cada uma é true por padrão. Veja Métodos de conexão . containerstring | HTMLElementOnde montar o modal. Padrão: document.body.
Temas Passe um modo ("light" ou "dark"), ou um objeto ThemeOptions para sobrescrever cores específicas por modo:
ZAPIConnector . open ({ token , theme : { mode : " dark " , light : { accent : " #25d366 " }, dark : { accent : " #00a884 " , surface : " #111b21 " }, }, });
Tokens de cor (ThemeColors, todos opcionais):
Token Descrição overlayCor do fundo escurecido atrás do modal surfaceCor de fundo do cartão do modal surfaceAltFundo secundário (abas, campos, caixas) textCor do texto principal textMutedCor do texto secundário borderCor das bordas accentCor de destaque (botões, links, realces) accentContrastCor do texto sobre a cor de destaque
Idioma Idiomas nativos: ptennavigator.language). Force um com locale:
ZAPIConnector . open ({ token , locale : " pt " });
Para ajustar textos ou traduzir para um idioma que não seja nativo, use messages — um mapa parcial mesclado sobre o idioma selecionado. Passe só as chaves que quer mudar:
ZAPIConnector . open ({ token , messages : { title : " Conecte seu número " , subtitle : " Aponte a câmera do WhatsApp para o código. " , }, });
Métodos de conexão Por padrão o modal mostra QR Code, número de telefone e o link de migração. Use methods para exibir só o que quiser:
ZAPIConnector . open ({ token , methods : { phone : false , migrate : false } });
Chave Descrição qrAba do QR Code. Padrão true. phoneAba do número de telefone. Padrão true. migrateLink para migrar uma sessão do WhatsApp Web existente. Padrão true.
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.
Eventos Acompanhe o ciclo de vida da conexão com on / off:
ZAPIConnector . on ( " connected " , () => atualizarInstancias ()); ZAPIConnector . on ( " status " , ({ status }) => console . log ( status )); ZAPIConnector . off ( " connected " , handler );
Evento Payload Disparado quando connected{ phone? }o canal conectou disconnected{ reason? }caiu ou foi desconectado qr{ base64 }um novo QR Code foi renderizado status{ status }o status mudou ("qr", "connected" ou "disconnected") error{ error }ocorreu um erro close– o usuário fechou o modal
Métodos Método Retorno Descrição open(options)Promise<boolean>Abre o modal; resolve quando ele fecha (true se conectou). close()voidFecha o modal programaticamente. on(event, handler)voidInscreve em um evento. off(event, handler)voidCancela a inscrição.
Mensagens Todo texto do modal pode ser sobrescrito por messages. Abaixo, cada chave, o valor padrão em português e para que serve. Passe apenas as chaves que quiser alterar.
Tela inicial e QR Code Chave Padrão Descrição titleConecte seu WhatsApp Título do modal subtitleEscaneie o QR code com seu celular para conectar. Subtítulo abaixo do título step1Abra o WhatsApp no seu celular Passo 1 das instruções do QR step2Toque em Configurações e depois em Aparelhos conectados Passo 2 das instruções do QR step3Toque em Conectar um aparelho e escaneie este código Passo 3 das instruções do QR qrLoadingGerando QR code… Texto enquanto o QR carrega qrErrorNão foi possível carregar o QR code. Tente novamente. Erro ao carregar o QR closeFechar Rótulo (aria) do botão de fechar tabQrQR code Rótulo da aba de QR Code tabPhoneNúmero de telefone Rótulo da aba de número de telefone
Conexão por número (web) Chave Padrão Descrição phoneHintDigite seu número do WhatsApp para receber um código de pareamento. Instrução da aba de telefone countrySearchBuscar país Placeholder da busca de país phonePlaceholderNúmero de telefone Placeholder do campo de número submitContinuar Botão para gerar o código phoneSendingGerando código… Estado do botão enquanto gera codeHintDigite este código no WhatsApp: Instrução acima do código de pareamento codeStep3Toque em Conectar com número de telefone e digite o código Passo para inserir o código no WhatsApp codeBackUsar outro número Voltar para digitar outro número
Fluxo de conexão por número (instâncias mobile) Chave Padrão Descrição mVerifyingVerificando número… Verificando o número informado mMethodHintComo quer receber o código? Escolha do método de envio do código mSmsSMS Opção de receber por SMS mCallLigação Opção de receber por ligação mWhatsappWhatsApp Opção de receber pelo WhatsApp mSendingEnviando… Enviando o código mCodeHintDigite o código que você recebeu Instrução para digitar o código recebido mWaOldHintAbra o WhatsApp no seu celular — você vai receber o código por lá. Digite-o abaixo. Instrução do método WhatsApp mConfirmConfirmar Botão de confirmar o código mConfirmingConfirmando… Estado enquanto confirma mCaptchaHintDigite os caracteres da imagem Instrução do captcha mSecurityHintDigite seu PIN (verificação em duas etapas) Instrução do PIN de duas etapas mForgotPinEsqueci o PIN Link de recuperação de PIN mConfirmOnPhoneConfirme no seu celular e toque em Confirmar Confirmação no aparelho mErrorAlgo deu errado. Tente novamente. Erro genérico mWrongCodeCódigo incorreto. Tente de novo. Código digitado incorreto mBlockedEste número está bloqueado pelo WhatsApp. Número bloqueado mUnblockSolicitar desbloqueio Botão para solicitar desbloqueio mNoRoutesNão conseguimos enviar o código agora. Verifique o número e tente outro método. Nenhuma rota de envio disponível mRateLimitMuitas tentativas. Aguarde um pouco antes de tentar de novo. Limite de tentativas atingido mBannedEste número está banido. Número banido mBannedTextDescreva por que este número deve ser desbanido: Texto do formulário de apelação mSendEnviar Botão de enviar a apelação mInReviewSeu pedido está em análise pelo WhatsApp. Apelação em análise mPinSentEnviamos as instruções de recuperação do PIN. Instruções de recuperação enviadas mPhoneOfflineCelular offline — as mensagens podem atrasar. Aviso de celular offline
Migração de sessão Chave Padrão Descrição migrateOrou Separador antes do link de migração migrateLinkClique aqui e migre uma conexão do WhatsApp Web já conectada pra cá Botão que abre o fluxo de migração migrateHintMigre sua sessão do WhatsApp Web com a extensão. Use este código: Instrução da tela de migração migrateStep1Instale a extensão Z-API Conector Passo 1 da migração migrateStep2Abra o web.whatsapp.com já conectado no seu computador Passo 2 da migração migrateStep3Abra a extensão e digite o código acima Passo 3 da migração migrateBackVoltar Voltar da tela de migração
Conectado Chave Padrão Descrição connectedTitleConectado Título da tela de sucesso disconnectDesconectar Botão de desconectar a instância disconnectingDesconectando… Estado enquanto desconecta
Autenticação por chave de acesso (extensão) Chave Padrão Descrição challengeTextConfirme a autenticação no seu dispositivo para conectar esta instância. Instrução da tela de autenticação challengeButtonResolver autenticação Botão para resolver a autenticação challengeSolvingAutenticando… Estado enquanto autentica challengeCancelCancelar Cancelar a autenticação installTitleAutenticação por chave de acesso Título da tela de instalação da extensão installTextA extensão confirma sua biometria neste dispositivo para conectar. Descrição da extensão installStep1Instale a extensão e adicione ao seu navegador Passo 1 da instalação installStep2Volte para esta janela — a conexão segue automaticamente Passo 2 da instalação installButtonInstalar extensão Botão genérico de instalar installChromeInstalar no Chrome Botão de instalar no Chrome installFirefoxInstalar no Firefox Botão de instalar no Firefox unsupportedBrowserAbra esta página no Chrome ou no Firefox para conectar com chave de acesso. Aviso em navegador sem suporte
Teste no playground Abra o playground do SDK para gerar um token, ajustar tema, idioma e métodos, e ver o conector real funcionando. 