Partner Integration Guide - Option 1 : Embedded Onboarding

This guide will help you integrate the SendZen embeddable onboarding component into your partner panel. This component allows you to onboard your customers and add their WhatsApp Business Account (WABA) details to your organization inside your own software.

Prerequisites

Partner API key from SendZen

Access to your partner panel/dashboard

Ability to make server-to-server API calls

Webhook endpoint (optional, but recommended) to receive activity logs

Integration Flow

The integration process consists of two main steps:

Generate Onboarding URL: Call the server-to-server API to get the iframe URL and customer credentials

Load and Handle Component: Embed the component using the iframe URL and handle the onboarding response

Step 1: Generate Onboarding URL

Before loading the component, you need to call the SendZen API to generate a unique onboarding URL for your customer.

API Endpoint

POST https://api.sendzen.io/v1/partner/onboard

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
`client_identifier`	string	Yes	Unique identifier for your customer. Can be your customer's email, user_id, mobile number, or any unique ID
`client_webhook_url`	string	Optional	Your webhook URL where you'll receive activity logs for this customer's account

Example Request

{
  "client_identifier": "customer-12345",
  "client_webhook_url": "https://your-domain.com/webhooks/sendzen"
}

Response

Upon successful API call, you'll receive the following response:

{
  "user_data": {
    "client_identifier": "customer-12345",
    "project_id": "proj_a1b2c3d4e5f6",
    "project_name": "Customer Project Name",
    "api_key": "sk_live_abc123xyz789"
  },
  "iframe_url": "https://app.sendzen.io/onboard/iframe?token=eyJhbGc...",
  "webhook": {
    "url": "https://your-domain.com/webhooks/sendzen",
    "valid": true,
    "detail": "Webhook URL is valid and configured"
  }
}

Response Fields Explained

`user_data`

Contains the customer's credentials and project information:

client_identifier: The unique identifier you provided

project_id: Unique project ID for this customer

project_name: Name of the project

api_key: Important: This is the API key specific to this customer. You must use this API key for all operations related to this customer (sending messages, viewing activity, etc.). Each customer will have a unique API key.

`iframe_url`

The URL to load the onboarding component. This URL is valid for 1 hour. After expiration, you need to call the API again to get a new iframe URL.

`webhook`

Contains webhook configuration details:

url: The webhook URL you provided (if any)

valid: Boolean indicating if the webhook URL is valid

detail: Additional details about the webhook configuration

Step 2: Load the Onboarding Component

Embedding the Component

Use the iframe_url from Step 1 to embed the onboarding component in your partner panel:

Important Notes

The iframe URL expires after 1 hour. If the user hasn't completed onboarding within this time, you'll need to generate a new URL by calling the API again.

Ensure the iframe has sufficient width and height to display the onboarding flow properly.

The component will handle the entire onboarding process internally.

Onboarding Process Reference

For detailed information about the onboarding steps your customers will go through, please refer to the WhatsApp Setup Documentation. This comprehensive guide covers the complete onboarding process, including:

Meta Business Account setup and verification

WhatsApp Business Account (WABA) and phone number registration

Compliance and verification requirements

Display name approval process

Scaling and account management

The component handles all these steps automatically. You only need to listen for the completion response as described in Step 3.

Step 3: Handle Onboarding Response

After your user completes the onboarding process, you'll receive a response indicating success or failure.

Success Response

When onboarding is completed successfully, you'll receive:

{
  "status": "completed",
  "project_id": "proj_a1b2c3d4e5f6",
  "client_identifier": "user-acc-12345-abcde",
  "waba_id": "109876543210987",
  "phone_number_id": "201234567890123"
}

Response Fields:

status: "completed" indicates successful onboarding

project_id: The project ID for this customer

client_identifier: The unique identifier you provided

waba_id: WhatsApp Business Account ID

phone_number_id: Phone number ID associated with the WABA

Failure Response

If onboarding fails or is cancelled, you'll receive:

{
  "status": "failed",
  "project_id": "proj_a1b2c3d4e5f6",
  "client_identifier": "user-acc-12345-abcde",
  "message": "User cancelled the authentication process."
}

Response Fields:

status: "failed" indicates onboarding was not completed

project_id: The project ID for this customer

client_identifier: The unique identifier you provided

message: Description of why the onboarding failed

Receiving Responses

You can receive these responses through:

PostMessage API: The iframe will send messages to the parent window using window.postMessage(). Listen for these messages:

Webhook: If you provided a client_webhook_url, you'll also receive webhook notifications about the onboarding status.

Using Customer API Key

Once a customer is successfully onboarded, you'll need to use the customer-specific API key (from user_data.api_key in Step 1) for all operations related to that customer:

Sending messages

Viewing account activity

Managing customer settings

Any other API operations for that specific customer

Example:

Complete Integration Example

Here's a complete example of how to integrate the component:

Error Handling

API Errors

If the API call fails, you may receive error responses:

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or expired"
}

Common error scenarios:

401 Unauthorized: Invalid or missing API key

400 Bad Request: Invalid request parameters (e.g., missing client_identifier)

429 Too Many Requests: Rate limit exceeded

500 Internal Server Error: Server-side error

Iframe URL Expiration

If the iframe URL expires (after 1 hour), the component will not load. You should:

Detect when the iframe fails to load

Call the API again to generate a new iframe URL

Update the iframe src attribute with the new URL

Best Practices

Store API Keys Securely: Never expose customer API keys in client-side code. Store them securely on your server.

Validate Webhook URLs: Ensure your webhook URL is accessible and returns a 200 status code for validation requests.

Handle Expiration: Implement logic to regenerate iframe URLs if they expire during the onboarding process.

Error Handling: Always implement proper error handling for API calls and onboarding responses.

Security: Verify the origin of postMessage events to prevent security vulnerabilities.

User Experience: Provide clear feedback to users during the onboarding process and handle both success and failure scenarios gracefully.

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 integration guide

Partner Integration Guide - Option 1 : Embedded Onboarding

Prerequisites#

Integration Flow#

Step 1: Generate Onboarding URL#

API Endpoint#

Authentication#

Request Body#

Example Request#

Response#

Response Fields Explained#

user_data#

iframe_url#

webhook#

Step 2: Load the Onboarding Component#

Embedding the Component#

Important Notes#

Onboarding Process Reference#

Step 3: Handle Onboarding Response#

Success Response#

Failure Response#

Receiving Responses#

Using Customer API Key#

Complete Integration Example#

Error Handling#

API Errors#

Iframe URL Expiration#

Best Practices#

Support#

Changelog#