---
title: "Create invitation"
method: POST
path: "/v1/invitations"
---

# Create invitation

`POST /v1/invitations`

Create a partner invitation link for a client to connect a Meta channel. The client opens the returned `url` and authorizes with Meta; the resulting sender is created in your project when they finish, and the invitation transitions to `completed`.

`connectionType` picks the channel:
- `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp Business Account.
- `messenger`: the client picks a Facebook Page they administer; its Messenger inbox (including Marketplace chats) is routed to Zavu.

One invitation connects one channel — create one per channel to onboard a client on several. `phoneNumberId` and `allowedPhoneCountries` apply to `whatsapp_waba` only.

## Request body

- InvitationCreateRequest
  - `clientName` string — Name of the client being invited.
  - `clientEmail` string, email — Email of the client being invited.
  - `clientPhone` string — Phone number of the client in E.164 format.
  - `phoneNumberId` string — ID of a Zavu phone number to pre-assign for WhatsApp registration. If provided, the client will use this number instead of their own. Only valid when `connectionType` is `whatsapp_waba` — sending it with `messenger` returns 400, since a Facebook Page has no phone number.
  - `expiresInDays` integer — Number of days until the invitation expires.
  - `allowedPhoneCountries` string[] — ISO country codes for allowed phone numbers. Only valid when `connectionType` is `whatsapp_waba` — sending it with `messenger` returns 400.
  - `connectionType` 'whatsapp_waba' | 'messenger' — Which Meta channel the client connects, and how. - `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp Business Account. Accepts `phoneNumberId` and `allowedPhoneCountries`. - `messenger`: the client authorizes with Facebook and picks a Facebook Page they administer. The Page's Messenger inbox — including Marketplace chats — is routed to Zavu. They must be an admin of at least one Page. A Page can only be connected to one Zavu project at a time: if the client picks a Page that another project already connected, the newer connection wins and the older one is disconnected. One invitation connects one channel. To onboard a client on several channels, create one invitation per channel; each completes into its own sender.

## Response `201`

Invitation created.

- InvitationResponse
  - `invitation` Invitation, required
    - `id` string, required
    - `url` string, required — Full URL to share with the client.
    - `token` string, required — Unique invitation token.
    - `clientName` string, nullable
    - `clientEmail` string, nullable
    - `clientPhone` string, nullable
    - `phoneNumberId` string, nullable — ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null for `messenger` invitations.
    - `connectionType` 'whatsapp_waba' | 'messenger' — Which Meta channel the client connects: `whatsapp_waba` (official WhatsApp Cloud API via embedded signup) or `messenger` (a Facebook Page's Messenger inbox, including Marketplace chats).
    - `status` 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed', required — Current status of the partner invitation. `failed` means the client started the connection and it did not finish (they cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed invitation is still usable: the same link can be retried, and it moves back to `in_progress` when the client tries again.
    - `senderId` string, nullable — ID of the sender created when invitation is completed.
    - `connectedAccount` object, nullable — The account the client linked, populated once the invitation is `completed`. Null before that. Use it to show the partner what was connected without fetching the sender.
      - `channel` 'whatsapp' | 'messenger', required
      - `id` string, required — Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.
      - `name` string, nullable — Display name of the connected account: the WhatsApp verified name, or the Facebook Page name.
    - `failureReason` string, nullable — Stable code for why the last attempt failed, present when `status` is `failed`. Values include `fb_cancelled` (client closed Meta's dialog), `fb_not_authorized` (permission denied), `signup_abandoned` (started but never finished), `meta_no_pages` (the client administers no Facebook Page), and `internal_error`. Treat unknown codes as a generic failure.
    - `failedAt` string, date-time, nullable
    - `expiresAt` string, date-time, required
    - `viewedAt` string, date-time, nullable
    - `startedAt` string, date-time, nullable
    - `completedAt` string, date-time, nullable
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400` — Invalid request.
- `401` — Unauthorized.

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/revisions/4dacdff2adf8/schema)