Connection & Setup

Connection (API)

WhatsApp requires a WhatsApp Business Account (WABA) and uses Meta's infrastructure for authentication. There are two ways to connect via the API:

Option 1: Redirect Flow (Recommended)

The standard OAuth-style redirect flow. Works from any domain, no JavaScript SDK required. Same pattern as connecting Instagram, TikTok, or any other platform.

1. Your app calls the connect endpoint to get an auth URL
2. You redirect the user to Meta's WhatsApp signup page
3. User selects or creates a WhatsApp Business Account and picks a phone number
4. User is redirected back to your app with the connection details

Step 1: Get the auth URL

const { data } = await zernio.get('/v1/connect/whatsapp', {
  params: {
    profileId: 'YOUR_PROFILE_ID',
    redirect_url: 'https://yourdomain.com/callback'
  }
});

// Redirect your user to the auth URL
// data.authUrl -> Meta's WhatsApp signup page

response = client.get('/v1/connect/whatsapp', params={
    'profileId': 'YOUR_PROFILE_ID',
    'redirect_url': 'https://yourdomain.com/callback'
})
auth_url = response.json()['authUrl']
# Redirect user to auth_url

curl "https://zernio.com/api/v1/connect/whatsapp?profileId=YOUR_PROFILE_ID&redirect_url=https://yourdomain.com/callback" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Returns: { "authUrl": "https://facebook.com/...", "state": "..." }

Step 2: Redirect your user to the authUrl. They complete WhatsApp Business signup on Meta's page.

Step 3: After completing signup, the user is redirected back to your redirect_url with connection details appended as query parameters:

https://yourdomain.com/callback?connected=whatsapp&profileId=xxx&accountId=xxx&username=+1234567890

The account is now connected and ready to send and receive messages.

Option 2: Headless Credentials (No Browser)

If you already have your Meta credentials, you can connect entirely via API with no browser popup. This is ideal for server-to-server integrations, CLI tools, or automated provisioning.

Prerequisites: Create a System User in Meta Business Suite, generate a permanent access token with whatsapp_business_management and whatsapp_business_messaging permissions (add whatsapp_business_manage_events too if you plan to use Click-to-WhatsApp conversion tracking), and get your WABA ID and Phone Number ID from the WhatsApp Manager.

const { data } = await zernio.post('/v1/connect/whatsapp/credentials', {
  profileId: 'YOUR_PROFILE_ID',
  accessToken: 'YOUR_META_SYSTEM_USER_TOKEN',
  wabaId: 'YOUR_WABA_ID',
  phoneNumberId: 'YOUR_PHONE_NUMBER_ID'
});
console.log('Connected:', data.account.accountId);

response = client.post('/v1/connect/whatsapp/credentials', json={
    'profileId': 'YOUR_PROFILE_ID',
    'accessToken': 'YOUR_META_SYSTEM_USER_TOKEN',
    'wabaId': 'YOUR_WABA_ID',
    'phoneNumberId': 'YOUR_PHONE_NUMBER_ID'
})
print(f"Connected: {response.json()['account']['accountId']}")

curl -X POST https://zernio.com/api/v1/connect/whatsapp/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "accessToken": "YOUR_META_SYSTEM_USER_TOKEN",
    "wabaId": "YOUR_WABA_ID",
    "phoneNumberId": "YOUR_PHONE_NUMBER_ID"
  }'

The endpoint validates your credentials against Meta's API, creates the connection, subscribes to webhooks, and registers the phone number on the WhatsApp network. If the phoneNumberId is not found in your WABA, the response includes available phone numbers so you can correct it.

WhatsApp Business App Coexistence

Businesses that already use the WhatsApp Business app can connect their existing number to Cloud API without giving up the app. During the Embedded Signup flow (Option 1), they will see an option to connect their existing WhatsApp Business app account and phone number.

When a business chooses this option:

• Their phone number works with both the WhatsApp Business app and Cloud API simultaneously
• Messages sent and received are mirrored between both apps (up to 6 months of history is synced)
• Contacts from the WhatsApp Business app are imported automatically
• The business can still send individual messages from the WA Business app

Limitations:

Disconnection: The business disconnects from the WhatsApp Business app (Settings > Account > Business Platform > Disconnect). This cannot be done via API. When they disconnect, Zernio automatically deactivates the account.

Getting Started (App Setup)

Follow these steps to connect your WhatsApp Business Account through the Zernio dashboard.

Step 1: Go to Connections

Navigate to Connections in the sidebar and find the WhatsApp card. Click + Connect to start the setup.

Step 2: Choose Your Number Type

You'll see two options:

1. Get a new number (recommended) - Zernio provisions and verifies a number for you. You pick the country next. US is $2/mo; most other countries run $2 to $25/mo (shown before you confirm).
2. Use my own number - Bring your existing phone number. Requires verification during setup.

Step 3: Pick a Country and Confirm

Choose the country for your number and review its monthly price.

• US and other instant countries are provisioned and verified in about 30 seconds.
• Regulated countries (most of Europe, plus many others) require a one-time identity-verification (KYC) form before the number can be provisioned: the registrant's name, a local address, and an ID document or business registration. Some countries (for example, Australia) also require the end user to complete an ID check via a secure link. After you submit, the order goes to regulatory review and the number activates within 1-3 business days; we email you (and fire the whatsapp.number.activated webhook) when it's ready.

Click Confirm to proceed.

Step 4: Auto-Verification

Zernio automatically verifies your number with Meta. This usually takes about 30 seconds - just wait for the verification to complete.

Step 5: Continue to Meta Registration

Once verification is complete, click Continue to WhatsApp setup to register your phone number with Meta.

Step 6: Meta Account Setup

You'll be redirected to Meta's Embedded Signup. Here you can either create a new WhatsApp Business Account or connect to an existing one. Follow the prompts to complete the setup.

Step 7: Select Your Number

In the phone number selection, you'll see the number you purchased already marked as Verified. Select it and continue.

Step 8: Connected!

Once verified, your WhatsApp account appears in your connections list with a connected status. You can now click Settings to configure it.

Step 9: Manage Templates

Click Settings on your WhatsApp connection to view and create message templates. Templates must be approved by Meta before use.

Step 10: Configure Business Profile

Switch to the Business Profile tab to customize your profile picture, display name, about text, description, and contact information.