Available Operations Webhooks
 
 

Get all available rooms

GET https://api-eu.vonage.com/beta/meetings/rooms
Host https://api-eu.vonage.com
GET /beta/meetings/rooms

Query Parameter

start_id
string

The ID to start returning events at

end_id
string

The ID to end returning events at (excluding end_id itself)

Responses

200 OK
page_size
integer

The number of results returned on this page.

_embedded
object
rooms
array of objects

List of all accessible rooms

id
string
display_name
string
metadata
string

Free text that can be attached to a room. This will be passed in the form of a header in events related to this room.

type
string
One of: instant or long_term
recording_options
object
auto_record
boolean

Automatically record all sessions in this room. Recording cannot be stopped when this is set to true.

meeting_code
string
is_available
boolean

Once a room becomes unavailable, no new sessions can be created under it

created_at
string

The time for when the room was created, expressed in ISO 8601 format

expires_at
string

The time for when the room will be expired, expressed in ISO 8601 format

expire_after_use
boolean

Close the room after a session ends. Only relevant for long_term rooms.

Example Responses

200
{
  "page_size": 10,
  "_embedded": {
    "rooms": [
      {
        "id": "abc123",
        "display_name": "abc123",
        "metadata": "abc123",
        "type": "abc123",
        "recording_options": {
          "auto_record": false
        },
        "meeting_code": "123456789",
        "is_available": false,
        "created_at": "abc123",
        "expires_at": "abc123",
        "expire_after_use": false,
        "_links": {
          "guest_url": {
            "href": "https://meetings.vonage.com/123456789"
          },
          "host_url": {
            "href": "https://meetings.vonage.com/123456789?participant_token=xyz"
          }
        }
      }
    ]
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/v0.1/meetings/rooms?page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/v0.1/meetings/rooms?page_size=10&start_id=20"
    },
    "next": {
      "href": "https://api.nexmo.com/v0.1/meetings/rooms?page_size=10&start_id=30"
    },
    "prev": {
      "href": "https://api.nexmo.com/v0.1/meetings/rooms?page_size=10&end_id=20"
    }
  }
}

Create a room

POST https://api-eu.vonage.com/beta/meetings/rooms
Host https://api-eu.vonage.com
POST /beta/meetings/rooms

Request body application/json

display_name
string | Max: 200
metadata
string | Max: 500

Free text that can be attached to a room. This will be passed in the form of a header in events related to this room.

type
string

Represents the type of the room.

Must be one of: instant or long_term
expires_at
string (date)

The time for when the room will be expired, expressed in ISO 8601 format. Required only for long-term room creation.

recording_options
object
auto_record
boolean

Automatically record all sessions in this room. Recording cannot be stopped when this is set to true.

expire_after_use
boolean

Close the room after a session ends. Only relevant for long_term rooms.

Responses

201 OK
id
string
display_name
string
metadata
string

Free text that can be attached to a room. This will be passed in the form of a header in events related to this room.

type
string
One of: instant or long_term
recording_options
object
auto_record
boolean

Automatically record all sessions in this room. Recording cannot be stopped when this is set to true.

meeting_code
string
is_available
boolean

Once a room becomes unavailable, no new sessions can be created under it

created_at
string

The time for when the room was created, expressed in ISO 8601 format

expires_at
string

The time for when the room will be expired, expressed in ISO 8601 format

expire_after_use
boolean

Close the room after a session ends. Only relevant for long_term rooms.

Example Request

{
}

Example Responses

201 403
{
  "id": "abc123",
  "display_name": "abc123",
  "metadata": "abc123",
  "type": "abc123",
  "recording_options": {
    "auto_record": false
  },
  "meeting_code": "123456789",
  "is_available": false,
  "created_at": "abc123",
  "expires_at": "abc123",
  "expire_after_use": false,
  "_links": {
    "guest_url": {
      "href": "https://meetings.vonage.com/123456789"
    },
    "host_url": {
      "href": "https://meetings.vonage.com/123456789?participant_token=xyz"
    }
  }
}

This endpoint does not support application/json

Get room details

