# Group calls

> Create end-to-end encrypted group video calls with call_type: group, hand out join URLs for additional participants, and check that your plan includes group calls.

Source: https://help.meetone.io/developers/video-api/group-calls
Last updated: 2026-10-10

---

By default, a room hosts a one-to-one call between a host and a guest. Pass `call_type: "group"` when [creating a room](https://help.meetone.io/developers/video-api/rooms-endpoints#create-a-room) to host an end-to-end encrypted group call instead, for example a group session, a consultation with several relatives, or a case conference.

> **Warning**
>
> **Group calls require a plan that includes them.** They are not part of every MeetOne plan and are **not enabled by default**: the `group_calls` feature has to be enabled for the organization of your Organization API Token, or for your tenant when you use an Instance API Token. Contact [support@meetone.io](mailto:support@meetone.io) to switch to a plan with group calls. Until then, `call_type: "group"` is refused with `422 Unprocessable Content`, see [When group calls are not available](https://help.meetone.io/developers/video-api/group-calls#when-group-calls-are-not-available).

## Single and group calls

`call_type` decides what kind of call a room hosts:

| | `single` (default) | `group` |
|---|---|---|
| Who joins | Host and guest, plus up to 4 additional guests | Host and guest, plus up to 98 additional guests |
| Additional guests | Only with the `appointment_additional_participants` feature | Always available |
| Plan requirement | None | A plan that includes group calls |
| In-call chat and whiteboard | Available | Not available |
| `room.participant_left` after a hangup | Right away | About 30 seconds later |

`call_type` is set once, when the room is created. Omitting it creates a `single` room, so existing integrations keep working unchanged.

## Create a group call

Send `call_type: "group"` together with `additional_guest_count`, the number of participants who join besides the host and the guest:

```bash
curl -X POST "https://acme.meetone.io/api/rooms" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Parent group session",
    "meeting_duration": 60,
    "scheduled_at": "2024-08-23T15:19:36.378+02:00",
    "call_type": "group",
    "additional_guest_count": 2
  }'
```

A successful request returns `201 Created`. The room carries `call_type: "group"`, and every additional participant gets an entry in `additional_access_tokens` with a `join_url` of their own:

```json
{
  "public_id": "3f2b8c1e-6a4d-4e9b-9c1a-2f6e8d7b5a10",
  "name": "Parent group session",
  "token": "f167d6f76f14991c",
  "status": "active",
  "access_token": "65a56167f28f6dec",
  "guest_token": "2367668999959557",
  "scheduled_at": "2024-08-23T15:19:36.378+02:00",
  "meeting_duration": 60,
  "call_type": "group",
  "host_join_url": "http://www.example.com/r/7bbb22b73d4e4732",
  "guest_join_url": "http://www.example.com/r/3d4e4722b7327bbb",
  "additional_access_tokens": [
    {
      "id": 42,
      "token": "abc123def456",
      "display_name": null,
      "join_url": "http://www.example.com/r/abc123def456",
      "participant": null
    },
    {
      "id": 43,
      "token": "def456ghi789",
      "display_name": null,
      "join_url": "http://www.example.com/r/def456ghi789",
      "participant": null
    }
  ],
  "created_at": "2024-08-23T15:19:36.378+02:00",
  "updated_at": "2024-08-23T15:19:36.378+02:00"
}
```

Give each participant their own join URL rather than sharing one link between several people: several people on the same link count as one participant in the [participant webhooks](https://help.meetone.io/developers/video-api/group-calls#webhooks-for-group-calls).

## How many additional guests you can request

A group call has room for the host, the guest, and by default up to 98 additional guests. A higher `additional_guest_count` is rejected with `400 Bad Request` and no room is created:

```json
[
  {
    "attribute": "additional_guest_count",
    "type": "less_than_or_equal_to",
    "message": "must be less than or equal to 98"
  }
]
```

Additional guest tokens are created together with the room. `additional_guest_count` has no effect on an update, so request every join URL you need when you create the room.

## The call type cannot change

A room keeps its `call_type` for its whole lifetime. Sending a different `call_type` to [update a room](https://help.meetone.io/developers/video-api/rooms-endpoints#update-a-room) returns `400 Bad Request` and leaves the room unchanged:

```json
[
  {
    "attribute": "call_type",
    "type": "fixed_once_created",
    "message": "cannot be changed once the room has been created"
  }
]
```

Sending the value the room already has is accepted. To turn a one-to-one call into a group call, create a new room with `call_type: "group"`.

A value other than `single` or `group` returns `400 Bad Request` with an error of type `inclusion` on `call_type`.

## When group calls are not available

Without a plan that includes group calls, `call_type: "group"` returns `422 Unprocessable Content`, and no room is created:

```json
{
  "error": "Group calls are not available in your current plan."
}
```

If your plan includes group calls but they are temporarily unavailable on your instance, the message is `"Group calls are currently not available."` instead. In both cases, `call_type: "single"`, or omitting the field, keeps working.

> **Warning**
>
> This `422` response is a single JSON object with an `error` string, not the array shape used for validation errors. See [Errors & pagination](https://help.meetone.io/developers/getting-started/errors-and-pagination).

## What participants need

Group calls are end-to-end encrypted in the browser. Participants need a browser that supports end-to-end encrypted media; a browser without that support shows an error instead of joining the call. Send `enable_chat` and `enable_whiteboard` as you like: both are accepted, but a group call shows neither the in-call chat nor the whiteboard.

## Webhooks for group calls

`room.created` and `room.reopened` carry `call_type`, so your endpoint can tell a group call from a one-to-one call, and they include `additional_access_tokens` for every group call.

`room.participant_joined` and `room.participant_left` work as in one-to-one calls, with one difference: a hangup cannot be told apart from a page reload, so its `room.participant_left` arrives like the one for a closed tab, about 30 seconds after the participant left, unless they came back. A reload therefore sends no leave/join pair. See the [webhook events reference](https://help.meetone.io/developers/webhooks/webhook-events-reference).

## Related

- [Rooms endpoints](https://help.meetone.io/developers/video-api/rooms-endpoints)
- [Additional participants & permanent rooms](https://help.meetone.io/developers/video-api/additional-participants-permanent-rooms)
- [Webhook events reference](https://help.meetone.io/developers/webhooks/webhook-events-reference)
- [Verifying webhook signatures](https://help.meetone.io/developers/webhooks/verifying-webhook-signatures)
- [Manage your plan and subscription](https://help.meetone.io/en/organizations-admins/manage-plan-subscription)

Questions? Contact us at [support@meetone.io](mailto:support@meetone.io).