Skip to content
DashboardGet API key

Create invitation

View .md
POST

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.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json · optional

  • clientNamestring

    Name of the client being invited.

    Limitsmax length 100
  • clientEmailstring<email>

    Email of the client being invited.

  • clientPhonestring

    Phone number of the client in E.164 format.

  • phoneNumberIdstring

    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.

  • expiresInDaysinteger

    Number of days until the invitation expires.

    Default7
    Limitsmin 1 · max 30
  • allowedPhoneCountriesstring[]

    ISO country codes for allowed phone numbers. Only valid when connectionType is whatsapp_waba — sending it with messenger returns 400.

  • connectionTypestring

    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.

    One ofwhatsapp_wabamessenger
    Defaultwhatsapp_waba

Responses

201Invitation created.
  • invitationobjectrequired
    19 properties
    • idstringrequired
    • urlstringrequired

      Full URL to share with the client.

    • tokenstringrequired

      Unique invitation token.

    • clientNamestringnullable
    • clientEmailstringnullable
    • clientPhonestringnullable
    • phoneNumberIdstringnullable

      ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null for messenger invitations.

    • connectionTypestring

      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).

      One ofwhatsapp_wabamessenger
    • statusstringrequired

      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.

      One ofpendingin_progresscompletedexpiredcancelledfailed
    • senderIdstringnullable

      ID of the sender created when invitation is completed.

    • connectedAccountobjectnullable

      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.

      3 properties
      • channelstringrequired
        One ofwhatsappmessenger
      • idstringrequired

        Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.

      • namestringnullable

        Display name of the connected account: the WhatsApp verified name, or the Facebook Page name.

    • failureReasonstringnullable

      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.

    • failedAtstring<date-time>nullable
    • expiresAtstring<date-time>required
    • viewedAtstring<date-time>nullable
    • startedAtstring<date-time>nullable
    • completedAtstring<date-time>nullable
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
400Invalid request.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject