# About the Conferencing Provider Service Plugin

The Conferencing Provider service plugin lets you integrate a video conferencing provider, such as Zoom or Google Meet, with Wix conferencing. You implement the plugin, and Wix calls it to connect a resource to your provider and to create and manage conferences on its behalf. A resource is identified by an opaque ID that you key connections by. It's the ID of a [Bookings resource](fallback::https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2), such as the resource of a staff member or the site's default business resource.

Your implementation owns connection state: you store connections and any access tokens, and Wix reads the current state from you on demand. Wix doesn't store connections or conferences itself.

With the Conferencing Provider service plugin, you can:

- Connect a resource to your provider using OAuth or credentials.
- Create, update, retrieve, and delete conferences in your provider for a connected resource.
- Report a resource's connections and their status back to Wix.
- Disconnect a resource from your provider.

## How this service plugin works

Wix calls your implementation when a user connects or disconnects a conferencing account for a resource, and when a conference needs to be created, updated, retrieved, or deleted for a connected resource. Calls are synchronous, and Wix waits for your response before continuing. The connect methods Wix calls depend on the connection methods you advertise in your configuration, and Wix calls Update Conference only when your configuration sets `updateSupported = true`.

Wix passes the conference details you return, such as the join URL and password, to the Wix product that requested the conference, through the [Conferencing API](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conference-v1/introduction). Wix reads your connections through List Connections to show connection status. If your implementation returns an error, Wix surfaces it to the caller. The exception is List Connections: if it fails, Wix leaves your connections out of the results and still returns the connections of other providers.

### Context provided with each call

Wix automatically includes context information with every service plugin call. Use this context to tailor your implementation's behavior to the site, user, and scenario.

| Context | Description |
|---------|-------------|
| Site identifiers | Unique identifiers for the Wix site and instance making the request. |
| Locale/Language | The language and regional settings of the current user session. |
| Currency | The currency configured for the site. |
| Identity | The type and ID of the entity making the request (site member, visitor, or app). |

::::TABS

:::REST_TAB

## Get started

To enable Wix to communicate with your app:

1. Go to [Extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions) in your app's dashboard.
1. Click **Create Extension** in the top right.
1. Find **Conferencing Provider** and click **Create**.
1. Provide the following configuration in the JSON editor and then click **Save**.

    | Name | Type | Description |
    | --- | --- | --- |
    | `deploymentUri` | string | **Required.** Base URI where your implementation is deployed. Wix appends each method path to this base URI. For example, to call Create Conference at `https://my-conferencing.com/v1/create-conference`, the base URI is `https://my-conferencing.com/`. |
    | `displayName` | string | Name shown to users. For example, `Zoom`. |
    | `connectionMethods` | array | Connection methods your provider supports: `OAUTH`, `CREDENTIALS`, or both. Wix calls only the connect methods matching these values. |
    | `updateSupported` | boolean | Whether your provider supports updating conferences. When `false`, Wix doesn't call Update Conference. |
    | `termsUrl`, `privacyUrl`, `iconUrl`, `supportUrl` | string | Terms of service, privacy policy, icon, and support URLs shown to users. |

:::
:::SDK_TAB

## Get started

**Self-hosted implementations:**

To enable Wix to communicate with your app:

1. Go to [Extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions) in your app's dashboard.
1. Click **Create Extension** in the top right.
1. Find **Conferencing Provider** and click **Create**.
1. Provide the following configuration in the JSON editor and then click **Save**.

    | Name | Type | Description |
    | --- | --- | --- |
    | `deploymentUri` | string | **Required.** Base URI where your implementation is deployed. Wix appends each method path to this base URI. For example, to call Create Conference at `https://my-conferencing.com/v1/create-conference`, the base URI is `https://my-conferencing.com/`. |
    | `displayName` | string | Name shown to users. For example, `Zoom`. |
    | `connectionMethods` | array | Connection methods your provider supports: `OAUTH`, `CREDENTIALS`, or both. Wix calls only the connect methods matching these values. |
    | `updateSupported` | boolean | Whether your provider supports updating conferences. When `false`, Wix doesn't call Update Conference. |
    | `termsUrl`, `privacyUrl`, `iconUrl`, `supportUrl` | string | Terms of service, privacy policy, icon, and support URLs shown to users. |

