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

> Partner invitations with the PHP SDK

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