By default, a room hosts a one-to-one call between a host and a guest. Pass call_type: "group" when creating 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.

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

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:

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:

{
  "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.

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:

[
  {
    "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 returns 400 Bad Request and leaves the room unchanged:

[
  {
    "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:

{
  "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.

This 422 response is a single JSON object with an error string, not the array shape used for validation errors. See Errors & 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.

Questions? Contact us at support@meetone.io.