Onboarding Clients via API

This guide shows you how to automate client onboarding using the Zavu API to create partner invitations programmatically.

Overview

The Partner Invitations API allows you to:

Create invitation links programmatically
Integrate client onboarding into your own application
Optionally pre-assign phone numbers to invitations
Track invitation status and completion

Creating an Invitation

Basic Invitation

Create an invitation where the client provides their own phone number:

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

const invitation = await zavu.invitations.create({
  clientName: 'Acme Corp',
  clientEmail: 'contact@acme.com',
  expiresInDays: 7,
});

console.log('Invitation URL:', invitation.url);
console.log('Token:', invitation.token);
console.log('Expires:', invitation.expiresAt);

Response

{
  "invitation": {
    "id": "jh7am5bng9p3v2x1k4r8",
    "url": "https://dashboard.zavu.dev/invite/abc123xyz",
    "token": "abc123xyz",
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "phoneNumberId": null,
    "status": "pending",
    "senderId": null,
    "expiresAt": "2025-01-22T00:00:00.000Z",
    "createdAt": "2025-01-15T12:00:00.000Z"
  }
}

With Pre-assigned Phone Number

Pre-assign a Zavu phone number that the client will register with WhatsApp:

// First, purchase a phone number
const phoneNumber = await zavu.phoneNumbers.purchase({
  phoneNumber: '+14155551234',
  name: 'Client: Acme Corp',
});

// Then create the invitation with the phone number
const invitation = await zavu.invitations.create({
  clientName: 'Acme Corp',
  clientEmail: 'contact@acme.com',
  phoneNumberId: phoneNumber.id,
  expiresInDays: 14,
});

console.log('Invitation URL:', invitation.url);

When you pre-assign a phone number, the invitation page will show the number and automatically display the verification code when it’s received via phone call.

Create Parameters

Parameter	Type	Required	Description
`clientName`	string	No	Name to identify the client (max 100 chars)
`clientEmail`	string	No	Client’s email address
`clientPhone`	string	No	Client’s phone number (E.164 format)
`phoneNumberId`	string	No	Pre-assign a Zavu phone number
`expiresInDays`	integer	No	Link validity in days (1-30, default: 7)

Listing Invitations

Retrieve all invitations for your project:

// List all invitations
const { items } = await zavu.invitations.list({});

// Filter by status
const pending = await zavu.invitations.list({
  status: 'pending',
});

for (const inv of pending.items) {
  console.log(inv.clientName, inv.status, inv.url);
}

List Parameters

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `in_progress`, `completed`, `expired`, `cancelled`
`limit`	integer	Results per page (default: 50, max: 100)
`cursor`	string	Pagination cursor

Getting Invitation Details

Retrieve details for a specific invitation:

const invitation = await zavu.invitations.get({
  invitationId: 'jh7am5bng9p3v2x1k4r8',
});

console.log('Status:', invitation.status);
console.log('Client:', invitation.clientName);

if (invitation.status === 'completed') {
  console.log('Sender ID:', invitation.senderId);
}

Response Fields

Field	Type	Description
`id`	string	Unique invitation ID
`url`	string	Full invitation URL to share with client
`token`	string	URL token (part of the URL)
`clientName`	string	Client name
`clientEmail`	string	Client email
`phoneNumberId`	string	Pre-assigned phone number ID (if any)
`status`	string	Current status
`senderId`	string	Created sender ID (when completed)
`expiresAt`	string	Expiration timestamp
`viewedAt`	string	When client first viewed the invitation
`startedAt`	string	When client started the setup
`completedAt`	string	When setup was completed

Cancelling an Invitation

Cancel an invitation to prevent it from being used:

await zavu.invitations.cancel({
  invitationId: 'jh7am5bng9p3v2x1k4r8',
});

You cannot cancel a completed invitation. Once a sender is created, manage it through the Senders API instead.

Invitation Lifecycle

Integration Examples

SaaS Onboarding Flow

Integrate WhatsApp setup into your SaaS onboarding:

async function onboardNewCustomer(customer: Customer) {
  // 1. Create the customer in your system
  await createCustomer(customer);

  // 2. Create a Zavu invitation
  const invitation = await zavu.invitations.create({
    clientName: customer.companyName,
    clientEmail: customer.email,
    expiresInDays: 14,
  });

  // 3. Send onboarding email with the invitation link
  await sendEmail({
    to: customer.email,
    subject: 'Connect Your WhatsApp Business',
    body: `
      Welcome to our platform!

      To enable WhatsApp messaging, please complete the setup:
      ${invitation.url}

      This link expires in 14 days.
    `,
  });

  // 4. Store the invitation ID for tracking
  await saveInvitationId(customer.id, invitation.id);
}

