# Partner Invitations

> Onboard clients to connect their WhatsApp Business account or Facebook Page to your Zavu project via 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 |

> **Note:**
> 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`.

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

```bash
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)

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

```json
{
  "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

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

Filter by status:

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

## Get Invitation Details

```bash
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:

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

> **Note:**
> 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:

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

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