Connectors

WhatsApp Connector

The WhatsApp connector enables Kiwire to send OTP codes and notifications to guests via WhatsApp using the Meta WhatsApp Business API (Cloud API). In markets where WhatsApp is the dominant messaging platform — Southeast Asia, South Asia, Latin America, and many parts of Africa and Europe — this connector offers significantly higher open rates and deliverability compared to SMS.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}
Image not uploaded yet public/assets/img/docs/connector-whatsapp/overview.png
The WhatsApp connector configuration — Meta phone number ID, access token, and API version.

Prerequisites

The WhatsApp Business API is a Meta product requiring approval and setup before it can be used. Before configuring this connector, you must complete the following steps in the Meta ecosystem:

  1. Create a Meta Business Portfolio — go to business.facebook.com and set up or verify your business account.
  2. Create a WhatsApp Business App — in the Meta Developer Dashboard, create a new app of type "Business" and add the WhatsApp product.
  3. Verify your Business — Meta requires business verification to access the full WhatsApp Cloud API (including message sending to users outside your test list).
  4. Register a Phone Number — add and verify the phone number to be used as your WhatsApp Business sender. This number must not already be registered with any WhatsApp personal or business account.
  5. Create approved message templates — WhatsApp requires pre-approved templates for OTP messages. See the Message Templates section below.

WhatsApp Business API access is not instant. Business verification, phone number registration, and template approval can each take several business days. Plan accordingly before deploying WhatsApp OTP to production.

Configuration Fields

FieldDescription
nameInstance label for this WhatsApp connector (e.g., Main WhatsApp)
is_activeEnable or disable this connector without losing configuration
phone_number_idThe WhatsApp Business phone number ID from the Meta Developer Dashboard. Found under WhatsApp → API Setup → Phone Number ID. This is a numeric string (e.g., 123456789012345), not the phone number itself.
access_tokenMeta API access token used to authenticate all API calls. A temporary token (24-hour) is generated in the Meta Developer Dashboard for testing; for production, generate a Permanent System User Token via the Meta Business Suite to avoid token expiry. Stored encrypted at rest.
api_versionMeta Graph API version used for all requests (e.g., v18.0, v19.0). Use the latest stable version. Check the Meta changelog for deprecation notices.

Always use a Permanent System User Token for production — not the temporary token shown in the Developer Dashboard. Temporary tokens expire after 24 hours and will silently break WhatsApp OTP delivery. Create a system user in Meta Business Suite → Business Settings → Users → System Users, assign the WhatsApp Business app, and generate a permanent token with the whatsapp_business_messaging permission.

Message Templates

WhatsApp requires that all messages sent to users outside an active conversation window use a pre-approved message template. OTP messages sent by Kiwire must use a Meta-approved template — free-form OTP delivery is not permitted.

Meta provides a built-in OTP template category with pre-approved templates for one-time passwords. To set up your OTP template:

  1. In Meta Business Suite, go to WhatsApp Manager → Message Templates
  2. Create a new template in the Authentication category
  3. Use the pre-built OTP template provided by Meta, or submit a custom template for review
  4. Note the approved template name — enter it in the WhatsApp connector's advanced configuration

Authentication category templates in Meta are specifically designed for OTP delivery and are approved faster than marketing templates. The standard OTP template looks like: "Your verification code is 1. For your security, do not share this code."

Usage in Captive Portal

Once the WhatsApp connector is active, the WhatsApp OTP login method becomes available to enable on captive portal journeys. The guest flow is:

  1. Guest selects WhatsApp OTP on the captive portal login page
  2. Guest enters their WhatsApp-registered phone number in international format
  3. Kiwire calls the WhatsApp Cloud API to send an OTP via the approved template
  4. Guest receives the WhatsApp message and enters the code on the portal
  5. On successful verification, the guest is authenticated and connected

WhatsApp OTP works best in markets where guests are likely to have WhatsApp installed and their phone number registered. Consider offering both SMS OTP and WhatsApp OTP as options in the captive portal journey, letting guests choose their preferred channel.

Testing the Configuration

Click Send Test Message after saving. Enter a WhatsApp-registered phone number in international format (e.g., +60123456789). The test sends an OTP-style message using the configured template. If the test succeeds, the recipient receives the WhatsApp message within seconds.

If the test fails with an authentication error, verify:

  • The access_token is valid and not expired (temporary tokens expire after 24 hours)
  • The system user has the whatsapp_business_messaging permission
  • The phone_number_id matches the registered phone number in your Meta app
  • Your WhatsApp business account is verified and the phone number is active

Required Permissions

view-connector-whatsapp · edit-connector-whatsapp