Define handler functions using [`conferencingProvider.provideHandlers()`](portalId::63e3acd8-2a9c-421d-8f92-d02930eeb59eresourceId::67e56abc-37a6-4734-81e2-624cee8fdd87#step-4--define-handler-functions*fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-4--define-handler-functions):

| Function | Required |
| --- | --- |
| [`createConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/create-conference) | Yes |
| [`getConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/get-conference) | Yes |
| [`deleteConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/delete-conference) | Yes |
| [`listConnections()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/list-connections) | Yes |
| [`markConnectionAsDisconnected()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/mark-connection-as-disconnected) | Yes |
| [`updateConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/update-conference) | Only if `updateSupported` is `true` |
| [`connectByOAuth()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/connect-by-oauth) | Only if `connectionMethods` includes `OAUTH` |
| [`connectByCredentials()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/connect-by-credentials) | Only if `connectionMethods` includes `CREDENTIALS` |

### Self-hosted: Basic code structure

```js
import { createClient } from '@wix/sdk';
import { conferencingProvider } from '@wix/calendar/service-plugins';

const wixClient = createClient({
  auth: {
    appId: <YOUR_APP_ID>,
    publicKey: <YOUR_APP_PUBLIC_KEY>
  },
  modules: { conferencingProvider }
});

wixClient.conferencingProvider.provideHandlers({
  createConference: async (payload) => {
    const { request, metadata } = payload;

    // Add your logic here
  },
  listConnections: async (payload) => {
    const { request, metadata } = payload;

    // Add your logic here
  },
  // Add the other handlers your provider supports
});

// Implement a router to process all requests
express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});
```

**CLI implementations:**

Learn how to [implement a service plugin with the CLI and the SDK](portalId::9d2c17b5-bdfd-4ef8-95e1-9efa463d13f5resourceId::bb12234f-4332-4fcf-84f7-6049d169868a*fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli).

Define handler functions using [`conferencingProvider.provideHandlers()`](portalId::63e3acd8-2a9c-421d-8f92-d02930eeb59eresourceId::67e56abc-37a6-4734-81e2-624cee8fdd87#step-4--define-handler-functions*fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-4--define-handler-functions):

| Function | Required |
| --- | --- |
| [`createConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/create-conference) | Yes |
| [`getConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/get-conference) | Yes |
| [`deleteConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/delete-conference) | Yes |
| [`listConnections()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/list-connections) | Yes |
| [`markConnectionAsDisconnected()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/mark-connection-as-disconnected) | Yes |
| [`updateConference()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/update-conference) | Only if `updateSupported` is `true` |
| [`connectByOAuth()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/connect-by-oauth) | Only if `connectionMethods` includes `OAUTH` |
| [`connectByCredentials()`](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/connect-by-credentials) | Only if `connectionMethods` includes `CREDENTIALS` |

### CLI: Basic code structure

```js
import { conferencingProvider } from '@wix/calendar/service-plugins';

conferencingProvider.provideHandlers({
  createConference: async (payload) => {
    const { request, metadata } = payload;

    // Add your logic here
  },
  listConnections: async (payload) => {
    const { request, metadata } = payload;

    // Add your logic here
  },
  // Add the other handlers your provider supports
});
```

:::
::::

## Requirements and constraints

Your implementation should meet the following expectations:

- Respond promptly to every call, since Wix calls your implementation synchronously and waits for the response.
- Be able to look up a connection by `resourceId` and a conference by the `id` you returned from Create Conference.
- Keep your stored connections accurate, since List Connections is Wix's source of truth for connection state.

There are no Wix-imposed rate limits or quotas on this service plugin. Any limits are those of your underlying provider.

### Error handling

Return the defined errors when the matching condition occurs, so Wix can respond appropriately. For example, return the resource-not-connected error when a request targets a resource that has no active connection in your system.

## Before you begin

It's important to note the following points before starting to code:

- Implement only the connect methods that match the `connectionMethods` you advertise. Wix doesn't call a connect method for a connection method you don't advertise.
- Your implementation owns connections and tokens. Wix doesn't persist them, so List Connections must return your current state.
- For OAuth, your implementation owns the full flow: return the OAuth URL, host the provider callback, create the connection, and redirect the user back to Wix's `redirectUrl` with `?connectionId` or `?error`.
- Treat `resourceId` as a stable, opaque key for storing and looking up connections.
- Set `connectedDate` on every connection you store. Wix ignores connections without it.
- When a conference is requested without naming a provider, Wix uses the resource's connection with the most recent `connectedDate`, across all providers on the site.

## Use cases

- [Add a conferencing provider with OAuth](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/sample-flows#add-a-conferencing-provider-with-oauth)
- [Create and manage a conference for a connected resource](fallback::https://dev.wix.com/docs/api-reference/business-management/calendar/conferencing/conferencing-provider-v1/sample-flows#create-and-manage-a-conference-for-a-connected-resource)

## Terminology

- **Service plugin**: The contract you implement, which Wix calls to connect resources and manage conferences with your provider.
- **Connection**: A link between a resource and an account in your provider. Your implementation stores connections.
- **Connection method**: How a connection is established: `OAUTH` or `CREDENTIALS`.
- **Conference**: A video meeting your provider creates and stores. Wix holds only the details you return.
- **Resource**: The entity a conference is created for. Identified by `resourceId`.
- **Connection status**: `CONNECTED` (usable), `DISCONNECTED` (intentionally disconnected), or `ERROR` (was connected but now broken and needs reconnection).


@sdk_package_setup

# Conferencing Provider: Sample Flows

This article presents possible use cases and corresponding sample flows that your service plugin can support. It provides a useful starting point as you plan your implementation.

## Add a conferencing provider with OAuth

A site user wants to connect their account in your provider so conferences can be created on their behalf. Your implementation owns the OAuth flow and the resulting connection.

> **Prerequisite:** Your Conferencing Provider service plugin is registered and configured, with `OAUTH` listed in `connectionMethods`.

To add a conferencing provider with OAuth:

### Step 1 | Wix calls your implementation

Wix calls your Connect By OAuth method with the `resourceId` to connect and a `redirectUrl` to return the user to.

### Step 2 | Your implementation returns an OAuth URL

Generate the authorization URL for your provider and return it as `oauthUrl`. Wix redirects the user there to grant access.

### Step 3 | Your implementation handles the callback

After the user authorizes, your provider calls your callback. Exchange the authorization code for tokens, create and store a connection for the `resourceId` (generating a stable connection `id`), and set its `connectedDate`. Wix ignores connections without a `connectedDate`.

### Step 4 | Your implementation redirects back to Wix

Redirect the user to the `redirectUrl` with `?connectionId=<id>` on success, or `?error=<code>` on failure (`reject`, `missing_permissions`, or `internal`).

### Step 5 | Wix reads the connection

Wix calls your List Connections method to read the connection state and show the connection's status.

## Create and manage a conference for a connected resource

Once a resource is connected, Wix asks your implementation to create a conference and, later, to update, retrieve, or delete it.

> **Prerequisite:** The resource has an active connection in your system (see [Add a conferencing provider with OAuth](fallback::#add-a-conferencing-provider-with-oauth)).

To create and manage a conference:

### Step 1 | Wix requests a conference

Wix calls your Create Conference method with the `resourceId` and optional scheduling details (`title`, `startTime`, `durationInMinutes`).

### Step 2 | Your implementation creates the meeting

Look up the connection for the `resourceId`, create a distinct meeting in your provider, and return the conference details, including a stable conference `id`, the join `url`, and any `password`.

### Step 3 | Wix uses the response

Wix passes the details you return, including the join URL, to the Wix product that requested the conference. Wix doesn't store the conference, so it calls Get Conference when it needs the current details.

### Step 4 | Wix manages the conference later

When the meeting changes, Wix calls your Update Conference method (only if your configuration sets `updateSupported = true`). To read or remove the meeting, Wix calls Get Conference or Delete Conference. Each call includes the conference `id` and `resourceId` you returned, which you use to look the meeting up in your provider.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso