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.

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.

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

sequenceDiagram
    participant Partner as Your App
    participant Zavu as Zavu API
    participant Client as Client
    participant Meta as Meta

    Partner->>Zavu: POST /v1/invitations
    Zavu-->>Partner: { url, token }
    Partner->>Client: Share invitation URL
    Client->>Zavu: Open invitation page
    Client->>Meta: Complete embedded signup
    Meta-->>Zavu: OAuth callback
    Zavu->>Zavu: Create sender
    Client-->>Partner: WhatsApp connected!

Create an Invitation

Client provides their own number

terminalCopy
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:

terminalCopy
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)

terminalCopy
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

JSONCopy
{
  "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

List Invitations

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

Filter by status:

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

Get Invitation Details

terminalCopy
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:

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

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:

terminalCopy
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

TypeScriptCopy
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