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

$invitation = $client->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => '[e-mail]',
    '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:

$invitation = $client->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => '[e-mail]',
    'expiresInDays' => 7,
    'allowedPhoneCountries' => ['US', 'MX'],
]);

With Pre-assigned Phone Number

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

$invitation = $client->invitations->create([
    'clientName' => 'Acme Corp',
    'clientEmail' => '[e-mail]',
    'phoneNumberId' => 'pn_abc123',
]);

Get Invitation

$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

$result = $client->invitations->list([]);

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

Filter by Status

$result = $client->invitations->list([
    'status' => 'pending',
    'limit' => 50,
]);

Pagination

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

$result = $client->invitations->cancel([
    'invitationId' => 'jh7am5bng9p3v2x1k4r8',
]);

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

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

After Completion

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

$result = $client->invitations->get([
    'invitationId' => 'jh7am5bng9p3v2x1k4r8',
]);

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

Full Example

<?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', '[e-mail]');
// Later...
checkInvitationStatus($client, $invitation->id);