> ## 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

> Onboard clients to connect their WhatsApp Business accounts to your Zavu project via partner invitations.

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

```mermaid theme={null}
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

```bash theme={null}
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`:

```bash theme={null}
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

```json theme={null}
{
  "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

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

## List Invitations

```bash theme={null}
curl https://api.zavu.dev/v1/invitations \
  -H "Authorization: Bearer $ZAVU_API_KEY"
```

Filter by status:

```bash theme={null}
curl "https://api.zavu.dev/v1/invitations?status=completed" \
  -H "Authorization: Bearer $ZAVU_API_KEY"
```

## Get Invitation Details

```bash theme={null}
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:

```bash theme={null}
curl -X POST https://api.zavu.dev/v1/invitations/jh7am5bng9p3v2x1k4r8/cancel \
  -H "Authorization: Bearer $ZAVU_API_KEY"
```

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

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

```bash theme={null}
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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  import os
  from zavudev import Zavudev

  zavu = Zavudev(
      api_key=os.environ.get("ZAVUDEV_API_KEY"),
  )

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

  print(f"Share this URL: {invitation.url}")

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

  # Cancel invitation
  zavu.invitations.cancel(invitation_id=invitation.id)
  ```

  ```ruby Ruby theme={null}
  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)
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "os"

      "github.com/zavudev/sdk-go"
  )

  func main() {
      client := zavudev.NewClient(
          zavudev.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")),
      )

      // Create invitation
      invitation, err := client.Invitations.Create(context.TODO(), zavudev.InvitationCreateParams{
          ClientName:    zavudev.String("Acme Corp"),
          ClientEmail:   zavudev.String("contact@acme.com"),
          ExpiresInDays: zavudev.Int(14),
      })

      fmt.Println("Share this URL:", invitation.URL)

      // List invitations
      result, err := client.Invitations.List(context.TODO(), zavudev.InvitationListParams{
          Status: zavudev.String("pending"),
      })

      // Cancel invitation
      _, err = client.Invitations.Cancel(context.TODO(), invitation.ID)
  }
  ```

  ```php PHP theme={null}
  $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);
  ```
</CodeGroup>

## 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