Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Phone Number Options

You have two options for the WhatsApp phone number:
  1. Client provides their own number: The client uses their existing phone number to register for WhatsApp Business
  2. 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 $ZAVU_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 $ZAVU_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.

​
Response

{
  "invitation": {
    "id": "jh7am5bng9p3v2x1k4r8",
    "url": "https://dashboard.zavu.dev/invite/abc123xyz",
    "token": "abc123xyz",
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "clientPhone": null,
    "phoneNumberId": null,
    "status": "pending",
    "senderId": 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 will complete Meta’s embedded signup flow to connect their WhatsApp Business account.

​
Invitation Lifecycle

StatusDescription
pendingInvitation created, waiting for client
in_progressClient started the signup flow
completedWhatsApp connected, sender created
expiredInvitation expired before completion
cancelledInvitation was cancelled

​
List Invitations

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

​
Get Invitation Details

curl https://api.zavu.dev/v1/invitations/jh7am5bng9p3v2x1k4r8 \
  -H "Authorization: Bearer $ZAVU_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 $ZAVU_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:
  1. A new sender is created in your project with WhatsApp enabled
  2. The sender’s phone number is the client’s registered WhatsApp number
  3. The invitation status changes to completed
  4. 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 $ZAVU_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);

​
Best Practices

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