Overview The Connection SDK is a ready-made modal you embed in your own software. Your customer clicks “connect”, scans the QR code (or uses their phone number), and their Z-API instance connects — without you building any screen.
Loads with a single <script> tag — exposes window.ZAPIConnector.
Framework-agnostic (React, Vue, Angular, plain HTML…).
Isolated via Shadow DOM: your site’s CSS can’t affect the modal, and the modal can’t affect yours.
Themeable (light/dark + colors) and translatable (pt/en, or your own strings).
Try the playground Generate a token, pick the options and open the connector live at
https://app.z-api.io/demo.html.
The SDK covers the same scenarios as the Z-API panel: QR code, phone number,
passkey authentication (extension) and migrating an already-connected WhatsApp
Web session.
How it works Integration has three parts: your backend generates a session token, your site loads the SDK and opens the connector with that token.
Your backend generates the token
Your server calls Z-API (with your Client-Token) and gets a short, disposable session token. See generate the SDK token .
Your site loads the SDK
Add the <script> tag that exposes window.ZAPIConnector.
Your site opens the connector
Call ZAPIConnector.open({ token }) with the token returned by the backend.
1. Generate the token (on your backend) The one talking to Z-API is your backend , because this call uses your Client-Token , which must never reach the browser.
curl --location ' https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/sdk-connector-token ' \ --header ' Client-Token: YOUR_CLIENT_TOKEN '
Response: { " token " : " eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... " }
Return that token to your frontend as-is. Full endpoint reference: Generate the SDK token .
The token is generated by your backend and is single-use for the connector.
Never expose your Client-Token or the instance credentials (instanceId and
token) in the frontend.
2. Load the SDK Add the <script> tag to your page. This URL always serves the latest version — you don’t need to update anything when we ship fixes and improvements.
< script src = " https://app.z-api.io/sdk.js " async ></ script >
This exposes window.ZAPIConnector globally.
3. Open the connector When the customer clicks connect, fetch the token from your backend and call open(). It returns a Promise<boolean> that stays pending until the modal closes and resolves true if the channel connected:
async function connect ( instanceId ) { const { token } = await fetch ( ` /sdk-token/ ${ instanceId }` ). then (( r ) => r . json (), ); const connected = await ZAPIConnector . open ({ token }); if ( connected ) { refreshInstances (); } }
Options ZAPIConnector.open(options) accepts:Option Type Description tokenstring (required) Session token returned by your backend. Pass it as-is — the SDK picks the connection experience from it. theme"light" | "dark" | ThemeOptionsColor theme. Default: "light". See Themes . locale"pt" | "en" | stringUI language. Auto-detected from the browser when omitted. messagesPartial<Messages>Override individual strings or translate to another language. See Messages . methods{ qr?, phone?, migrate? }Which connection options to show. Each is true by default. See Connection methods . containerstring | HTMLElementWhere to mount the modal. Default: document.body.
Themes Pass a mode ("light" or "dark"), or a ThemeOptions object to override specific colors per mode:
ZAPIConnector . open ({ token , theme : { mode : " dark " , light : { accent : " #25d366 " }, dark : { accent : " #00a884 " , surface : " #111b21 " }, }, });
Color tokens (ThemeColors, all optional):
Token Description overlayDimmed backdrop behind the modal surfaceModal card background surfaceAltSecondary background (tabs, fields, boxes) textPrimary text color textMutedSecondary text color borderBorder color accentAccent color (buttons, links, highlights) accentContrastText color on top of the accent color
Language Built-in languages: ptennavigator.language). Force one with locale:
ZAPIConnector . open ({ token , locale : " en " });
To tweak wording or translate to a non-built-in language, use messages — a partial map merged over the selected locale. Pass only the keys you want to change:
ZAPIConnector . open ({ token , messages : { title : " Connect your number " , subtitle : " Point your WhatsApp camera at the code. " , }, });
Connection methods By default the modal shows QR code, phone number and the migration link. Use methods to show only what you want:
ZAPIConnector . open ({ token , methods : { phone : false , migrate : false } });
Key Description qrQR code tab. Default true. phonePhone number tab. Default true. migrateLink to migrate an existing WhatsApp Web session. Default true.
When only one method is enabled, the tabs are hidden (it goes straight to it).
If you disable QR and phone at the same time, the SDK re-enables both so the
modal is never left without a way to connect.
Events Track the connection lifecycle with on / off:
ZAPIConnector . on ( " connected " , () => refreshInstances ()); ZAPIConnector . on ( " status " , ({ status }) => console . log ( status )); ZAPIConnector . off ( " connected " , handler );
Event Payload Fired when connected{ phone? }the channel connected disconnected{ reason? }it dropped or was disconnected qr{ base64 }a new QR code was rendered status{ status }status changed ("qr", "connected" or "disconnected") error{ error }an error occurred close– the user closed the modal
Methods Method Returns Description open(options)Promise<boolean>Opens the modal; resolves when it closes (true if connected). close()voidCloses the modal programmatically. on(event, handler)voidSubscribe to an event. off(event, handler)voidUnsubscribe.
Messages Every string in the modal can be overridden via messages. Below, each key, its default English value and what it’s for. Pass only the keys you want to change.
Home screen and QR code Key Default Description titleConnect your WhatsApp Modal title subtitleScan the QR code with your phone to connect. Subtitle below the title step1Open WhatsApp on your phone QR instructions step 1 step2Tap Settings , then Linked devices QR instructions step 2 step3Tap Link a device and scan this code QR instructions step 3 qrLoadingGenerating QR code… Text while the QR loads qrErrorCould not load the QR code. Please try again. Error loading the QR closeClose Close button label (aria) tabQrQR code QR code tab label tabPhonePhone number Phone number tab label
Phone connection (web) Key Default Description phoneHintEnter your WhatsApp number to receive a pairing code. Phone tab instruction countrySearchSearch country Country search placeholder phonePlaceholderPhone number Phone field placeholder submitContinue Button to generate the code phoneSendingGenerating code… Button state while generating codeHintEnter this code in WhatsApp: Instruction above the pairing code codeStep3Tap Link with phone number and enter the code Step to enter the code in WhatsApp codeBackUse another number Back to enter a different number
Phone connection flow (mobile instances) Key Default Description mVerifyingChecking number… Verifying the entered number mMethodHintHow do you want to receive the code? Choose the code delivery method mSmsSMS Receive via SMS mCallCall Receive via call mWhatsappWhatsApp Receive via WhatsApp mSendingSending… Sending the code mCodeHintEnter the code you received Prompt to enter the received code mWaOldHintOpen WhatsApp on your phone — you’ll receive the code there. Enter it below. WhatsApp method instruction mConfirmConfirm Confirm the code mConfirmingConfirming… State while confirming mCaptchaHintType the characters in the image Captcha instruction mSecurityHintEnter your PIN (two-step verification) Two-step PIN instruction mForgotPinForgot PIN PIN recovery link mConfirmOnPhoneConfirm on your phone, then tap Confirm Confirmation on the device mErrorSomething went wrong. Please try again. Generic error mWrongCodeWrong code. Try again. Wrong code entered mBlockedThis number is blocked by WhatsApp. Number blocked mUnblockRequest unblock Button to request unblock mNoRoutesWe couldn’t send the code right now. Check the number and try another method. No delivery route available mRateLimitToo many attempts. Please wait before trying again. Attempt limit reached mBannedThis number is banned. Number banned mBannedTextDescribe why this number should be unbanned: Appeal form text mSendSend Send the appeal mInReviewYour appeal is under review by WhatsApp. Appeal under review mPinSentWe’ve sent PIN recovery instructions. Recovery instructions sent mPhoneOfflinePhone offline — messages may be delayed. Phone offline warning
Session migration Key Default Description migrateOror Separator before the migration link migrateLinkClick here to migrate an already-connected WhatsApp Web session Button that opens the migration flow migrateHintMigrate your WhatsApp Web session with the extension. Use this code: Migration screen instruction migrateStep1Install the Z-API Connector extension Migration step 1 migrateStep2Open web.whatsapp.com already connected on your computer Migration step 2 migrateStep3Open the extension and enter the code above Migration step 3 migrateBackBack Back from the migration screen
Connected Key Default Description connectedTitleConnected Success screen title disconnectDisconnect Button to disconnect the instance disconnectingDisconnecting… State while disconnecting
Passkey authentication (extension) Key Default Description challengeTextConfirm the authentication on your device to connect this instance. Authentication screen instruction challengeButtonResolve authentication Button to resolve authentication challengeSolvingAuthenticating… State while authenticating challengeCancelCancel Cancel authentication installTitlePasskey authentication Extension install screen title installTextThe extension confirms your biometrics on this device to connect. Extension description installStep1Install the extension and add it to your browser Install step 1 installStep2Come back to this window — it continues automatically Install step 2 installButtonInstall extension Generic install button installChromeInstall on Chrome Install-on-Chrome button installFirefoxInstall on Firefox Install-on-Firefox button unsupportedBrowserOpen this page in Chrome or Firefox to connect with a passkey. Warning on an unsupported browser
Try the playground Open the SDK playground to generate a token, adjust theme, language and methods, and see the real connector in action. 