Partner Invitations

Partner invitations allow you to generate links that your clients can use to connect a Meta channel to your project. When a client completes the flow, a new sender is automatically created in your project.

Channels

connectionType picks what the client connects. One invitation connects one channel; create one invitation per channel to onboard a client on several.

`connectionType`	What the client connects
`whatsapp_waba` (default)	An official WhatsApp Business Account, through Meta’s embedded signup
`messenger`	A Facebook Page they administer. Its Messenger inbox, including Marketplace chats, is routed to Zavu

A Facebook Page can only be connected to one Zavu project at a time. If your client picks a Page that another project already connected, the newer connection wins and the older one is disconnected.

Phone Number Options

These apply to whatsapp_waba only. A Facebook Page has no phone number, so sending phoneNumberId or allowedPhoneCountries with connectionType: "messenger" returns 400.

Client provides their own number: The client uses their existing phone number to register for WhatsApp Business
Pre-assign a Zavu number: You purchase a phone number from Zavu and assign it to the invitation. The client registers this number under their WhatsApp Business Account

Use Cases

Agencies: Onboard client WhatsApp accounts without accessing their Facebook credentials
SaaS platforms: Let customers self-service WhatsApp setup
Resellers: Manage multiple client WhatsApp accounts under one project
Managed services: Provision phone numbers and let clients complete the WhatsApp verification

How It Works

Create an Invitation

Client provides their own number

curl -X POST https://api.zavu.dev/v1/invitations \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "expiresInDays": 14
  }'

Pre-assign a Zavu phone number

First, purchase a phone number from Zavu, then create the invitation with the phoneNumberId:

curl -X POST https://api.zavu.dev/v1/invitations \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "phoneNumberId": "pn_abc123",
    "expiresInDays": 14
  }'

When a phone number is pre-assigned, the client will see the number on the invitation page and use it during the WhatsApp registration. The verification code will be received via phone call to that number.

Connect a Facebook Page (Messenger)

curl -X POST https://api.zavu.dev/v1/invitations \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "connectionType": "messenger"
  }'

The client authorizes with Facebook, picks a Page they administer, and the resulting sender lands in your project with the Messenger channel enabled.

Response

{
  "invitation": {
    "id": "jh7am5bng9p3v2x1k4r8",
    "url": "https://dashboard.zavu.dev/invite/abc123xyz",
    "token": "abc123xyz",
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "clientPhone": null,
    "phoneNumberId": null,
    "connectionType": "whatsapp_waba",
    "status": "pending",
    "senderId": null,
    "connectedAccount": null,
    "failureReason": null,
    "failedAt": null,
    "expiresAt": "2025-01-15T00:00:00.000Z",
    "viewedAt": null,
    "startedAt": null,
    "completedAt": null,
    "createdAt": "2025-01-01T12:00:00.000Z",
    "updatedAt": "2025-01-01T12:00:00.000Z"
  }
}

Share the url with your client. They complete Meta’s authorization to connect the channel. Once done, status is completed, senderId points at the new sender, and connectedAccount reports what was linked: the WhatsApp number or the Facebook Page.

Invitation Lifecycle

Status	Description
`pending`	Invitation created, waiting for client
`in_progress`	Client started the signup flow
`completed`	WhatsApp connected, sender created
`expired`	Invitation expired before completion
`cancelled`	Invitation was cancelled
`failed`	The client started and did not finish. `failureReason` says why, and the same link can be retried

List Invitations

curl https://api.zavu.dev/v1/invitations \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Filter by status:

curl "https://api.zavu.dev/v1/invitations?status=completed" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Get Invitation Details

curl https://api.zavu.dev/v1/invitations/jh7am5bng9p3v2x1k4r8 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Cancel an Invitation

Cancel an active invitation to prevent the client from using it:

curl -X POST https://api.zavu.dev/v1/invitations/jh7am5bng9p3v2x1k4r8/cancel \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

You cannot cancel a completed invitation. Once a sender is created, you can delete it through the senders API.

After Completion

When a client completes the signup flow:

A new sender is created in your project with WhatsApp enabled
The sender’s phone number is the client’s registered WhatsApp number
The invitation status changes to completed
The senderId field contains the ID of the created sender

You can then use this sender to send WhatsApp messages on behalf of your client:

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Zavu-Sender: snd_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "channel": "whatsapp",
    "messageType": "template",
    "content": {
      "templateId": "tmpl_xyz789",
      "templateVariables": {
        "1": "John"
      }
    }
  }'

SDK Examples

import Zavudev from '@zavudev/sdk';

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

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

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

// List invitations
const { items } = await zavu.invitations.list({ status: 'pending' });

// Cancel invitation
await zavu.invitations.cancel(invitation.id);

require 'zavudev'

zavu = Zavudev::Client.new(
  api_key: ENV['ZAVUDEV_API_KEY']
)

# Create invitation
invitation = zavu.invitations.create(
  client_name: "Acme Corp",
  client_email: "contact@acme.com",
  expires_in_days: 14
)

puts "Share this URL: #{invitation.url}"

# List invitations
result = zavu.invitations.list(status: "pending")

# Cancel invitation
zavu.invitations.cancel(invitation.id)

$zavu = new Zavudev\Client(['apiKey' => getenv('ZAVUDEV_API_KEY')]);

// Create invitation
$invitation = $zavu->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => 'contact@acme.com',
    'expiresInDays' => 14,
]);

echo "Share this URL: " . $invitation->url . "\n";

// List invitations
$result = $zavu->invitations->list(['status' => 'pending']);

// Cancel invitation
$zavu->invitations->cancel($invitation->id);

Best Practices

Set appropriate expiration: Use shorter expirations (3-7 days) for urgent onboarding
Track client info: Include clientName and clientEmail for easier management
Monitor status: Check for expired or cancelled invitations and resend if needed
Webhooks: Configure webhooks on the resulting sender to receive inbound messages

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Partner Invitations

Channels

Phone Number Options

Use Cases

How It Works

Create an Invitation

Client provides their own number

Pre-assign a Zavu phone number

Connect a Facebook Page (Messenger)

Response

Invitation Lifecycle

List Invitations

Get Invitation Details

Cancel an Invitation

After Completion

SDK Examples

Best Practices

​Channels

​Phone Number Options

​Use Cases

​How It Works

​Create an Invitation

​Client provides their own number

​Pre-assign a Zavu phone number

​Connect a Facebook Page (Messenger)

​Response

​Invitation Lifecycle

​List Invitations

​Get Invitation Details

​Cancel an Invitation

​After Completion

​SDK Examples

​Best Practices

Channels

Phone Number Options

Use Cases

How It Works

Create an Invitation

Client provides their own number

Pre-assign a Zavu phone number

Connect a Facebook Page (Messenger)

Response

Invitation Lifecycle

List Invitations

Get Invitation Details

Cancel an Invitation

After Completion

SDK Examples

Best Practices