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

```typescript theme={null}
const invitation = await zavu.invitations.create({
  clientName: "Acme Corp",
  clientEmail: "contact@acme.com",
  expiresInDays: 14,
});

console.log(invitation.id);  // jh7am5bng9p3v2x1k4r8
console.log(invitation.url); // https://dashboard.zavu.dev/invite/abc123xyz
console.log(invitation.status); // pending
```

### With Phone Number Restrictions

Restrict which countries the client can register phone numbers from:

```typescript theme={null}
const invitation = await zavu.invitations.create({
  clientName: "Acme Corp",
  clientEmail: "contact@acme.com",
  expiresInDays: 7,
  allowedPhoneCountries: ["US", "MX"],
});
```

## Get Invitation

```typescript theme={null}
const { invitation } = await zavu.invitations.get({
  invitationId: "jh7am5bng9p3v2x1k4r8",
});

console.log(invitation.status);      // pending | in_progress | completed | expired | cancelled
console.log(invitation.clientName);  // Acme Corp
console.log(invitation.senderId);    // null (until completed)
console.log(invitation.expiresAt);   // 2025-01-15T00:00:00.000Z
```

## List Invitations

```typescript theme={null}
const { items, nextCursor } = await zavu.invitations.list({});

for (const invitation of items) {
  console.log(invitation.id, invitation.clientName, invitation.status);
}
```

### Filter by Status

```typescript theme={null}
const { items } = await zavu.invitations.list({
  status: "pending",
  limit: 50,
});
```

### Pagination

```typescript theme={null}
let cursor: string | undefined;

do {
  const result = await zavu.invitations.list({
    limit: 50,
    cursor,
  });

  for (const invitation of result.items) {
    console.log(invitation.id);
  }

  cursor = result.nextCursor ?? undefined;
} while (cursor);
```

## Cancel Invitation

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

```typescript theme={null}
const { invitation } = await zavu.invitations.cancel({
  invitationId: "jh7am5bng9p3v2x1k4r8",
});

console.log(invitation.status); // 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:

```typescript theme={null}
const { invitation } = await zavu.invitations.get({
  invitationId: "jh7am5bng9p3v2x1k4r8",
});

if (invitation.status === "completed" && invitation.senderId) {
  // Use the sender to send messages
  await zavu.messages.send({
    to: "+14155551234",
    channel: "whatsapp",
    messageType: "template",
    content: {
      templateId: "tmpl_xyz789",
      templateVariables: {
        "1": "John",
      },
    },
  }, {
    headers: {
      "Zavu-Sender": invitation.senderId,
    },
  });
}
```

## Full Example

```typescript theme={null}
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

async function onboardClient(clientName: string, clientEmail: string) {
  // Create invitation
  const invitation = await zavu.invitations.create({
    clientName,
    clientEmail,
    expiresInDays: 7,
  });

  console.log(`Send this link to ${clientName}: ${invitation.url}`);

  return invitation;
}

async function checkInvitationStatus(invitationId: string) {
  const { invitation } = await zavu.invitations.get({ invitationId });

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

  return invitation;
}

// Usage
const invitation = await onboardClient("Acme Corp", "contact@acme.com");
// Later...
await checkInvitationStatus(invitation.id);
```