Partner Integration Guide - Option 2: WABA Pre-Registration Integration

This guide will help you integrate the SendZen WABA Pre-Registration method into your partner panel.

With this method, instead of embedding an iframe onboarding component, you register your customer's details (mapping their SendZen project_id and their phone_number) via the SendZen backend API first, and then redirect the user to the Meta WhatsApp onboarding URL to complete WABA registration. SendZen will automatically link the newly registered number to their project in the background.

Prerequisites

Partner API key from SendZen

Access to your partner panel/dashboard

Ability to make server-to-server API calls

Integration Flow

The integration process consists of four main steps:

Create Pre-Registration Record: Call the server-to-server API to register the relationship between the phone number and the target project.

Redirect to Meta Onboarding: Redirect the customer to the Meta onboarding URL so they can register their WhatsApp Business Account.

Background Mapping: SendZen automatically catches the Meta registration events, matches the phone number, links it to the pre-registered project, and cleans up the pre-registration record.

Verify Phone Number: Call the WABA API to verify that the phone number has been successfully added.

Step 1: Create Pre-Registration Record

Before sending your customer to Meta onboarding, register their phone number and project mapping in SendZen.

API Endpoint

POST https://api.sendzen.io/v1/waba/pre_registration

Authentication

Use your Partner API Key for authentication. Include it in the request headers:

Authorization: Bearer YOUR_PARTNER_API_KEY

Request Body

Parameter	Type	Required	Description
`project_id`	integer	Yes	The ID of the target project in SendZen where this phone number should be assigned
`phone_number`	string	Yes	The WhatsApp phone number of the customer (with country code, e.g., `"1234567890"`)

Example Request

{
  "project_id": 12345,
  "phone_number": "12345678901"
}

Response

Upon successful API call, you will receive a 201 Created status with the following response body:

{
  "id": 1,
  "project_id": 12345,
  "phone_number": "12345678901"
}

Step 2: Redirect to Meta Onboarding

After successfully creating the pre-registration record, display a button or link in your partner panel interface to redirect the customer to the Meta onboarding page.

Meta Onboarding URL

Use the following URL for the redirection:

https://business.facebook.com/messaging/whatsapp/onboard/?app_id=1084368675447421&config_id=1394853824461250&extras=%7B%22featureType%22%3A%22whatsapp_business_app_onboarding%22%2C%22sessionInfoVersion%22%3A%223%22%2C%22version%22%3A%22v4-public-preview%22%2C%22features%22%3A[%7B%22name%22%3A%22marketing_messages_lite%22%7D]%7D

Example UI Workflow

The admin/partner enters the phone number in Option 2 panel.

Clicking "Pre-register & Onboard" triggers the server-to-server call.

Upon receiving the successful API response, the partner panel enables a button that redirects the user to the Meta onboarding URL in a new tab or via a direct window location change.

Step 3: Background Mapping and Cleanup

Once the customer completes the onboarding process on the Meta onboarding page, SendZen automatically catches the Meta registration events, matches the phone number, links it to the pre-registered project, and cleans up the pre-registration record.

Step 4: Verify Phone Number

Finally, call the WABA API to verify that the phone number is successfully added and active.

Complete Integration Example

Here is a backend Node.js and frontend Javascript example to illustrate the integration flow:

Server-Side (Node.js/Express)

Call the SendZen API from your backend to protect your API credentials.

Client-Side (HTML / Javascript)

Error Handling

API Errors

If the pre-registration request fails, the API returns a standard error format:

{
  "error": "Failed to create pre-registration record.",
  "message": "Database failed to insert record."
}

Common HTTP status codes returned:

400 Bad Request: Invalid or missing parameters (e.g., missing phone_number or project_id).

401 Unauthorized: Invalid or missing Partner API key in authorization header.

500 Internal Server Error: Database connection or routing issues.

Best Practices

Secure Your Partner API Key: Never call the pre-registration endpoint directly from frontend code. Always proxy this request through your server backend.

Format Phone Numbers: While SendZen cleans up special characters automatically, validating that the phone number includes the country code and has correct length prevents typos.

Verify Project Status: Ensure the project_id you are passing to the API is valid and belongs to your partner organization.

Support

For technical support or questions about integration, please contact:

Email: hi@sendzen.io

Documentation: https://www.sendzen.io/docs

Changelog

v1.0 (Current): Initial WABA Pre-registration integration guide.

Partner Integration Guide - Option 2: WABA Pre-Registration Integration

Prerequisites#

Integration Flow#

Step 1: Create Pre-Registration Record#

API Endpoint#

Authentication#

Request Body#

Example Request#

Response#

Step 2: Redirect to Meta Onboarding#

Meta Onboarding URL#

Example UI Workflow#

Step 3: Background Mapping and Cleanup#

Step 4: Verify Phone Number#

Complete Integration Example#

Server-Side (Node.js/Express)#

Client-Side (HTML / Javascript)#

Error Handling#

API Errors#

Best Practices#

Support#

Changelog#