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

```ruby theme={null}
invitation = client.invitations.create(
  client_name: "Acme Corp",
  client_email: "contact@acme.com",
  expires_in_days: 14
)

puts invitation.id     # jh7am5bng9p3v2x1k4r8
puts invitation.url    # https://dashboard.zavu.dev/invite/abc123xyz
puts invitation.status # pending
```

### With Phone Number Restrictions

Restrict which countries the client can register phone numbers from:

```ruby theme={null}
invitation = client.invitations.create(
  client_name: "Acme Corp",
  client_email: "contact@acme.com",
  expires_in_days: 7,
  allowed_phone_countries: ["US", "MX"]
)
```

## Get Invitation

```ruby theme={null}
result = client.invitations.get(invitation_id: "jh7am5bng9p3v2x1k4r8")

puts result.invitation.status      # pending | in_progress | completed | expired | cancelled
puts result.invitation.client_name # Acme Corp
puts result.invitation.sender_id   # nil (until completed)
puts result.invitation.expires_at  # 2025-01-15T00:00:00.000Z
```

## List Invitations

```ruby theme={null}
result = client.invitations.list

result.items.each do |invitation|
  puts "#{invitation.id} #{invitation.client_name} #{invitation.status}"
end
```

### Filter by Status

```ruby theme={null}
result = client.invitations.list(
  status: "pending",
  limit: 50
)
```

### Pagination

```ruby theme={null}
cursor = nil
loop do
  result = client.invitations.list(
    limit: 50,
    cursor: cursor
  )

  result.items.each { |invitation| puts invitation.id }

  cursor = result.next_cursor
  break if cursor.nil?
end
```

## Cancel Invitation

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

```ruby theme={null}
result = client.invitations.cancel(invitation_id: "jh7am5bng9p3v2x1k4r8")

puts result.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:

```ruby theme={null}
result = client.invitations.get(invitation_id: "jh7am5bng9p3v2x1k4r8")

if result.invitation.status == "completed" && result.invitation.sender_id
  # Use the sender to send messages
  client.messages.send(
    to: "+14155551234",
    channel: "whatsapp",
    message_type: "template",
    content: {
      "template_id" => "tmpl_xyz789",
      "template_variables" => {
        "1" => "John"
      }
    },
    zavu_sender: result.invitation.sender_id
  )
end
```

## Full Example

```ruby theme={null}
require "zavudev"

client = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)

def onboard_client(client, client_name, client_email)
  # Create invitation
  invitation = client.invitations.create(
    client_name: client_name,
    client_email: client_email,
    expires_in_days: 7
  )

  puts "Send this link to #{client_name}: #{invitation.url}"
  invitation
end

def check_invitation_status(client, invitation_id)
  result = client.invitations.get(invitation_id: invitation_id)
  invitation = result.invitation

  case invitation.status
  when "pending"
    puts "Waiting for client to start signup"
  when "in_progress"
    puts "Client is completing the signup flow"
  when "completed"
    puts "Success! Sender ID: #{invitation.sender_id}"
  when "expired"
    puts "Invitation expired, create a new one"
  when "cancelled"
    puts "Invitation was cancelled"
  end

  invitation
end

# Usage
invitation = onboard_client(client, "Acme Corp", "contact@acme.com")
# Later...
check_invitation_status(client, invitation.id)
```