GET https://api-eu.vonage.com/beta/meetings/rooms/:room_id
Host https://api-eu.vonage.com
GET /beta/meetings/rooms/:room_id

Responses

200 OK
id
string
display_name
string
metadata
string

Free text that can be attached to a room. This will be passed in the form of a header in events related to this room.

type
string
One of: instant or long_term
recording_options
object
auto_record
boolean

Automatically record all sessions in this room. Recording cannot be stopped when this is set to true.

meeting_code
string
is_available
boolean

Once a room becomes unavailable, no new sessions can be created under it

created_at
string

The time for when the room was created, expressed in ISO 8601 format

expires_at
string

The time for when the room will be expired, expressed in ISO 8601 format

expire_after_use
boolean

Close the room after a session ends. Only relevant for long_term rooms.

Example Responses

200 404
{
  "id": "abc123",
  "display_name": "abc123",
  "metadata": "abc123",
  "type": "abc123",
  "recording_options": {
    "auto_record": false
  },
  "meeting_code": "123456789",
  "is_available": false,
  "created_at": "abc123",
  "expires_at": "abc123",
  "expire_after_use": false,
  "_links": {
    "guest_url": {
      "href": "https://meetings.vonage.com/123456789"
    },
    "host_url": {
      "href": "https://meetings.vonage.com/123456789?participant_token=xyz"
    }
  }
}

This endpoint does not support application/json

Delete a room

DELETE https://api-eu.vonage.com/beta/meetings/rooms/:room_id
Host https://api-eu.vonage.com
DELETE /beta/meetings/rooms/:room_id

Example Responses

204 404
OK

This endpoint does not support application/json

Update an existing room

PATCH https://api-eu.vonage.com/beta/meetings/rooms/:room_id
Host https://api-eu.vonage.com
PATCH /beta/meetings/rooms/:room_id

Request body application/json

update_details
object
expires_at
string (date)

The time for when the room will be expired, expressed in ISO 8601 format.

expire_after_use
boolean

Close the room after a session ends. Only relevant for long_term rooms.

Responses

200 OK
id
string
display_name
string
metadata
string

Free text that can be attached to a room. This will be passed in the form of a header in events related to this room.

type
string
One of: instant or long_term
recording_options
object
auto_record
boolean

Automatically record all sessions in this room. Recording cannot be stopped when this is set to true.

meeting_code
string
is_available
boolean

Once a room becomes unavailable, no new sessions can be created under it

created_at
string

The time for when the room was created, expressed in ISO 8601 format

expires_at
string

The time for when the room will be expired, expressed in ISO 8601 format

expire_after_use
boolean

Close the room after a session ends. Only relevant for long_term rooms.

Example Request

{
}

Example Responses

200 400 404
{
  "id": "abc123",
  "display_name": "abc123",
  "metadata": "abc123",
  "type": "abc123",
  "recording_options": {
    "auto_record": false
  },
  "meeting_code": "123456789",
  "is_available": false,
  "created_at": "abc123",
  "expires_at": "abc123",
  "expire_after_use": false,
  "_links": {
    "guest_url": {
      "href": "https://meetings.vonage.com/123456789"
    },
    "host_url": {
      "href": "https://meetings.vonage.com/123456789?participant_token=xyz"
    }
  }
}

This endpoint does not support application/json

This endpoint does not support application/json

Get a recording

GET https://api-eu.vonage.com/beta/meetings/recordings/:recording_id
Host https://api-eu.vonage.com
GET /beta/meetings/recordings/:recording_id

Responses

200 OK
id
string
session_id
string

Corresponds to the underlying Video API session id

started_at
string
ended_at
string
status
string
One of: started, stopped, paused or uploaded

Example Responses

200 404
{
  "id": "abc123",
  "session_id": "2_MX40NjMwODczMn5-MTU3NTgyODEwNzQ2MH5OZDJrVmdBRUNDbG5MUzNqNXgya20yQ1Z-fg",
  "started_at": "abc123",
  "ended_at": "abc123",
  "status": "abc123",
  "_links": {
    "url": {
      "href": "abc123"
    }
  }
}

