> ## 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. # Create invitation > 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. ## OpenAPI ````yaml /openapi.json post /v1/invitations openapi: 3.0.3 info: title: Zavu Unified Messaging Layer API version: 0.2.0 description: > Unified multi-channel messaging API for Zavu. Supported channels: - **SMS**: Simple text messages - **WhatsApp**: Rich messaging with media, buttons, lists, CTA URL buttons, location requests, and templates - **Telegram**: Bot messaging with text, media, and interactive elements - **Email**: Transactional emails via Amazon SES Design goals: - Simple `send()` entrypoint for developers - Project-level authentication via Bearer token - Support for all WhatsApp message types (text, image, video, audio, document, sticker, location, contact, buttons, list, cta_url, location_request, reaction, template) - If a non-text message type is sent, WhatsApp channel is used automatically - 24-hour WhatsApp conversation window enforcement - Universal `to` field accepts phone numbers (E.164), email addresses, or numeric chat IDs (Telegram/Instagram/Messenger) servers: - url: https://api.zavu.dev security: - bearerAuth: [] paths: /v1/invitations: post: summary: Create invitation description: >- 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. operationId: createInvitation requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/InvitationCreateRequest' examples: basic: summary: Basic invitation value: clientName: Acme Corp full: summary: Full invitation with all options value: clientName: Acme Corp clientEmail: contact@acme.com clientPhone: '+14155551234' expiresInDays: 14 allowedPhoneCountries: - US - MX messenger: summary: Messenger invitation (Facebook Page) value: clientName: Acme Corp clientEmail: contact@acme.com connectionType: messenger responses: '201': description: Invitation created. content: application/json: schema: $ref: '#/components/schemas/InvitationResponse' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: InvitationCreateRequest: type: object properties: clientName: type: string maxLength: 100 description: Name of the client being invited. example: Acme Corp clientEmail: type: string format: email description: Email of the client being invited. example: contact@acme.com clientPhone: type: string description: Phone number of the client in E.164 format. example: '+14155551234' phoneNumberId: type: string description: >- 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. example: pn_abc123 expiresInDays: type: integer minimum: 1 maximum: 30 default: 7 description: Number of days until the invitation expires. allowedPhoneCountries: type: array items: type: string minLength: 2 maxLength: 2 description: >- ISO country codes for allowed phone numbers. Only valid when `connectionType` is `whatsapp_waba` — sending it with `messenger` returns 400. example: - US - MX connectionType: type: string enum: - whatsapp_waba - messenger default: whatsapp_waba description: >- 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. InvitationResponse: type: object required: - invitation properties: invitation: $ref: '#/components/schemas/Invitation' Error: type: object required: - code - message properties: code: type: string example: invalid_request message: type: string example: Phone number is invalid details: type: object additionalProperties: true Invitation: type: object required: - id - url - token - status - expiresAt - createdAt - updatedAt properties: id: type: string example: inv_abc123 url: type: string description: Full URL to share with the client. example: https://dashboard.zavu.dev/invite/abc123xyz token: type: string description: Unique invitation token. clientName: type: string nullable: true clientEmail: type: string nullable: true clientPhone: type: string nullable: true phoneNumberId: type: string nullable: true description: >- ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null for `messenger` invitations. connectionType: type: string enum: - whatsapp_waba - messenger description: >- 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: $ref: '#/components/schemas/InvitationStatus' senderId: type: string nullable: true description: ID of the sender created when invitation is completed. connectedAccount: type: object nullable: true description: >- 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. required: - channel - id properties: channel: type: string enum: - whatsapp - messenger id: type: string description: >- Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID. name: type: string nullable: true description: >- Display name of the connected account: the WhatsApp verified name, or the Facebook Page name. failureReason: type: string nullable: true description: >- 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: type: string format: date-time nullable: true expiresAt: type: string format: date-time viewedAt: type: string format: date-time nullable: true startedAt: type: string format: date-time nullable: true completedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time InvitationStatus: type: string description: >- 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. enum: - pending - in_progress - completed - expired - cancelled - failed securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````