Polling for Completion

Check if a client has completed the setup:

async function checkInvitationStatus(invitationId: string) {
  const invitation = await zavu.invitations.get({ invitationId });

  switch (invitation.status) {
    case 'completed':
      console.log('Client connected! Sender ID:', invitation.senderId);
      // Start sending messages through this sender
      break;
    case 'pending':
    case 'in_progress':
      console.log('Still waiting for client to complete setup');
      break;
    case 'expired':
      console.log('Invitation expired, creating new one...');
      // Create a new invitation
      break;
    case 'cancelled':
      console.log('Invitation was cancelled');
      break;
  }

  return invitation;
}

Webhook Integration

Set up a webhook to be notified when invitations are completed:

// In your webhook handler
app.post('/webhooks/zavu', async (req, res) => {
  const event = req.body;

  if (event.type === 'sender.created') {
    // A new sender was created (possibly from an invitation)
    const sender = event.data;
    console.log('New sender:', sender.id, sender.phoneNumber);

    // Update your system
    await updateCustomerWhatsAppStatus(sender.phoneNumber, 'connected');
  }

  res.status(200).send('OK');
});

Error Handling

try {
  const invitation = await zavu.invitations.create({
    clientName: 'Acme Corp',
    phoneNumberId: 'pn_invalid',
  });
} catch (error) {
  if (error.code === 'not_found') {
    console.error('Phone number not found');
  } else if (error.code === 'invalid_request') {
    console.error('Invalid request:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Errors

Code	Description
`not_found`	Phone number or invitation not found
`invalid_request`	Invalid parameters
`phone_number_wrong_team`	Phone number belongs to a different team
`already_completed`	Cannot cancel a completed invitation

Best Practices

Store Invitation IDs

Save the invitation ID in your database to track status and link to your customer records.

Set Reminders

If an invitation is pending for several days, send a reminder to your client.

Handle Expiration

Monitor for expired invitations and automatically create new ones if needed.

Use Webhooks

Set up webhooks to get real-time notifications when senders are created.

Rate Limits

The Invitations API has the following rate limits:

Endpoint	Limit
Create invitation	100 requests/minute
List invitations	200 requests/minute
Get invitation	200 requests/minute
Cancel invitation	100 requests/minute

Next Steps

Dashboard Guide

Learn to create invitations from the dashboard

Senders API

Work with senders created from invitations

Send WhatsApp Messages

Start sending messages through your new senders

Phone Numbers

Purchase phone numbers to pre-assign to invitations

Getting Started

Concepts

Guides

Onboarding Clients via API

Overview

Creating an Invitation

Basic Invitation

Response

With Pre-assigned Phone Number

Create Parameters

Listing Invitations

List Parameters

Getting Invitation Details

Response Fields

Cancelling an Invitation

Invitation Lifecycle

Integration Examples

SaaS Onboarding Flow

Polling for Completion

Webhook Integration

Error Handling

Common Errors

Best Practices

Store Invitation IDs

Set Reminders

Handle Expiration

Use Webhooks

Rate Limits

Next Steps

Dashboard Guide

Senders API

Send WhatsApp Messages

Phone Numbers

Getting Started

Concepts

Guides

​Overview

​Creating an Invitation

​Basic Invitation

​Response

​With Pre-assigned Phone Number

​Create Parameters

​Listing Invitations

​List Parameters

​Getting Invitation Details

​Response Fields

​Cancelling an Invitation

​Invitation Lifecycle

​Integration Examples

​SaaS Onboarding Flow

​Polling for Completion

​Webhook Integration

​Error Handling

​Common Errors

​Best Practices

Store Invitation IDs

Set Reminders

Handle Expiration

Use Webhooks

​Rate Limits

​Next Steps

Dashboard Guide

Senders API

Send WhatsApp Messages

Phone Numbers

Overview

Creating an Invitation

Basic Invitation

Response

With Pre-assigned Phone Number

Create Parameters

Listing Invitations

List Parameters

Getting Invitation Details

Response Fields

Cancelling an Invitation

Invitation Lifecycle

Integration Examples

SaaS Onboarding Flow

Polling for Completion

Webhook Integration

Error Handling

Common Errors

Best Practices

Rate Limits

Next Steps