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

invitation = client.invitations.create(
  client_name: "Acme Corp",
  client_email: "[e-mail]",
  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:

invitation = client.invitations.create(
  client_name: "Acme Corp",
  client_email: "[e-mail]",
  expires_in_days: 7,
  allowed_phone_countries: ["US", "MX"]
)

Get Invitation

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

result = client.invitations.list

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

Filter by Status

result = client.invitations.list(
  status: "pending",
  limit: 50
)

Pagination

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:

result = client.invitations.cancel(invitation_id: "jh7am5bng9p3v2x1k4r8")

puts result.invitation.status # 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(invitation_id: "jh7am5bng9p3v2x1k4r8")

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

Full Example

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", "[e-mail]")
# Later...
check_invitation_status(client, invitation.id)