Skip to content
Optiwork API Docs

Ring more people into a call

POST
/rooms/calls/{room}/invite
curl --request POST \
  --url https://collab.work.optidata.cloud/api/rooms/calls/a3050cd3-5921-4153-b90a-owt42-e94de63c7b15/invite \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "callee_uuids": [ "5b1c7e22-9d40-4f6a-b3c8-1e2f3a4b5c6d" ] }'

Rings the users in callee_uuids into an existing room, for example to add someone to a call in progress. Same response as startCall; the room comes without settings.

You must be a party of the call. caller_uuid is optional and, when sent, must be your own user uuid. Up to 100 users per request.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
room
required
string

The room’s hash (from its link) or its permanent-link identifier custom_hash.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
caller_uuid

Optional. When sent, your own user uuid.

string | null format: uuid
callee_uuids
required

Uuids of the users to ring.

Array<string>
<= 100 items
Examples
Exampleinvite
{
  "callee_uuids": [
    "5b1c7e22-9d40-4f6a-b3c8-1e2f3a4b5c6d"
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The room, caller and callees.

Media typeapplication/json
object
room
required
object
id
required

Internal id. Address the room by hash or custom_hash, never by this id.

integer
room_settings_id
integer | null
cuid

Your company’s id.

string
name
required
string | null
description
string | null
icon_url
string | null
hash
required

The room’s identifier and link.

string
custom_hash

The permanent-link identifier, when the room has one.

string | null
owner_uuid

The user who created the room.

string | null format: uuid
conference_type

on_site for rooms holding an uploaded in-person meeting; null or virtual for video meetings.

string | null
Allowed values: virtual on_site
is_recording_in_progress
boolean
is_ai_notes_enabled

Whether AI meeting notes are on for this room.

boolean
is_ai_notes_locked

Whether participants are prevented from turning AI notes off.

boolean
is_hidden
boolean
chat_uuid
string | null
usage_url
required

The room’s link, to share with participants.

string format: uri
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
settings
object
id
integer
room_id
integer
max_users

Maximum number of people in the room at once.

integer | null
is_guests_allowed

Whether people without an Optiwork account may join.

boolean
join_mode

Who may enter the room and whether they must ask first:

  • automatic — anyone with the link enters straight away; guests without an account appear as “Guest”.
  • no_request — anyone with the link enters without asking; guests type their name first.
  • unauthenticated_must_request — signed-in Optiwork users enter; guests type their name and ask to join.
  • authenticated_only_no_request — only signed-in Optiwork users, without asking; guests are turned away.
  • authenticated_only_must_request — only signed-in Optiwork users, and they ask to join; guests are turned away.
  • any_must_request — everyone asks to join; guests type their name first.
string
Allowed values: automatic no_request unauthenticated_must_request authenticated_only_no_request authenticated_only_must_request any_must_request
created_at
string format: date-time
updated_at
string format: date-time
participations

Present on getRoom and listRooms.

Array<object>

One person’s presence in a room.

object
id
integer
room_id
integer
user_id

null for guests without an Optiwork account.

integer | null
role

admin for the room owner, moderator for co-hosts, guest for everyone else.

string | null
Allowed values: admin moderator guest
is_send_audio_allowed
boolean
is_send_video_allowed
boolean
is_send_chat_allowed
boolean
is_guest
boolean
guest_user

Details a guest gave when joining.

object
name
string | null
email

Where the guest gets the meeting summary. Shown only on your own participation, or to the room’s owner, its moderators and company super-administrators.

string | null format: email
should_receive_call_summary
boolean
join_request_status

State of the person’s request to join, in rooms where joining must be requested.

string | null
origin_hash
string | null
is_ai_notes_enabled
boolean
last_active_at
string | null format: date-time
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
user
object
id
integer
uuid
string format: uuid
cuid
string
username
string
email
string format: email
name
string
company_name
string | null
status
string
avatar_url
string | null
settings

The user’s display preferences (language, theme, time zone).

object | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
last_recording
One of:
object
id
required
integer
room_id
required
integer
user_id

The person who made the recording.

integer | null
name
string | null
status
required
  • creating, started — being recorded.
  • stopped_locally, pending, processing — recorded; being saved and processed.
  • stopped — done; the transcript follows when ready.
  • failed — interrupted; see startRecordingRecovery.
string
Allowed values: creating started pending processing stopped_locally stopped failed
type
required

manual when a participant pressed record; automatic for the audio recorded to produce AI meeting notes; audio_only_sibling for the audio track kept next to a manual recording.

string
Allowed values: manual automatic audio_only_sibling
duration_ms
integer | null
chunks_count
integer | null
is_drive_saved

Whether a copy was saved to Optiwork Drive.

boolean
sibling_recording_id
integer | null
is_processing
boolean
is_in_progress
boolean
public_link_url

The public link, when the recording has one.

string | null
link

Address of the recording page in Optiwork.

string
meta

Technical details of the recording. Its content may change; do not rely on it.

object | null
created_at
string format: date-time
updated_at
string format: date-time
stopped_at
string | null format: date-time
room
object recursive
user
object
id
integer
uuid
string format: uuid
cuid
string
username
string
email
string format: email
name
string
company_name
string | null
status
string
avatar_url
string | null
settings

The user’s display preferences (language, theme, time zone).

object | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
participations

Who was in the meeting while it was recorded.

Array<object>

One person’s presence in a room.

object
id
integer
room_id
integer
user_id

null for guests without an Optiwork account.

integer | null
role

admin for the room owner, moderator for co-hosts, guest for everyone else.

string | null
Allowed values: admin moderator guest
is_send_audio_allowed
boolean
is_send_video_allowed
boolean
is_send_chat_allowed
boolean
is_guest
boolean
guest_user

Details a guest gave when joining.

object
name
string | null
email

Where the guest gets the meeting summary. Shown only on your own participation, or to the room’s owner, its moderators and company super-administrators.

string | null format: email
should_receive_call_summary
boolean
join_request_status

State of the person’s request to join, in rooms where joining must be requested.

string | null
origin_hash
string | null
is_ai_notes_enabled
boolean
last_active_at
string | null format: date-time
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
user
object
id
integer
uuid
string format: uuid
cuid
string
username
string
email
string format: email
name
string
company_name
string | null
status
string
avatar_url
string | null
settings

The user’s display preferences (language, theme, time zone).

object | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
permissions

People and groups the recording is shared with.

Array<object>
object
key
additional properties
any
link_permission

The public-link setting, when the recording has a public link.

object | null
transcription
One of:
object
id
integer
recording_id
integer
status
string
Allowed values: queued processing completed error
summary

AI summary of the meeting.

string | null
key_points

AI key points, as a JSON-encoded string: an array of { "title", "items": [string] } sections.

string | null
content

The full transcript as produced by the speech-to-text engine (utterances, words, speakers, timings). Its exact shape depends on the engine and may change.

object | null
transcript_id
string | null
transcript_error
string | null
meta
object | null
created_at
string format: date-time
updated_at
string format: date-time
caller
required
object
id
integer
uuid
string format: uuid
cuid
string
username
string
email
string format: email
name
string
company_name
string | null
status
string
avatar_url
string | null
settings

The user’s display preferences (language, theme, time zone).

object | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
callees
required
Array<object>
object
id
integer
uuid
string format: uuid
cuid
string
username
string
email
string format: email
name
string
company_name
string | null
status
string
avatar_url
string | null
settings

The user’s display preferences (language, theme, time zone).

object | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
calleeUuids

The callee_uuids you sent.

Array<string>
Example
{
  "room": {
    "conference_type": "virtual",
    "settings": {
      "join_mode": "automatic"
    },
    "participations": [
      {
        "role": "admin",
        "user": {
          "status": "active"
        }
      }
    ],
    "last_recording": {
      "status": "creating",
      "type": "manual",
      "user": {
        "status": "active"
      },
      "participations": [
        {
          "role": "admin",
          "user": {
            "status": "active"
          }
        }
      ],
      "transcription": {
        "status": "queued"
      }
    }
  },
  "caller": {
    "status": "active"
  },
  "callees": [
    {
      "status": "active"
    }
  ]
}

401

Section titled “401”

No authentication key was sent, or it is malformed.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

You are not a party of the call (the room’s owner, someone admitted to the room or holding a moderator or admin role in it, or someone rung into it within the last hour), or a field naming the actor is not your own uuid.

Media typeapplication/json

A refused or not-found request.

object
message
required
string
Examples

Not a party of the call

{
  "message": "You are not a participant of this call."
}

404

Section titled “404”

No room has this hash or permanent link.

Media typeapplication/json

A refused or not-found request.

object
message
required
string
Examples
ExamplenotFound
{
  "message": ""
}

419

Section titled “419”

The authentication key is expired or not recognised. Get a fresh one and retry.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Exampleexpired
{
  "error": "JWT passport expired: Passport expired"
}

422

Section titled “422”

The body failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
Examplemissing
{
  "message": "The callee uuids field is required.",
  "errors": {
    "callee_uuids": [
      "The callee uuids field is required."
    ]
  }
}