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

# Invitations

> Generate partner invitations for client WhatsApp Business onboarding via the Zavu PHP SDK. Track status and manage expiration.

Partner invitations allow you to generate links for clients to connect their WhatsApp Business accounts to your project.

## Create Invitation

```php theme={null}
$invitation = $client->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => 'contact@acme.com',
    'expiresInDays' => 14,
]);

echo $invitation->id . "\n";  // jh7am5bng9p3v2x1k4r8
echo $invitation->url . "\n"; // https://dashboard.zavu.dev/invite/abc123xyz
echo $invitation->status . "\n"; // pending
```

### With Phone Number Restrictions

Restrict which countries the client can register phone numbers from:

```php theme={null}
$invitation = $client->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => 'contact@acme.com',
    'expiresInDays' => 7,
    'allowedPhoneCountries' => ['US', 'MX'],
]);
```

### With Pre-assigned Phone Number

Assign a Zavu phone number for the client to use during WhatsApp registration:

```php theme={null}
$invitation = $client->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => 'contact@acme.com',
    'phoneNumberId' => 'pn_abc123',
]);
```

## Get Invitation

```php theme={null}
$result = $client->invitations->get([
    'invitationId' => 'jh7am5bng9p3v2x1k4r8',
]);

echo $result->invitation->status . "\n";      // pending | in_progress | completed | expired | cancelled
echo $result->invitation->clientName . "\n";  // Acme Corp
echo $result->invitation->senderId . "\n";    // null (until completed)
echo $result->invitation->expiresAt . "\n";   // 2025-01-15T00:00:00.000Z
```

## List Invitations

```php theme={null}
$result = $client->invitations->list([]);

foreach ($result->items as $invitation) {
    echo $invitation->id . " " . $invitation->clientName . " " . $invitation->status . "\n";
}
```

### Filter by Status

```php theme={null}
$result = $client->invitations->list([
    'status' => 'pending',
    'limit' => 50,
]);
```

### Pagination

```php theme={null}
$cursor = null;

do {
    $result = $client->invitations->list([
        'limit' => 50,
        'cursor' => $cursor,
    ]);

    foreach ($result->items as $invitation) {
        echo $invitation->id . "\n";
    }

    $cursor = $result->nextCursor;
} while ($cursor !== null);
```

## Cancel Invitation

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

```php theme={null}
$result = $client->invitations->cancel([
    'invitationId' => 'jh7am5bng9p3v2x1k4r8',
]);

echo $result->invitation->status . "\n"; // cancelled
```

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

## After Completion

When a client completes the signup flow, a sender is created in your project:

```php theme={null}
$result = $client->invitations->get([
    'invitationId' => 'jh7am5bng9p3v2x1k4r8',
]);

if ($result->invitation->status === 'completed' && $result->invitation->senderId) {
    // Use the sender to send messages
    $client->messages->send([
        'to' => '+14155551234',
        'channel' => 'whatsapp',
        'messageType' => 'template',
        'content' => [
            'templateId' => 'tmpl_xyz789',
            'templateVariables' => [
                '1' => 'John',
            ],
        ],
        'Zavu-Sender' => $result->invitation->senderId,
    ]);
}
```

## Full Example

```php theme={null}
<?php

use Zavudev\Client;

$client = new Client(
    apiKey: getenv('ZAVUDEV_API_KEY')
);

function onboardClient(Client $client, string $clientName, string $clientEmail): object
{
    // Create invitation
    $invitation = $client->invitations->create([
        'clientName' => $clientName,
        'clientEmail' => $clientEmail,
        'expiresInDays' => 7,
    ]);

    echo "Send this link to $clientName: " . $invitation->url . "\n";

    return $invitation;
}

function checkInvitationStatus(Client $client, string $invitationId): object
{
    $result = $client->invitations->get(['invitationId' => $invitationId]);
    $invitation = $result->invitation;

    switch ($invitation->status) {
        case 'pending':
            echo "Waiting for client to start signup\n";
            break;
        case 'in_progress':
            echo "Client is completing the signup flow\n";
            break;
        case 'completed':
            echo "Success! Sender ID: " . $invitation->senderId . "\n";
            break;
        case 'expired':
            echo "Invitation expired, create a new one\n";
            break;
        case 'cancelled':
            echo "Invitation was cancelled\n";
            break;
    }

    return $invitation;
}

// Usage
$invitation = onboardClient($client, 'Acme Corp', 'contact@acme.com');
// Later...
checkInvitationStatus($client, $invitation->id);
```