This endpoint does not support application/json

Delete a recording

DELETE https://api-eu.vonage.com/beta/meetings/recordings/:recording_id
Host https://api-eu.vonage.com
DELETE /beta/meetings/recordings/:recording_id

Example Responses

204 403 404
No Content

This endpoint does not support application/json

This endpoint does not support application/json

Get recordings of a session

GET https://api-eu.vonage.com/beta/meetings/sessions/:session_id/recordings
Host https://api-eu.vonage.com
GET /beta/meetings/sessions/:session_id/recordings

Responses

200 OK
_embedded
object
recordings
array of objects

List of recordings for the given session

id
string
session_id
string

Corresponds to the underlying Video API session id

started_at
string
ended_at
string
status
string
One of: started, stopped, paused or uploaded

Example Responses

200 404
{
  "_embedded": {
    "recordings": [
      {
        "id": "abc123",
        "session_id": "2_MX40NjMwODczMn5-MTU3NTgyODEwNzQ2MH5OZDJrVmdBRUNDbG5MUzNqNXgya20yQ1Z-fg",
        "started_at": "abc123",
        "ended_at": "abc123",
        "status": "abc123",
        "_links": {
          "url": {
            "href": "abc123"
          }
        }
      }
    ]
  }
}

This endpoint does not support application/json

Get numbers that can be used to dial into a meeting

GET https://api-eu.vonage.com/beta/meetings/dial-in-numbers
Host https://api-eu.vonage.com
GET /beta/meetings/dial-in-numbers

Responses

200 OK
number
string
locale
string
display_name
string

Example Responses

200
[
  {
    "number": "17323338801",
    "locale": "en-US",
    "display_name": "United States"
  }
]

Webhooks

Webhooks are an extension of an API, but instead of your code requesting data, the API sends data to you. The data arrives in a web request to your application.

To learn more about webhooks, see our webhooks documentation

This API may send any of the webhooks documented below to the URL that you have configured. You must respond with a 200 or 204 HTTP response, or the requests will be retried

 

Room Expired Callback Webhook

A notification about a room becoming inactive, which means no more sessions can be created for it

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: room:expired
room_id
string (uuid)
room_type
string
One of: instant or long_term
expires_at
string (date)

The time for when the room will be expired, expressed in ISO 8601 format

created_at
string (date)

The time for when the room was created, expressed in ISO 8601 format

Example Payload

{
}

Session Started Callback Webhook

A notification about a newly started session

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: session:started
session_id
string
room_id
string (uuid)
started_at
string (date-time)

Example Payload

{
}

Session Ended Callback Webhook

A notification about a session that has just ended

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: session:ended
session_id
string
room_id
string (uuid)
started_at
string (date-time)
ended_at
string (date-time)

Example Payload

{
}

Recording Started Callback Webhook

A notification about recording being turned on in a specific session

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: recording:started
recording_id
string (uuid)
session_id
string

Example Payload

{
}

Recording Ended Callback Webhook

A notification about recording being turned off in a specific session

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: recording:ended
recording_id
string (uuid)
session_id
string
started_at
string (date-time)
ended_at
string (date-time)
duration
number

Duration of the recording in seconds

Example Payload

{
}

Recording Ready Callback Webhook

A notification about recording ready to be downloaded

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: recording:ready
recording_id
string (uuid)
session_id
string
room_id
string (uuid)
started_at
string (date-time)
ended_at
string (date-time)
duration
number

Duration of the recording in seconds

url
string (uri)

Example Payload

{
}

Participant Joined Callback Webhook

A notification about someone joining a specific session

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: session:participant:joined
participant_id
string (uuid)
session_id
string
room_id
string (uuid)
name
string
type
string
is_host
boolean

indicates if this participant is the session's host

Example Payload

{
}

Participant Left Callback Webhook

A notification about someone leaving a specific session

POST https://example.com/webhooks/event

Request body application/json

event
string
One of: session:participant:left
participant_id
string (uuid)
session_id
string
room_id
string (uuid)
name
string
type
string
is_host
boolean

indicates if this participant is the session's host

Example Payload

{
}