Rooms API

Rooms operations.

View a list of rooms.

SecuritybearerAuth
Request
query Parameters
filter[date_created_at][eq]
string <date>

ISO 8601 date for filtering rooms created on that date.

Example: filter[date_created_at][eq]=2021-04-25
filter[date_created_at][gte]
string <date>

ISO 8601 date for filtering rooms created after that date.

Example: filter[date_created_at][gte]=2021-04-25
filter[date_created_at][lte]
string <date>

ISO 8601 date for filtering rooms created before that date.

Example: filter[date_created_at][lte]=2021-04-25
filter[date_updated_at][eq]
string <date>

ISO 8601 date for filtering rooms updated on that date.

Example: filter[date_updated_at][eq]=2021-04-25
filter[date_updated_at][gte]
string <date>

ISO 8601 date for filtering rooms updated after that date.

Example: filter[date_updated_at][gte]=2021-04-25
filter[date_updated_at][lte]
string <date>

ISO 8601 date for filtering rooms updated before that date.

Example: filter[date_updated_at][lte]=2021-04-25
filter[unique_name]
string

Unique_name for filtering rooms.

Example: filter[unique_name]=my_video_room
include_sessions
boolean

To decide if room sessions should be included in the response.

Example: include_sessions=true
page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

page[number]
integer >= 1
Default: 1

The page number to load

Responses
200

List rooms response.

Response Schema: application/json
Array of objects (Room)
object (PaginationMeta)
get/rooms
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "active_session_id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
      • "created_at": "2021-04-16T09:46:20.954863Z",
      • "enable_recording": true,
      • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
      • "max_participants": 50,
      • "record_type": "room",
      • "sessions": [
        • {
          • "active": true,
          • "created_at": "2021-04-16T09:46:20.954863Z",
          • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
          • "participants": [ ],
          • "record_type": "room_session",
          • "room_id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
          • "updated_at": "2021-04-16T10:24:55.962200Z"
          }
        ],
      • "unique_name": "My Room",
      • "updated_at": "2021-04-16T10:24:55.962200Z",
      • "webhook_event_failover_url": "https://failover.example.com",
      • "webhook_event_url": "https://www.example.com",
      • "webhook_timeout_secs": 25
      }
    ],
  • "meta": {
    • "page_number": 2,
    • "page_size": 25,
    • "total_pages": 3,
    • "total_results": 55
    }
}
Create a room.
Synchronously create a Room.


SecuritybearerAuth 
Request 
Request Body schema: application/json
required
Parameters that can be defined during room creation.


enable_recording
boolean
 Default:  false
Enable or disable recording for that room.


 
max_participants
integer  [ 2 .. 50 ] 
 Default:  10
The maximum amount of participants allowed in a room. If new participants try to join after that limit is reached, their request will be rejected.


 
unique_name
string
The unique (within the Telnyx account scope) name of the room.


 
webhook_event_failover_url
string <url> 
 Default:  ""
The failover URL where webhooks related to this room will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.


 
webhook_event_url
string <url> 
The URL where webhooks related to this room will be sent. Must include a scheme, such as 'https'.


 
webhook_timeout_secs
integer  [ 0 .. 30 ] 
 Default:  null
Specifies how many seconds to wait before timing out a webhook.


 
Responses 
201
Create room response.


Response Schema: application/json
object (Room) 
 
active_session_id
string <uuid> 
The identifier of the active room session if any.


 
created_at
string <datetime> 
ISO 8601 timestamp when the room was created.


 
enable_recording
boolean
 Default:  false
Enable or disable recording for that room.


 
id
string <uuid> 
A unique identifier for the room.


 
max_participants
integer
Maximum participants allowed in the room.


 
record_type
string
 
Array of objects (RoomSession) 
 
unique_name
string
The unique (within the Telnyx account scope) name of the room.


 
updated_at
string <datetime> 
ISO 8601 timestamp when the room was updated.


 
webhook_event_failover_url
string <url> 
 Default:  ""
The failover URL where webhooks related to this room will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.


 
webhook_event_url
string <url> 
The URL where webhooks related to this room will be sent. Must include a scheme, such as 'https'.


 
webhook_timeout_secs
integer  [ 0 .. 30 ] 
 Default:  null
Specifies how many seconds to wait before timing out a webhook.


 
422
Unprocessable entity. Check the 'detail' field in response for details.


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/rooms
Request samples 
application/json
{}
Response samples 
application/json
{
  • "data": {
    • "active_session_id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
    • "created_at": "2021-04-16T09:46:20.954863Z",
    • "enable_recording": true,
    • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
    • "max_participants": 50,
    • "record_type": "room",
    • "sessions": [
      • {
        • "active": true,
        • "created_at": "2021-04-16T09:46:20.954863Z",
        • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
        • "participants": [ ],
        • "record_type": "room_session",
        • "room_id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
        • "updated_at": "2021-04-16T10:24:55.962200Z"
        }
      ],
    • "unique_name": "My Room",
    • "updated_at": "2021-04-16T10:24:55.962200Z",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_event_url": "https://www.example.com",
    • "webhook_timeout_secs": 25
    }
}
Delete a room.
Synchronously delete a Room. Participants from that room will be kicked out, they won't be able to join that room anymore, and you won't be charged anymore for that room.


SecuritybearerAuth 
Request 
path Parameters
room_id
required
string <uuid> 
The unique identifier of a room.


 
 Example:  0ccc7b54-4df3-4bca-a65a-3da1ecc777f0
Responses 
204
The resource was deleted successfully.


404
Resource not found


Response Schema: application/json
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
delete/rooms/{room_id}
Request samples 
Response samples 
application/json
{
  • "code": "string",
  • "detail": "string",
  • "meta": { },
  • "source": {
    • "parameter": "string",
    • "pointer": "/json/pointer"
    },
  • "title": "string"
}
View a room.
SecuritybearerAuth 
Request 
path Parameters
room_id
required
string <uuid> 
The unique identifier of a room.


 
 Example:  0ccc7b54-4df3-4bca-a65a-3da1ecc777f0
query Parameters
include_sessions
boolean
To decide if room sessions should be included in the response.


 
 Example:  include_sessions=true
Responses 
200
Get room response.


Response Schema: application/json
object (Room) 
 
active_session_id
string <uuid> 
The identifier of the active room session if any.


 
created_at
string <datetime> 
ISO 8601 timestamp when the room was created.


 
enable_recording
boolean
 Default:  false
Enable or disable recording for that room.


 
id
string <uuid> 
A unique identifier for the room.


 
max_participants
integer
Maximum participants allowed in the room.


 
record_type
string
 
Array of objects (RoomSession) 
 
unique_name
string
The unique (within the Telnyx account scope) name of the room.


 
updated_at
string <datetime> 
ISO 8601 timestamp when the room was updated.


 
webhook_event_failover_url
string <url> 
 Default:  ""
The failover URL where webhooks related to this room will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.


 
webhook_event_url
string <url> 
The URL where webhooks related to this room will be sent. Must include a scheme, such as 'https'.


 
webhook_timeout_secs
integer  [ 0 .. 30 ] 
 Default:  null
Specifies how many seconds to wait before timing out a webhook.


 
404
Resource not found


Response Schema: application/json
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/rooms/{room_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "active_session_id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
    • "created_at": "2021-04-16T09:46:20.954863Z",
    • "enable_recording": true,
    • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
    • "max_participants": 50,
    • "record_type": "room",
    • "sessions": [
      • {
        • "active": true,
        • "created_at": "2021-04-16T09:46:20.954863Z",
        • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
        • "participants": [ ],
        • "record_type": "room_session",
        • "room_id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
        • "updated_at": "2021-04-16T10:24:55.962200Z"
        }
      ],
    • "unique_name": "My Room",
    • "updated_at": "2021-04-16T10:24:55.962200Z",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_event_url": "https://www.example.com",
    • "webhook_timeout_secs": 25
    }
}
Update a room.
Synchronously update a Room.


SecuritybearerAuth 
Request 
path Parameters
room_id
required
string <uuid> 
The unique identifier of a room.


 
 Example:  0ccc7b54-4df3-4bca-a65a-3da1ecc777f0
Request Body schema: application/json
required
Parameters that can be defined during room update.


enable_recording
boolean
 Default:  false
Enable or disable recording for that room.


 
max_participants
integer  [ 2 .. 50 ] 
 Default:  10
The maximum amount of participants allowed in a room. If new participants try to join after that limit is reached, their request will be rejected.


 
unique_name
string
The unique (within the Telnyx account scope) name of the room.


 
webhook_event_failover_url
string <url> 
 Default:  ""
The failover URL where webhooks related to this room will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.


 
webhook_event_url
string <url> 
The URL where webhooks related to this room will be sent. Must include a scheme, such as 'https'.


 
webhook_timeout_secs
integer  [ 0 .. 30 ] 
 Default:  null
Specifies how many seconds to wait before timing out a webhook.


 
Responses 
200
Update room response.


Response Schema: application/json
object (Room) 
 
active_session_id
string <uuid> 
The identifier of the active room session if any.


 
created_at
string <datetime> 
ISO 8601 timestamp when the room was created.


 
enable_recording
boolean
 Default:  false
Enable or disable recording for that room.


 
id
string <uuid> 
A unique identifier for the room.


 
max_participants
integer
Maximum participants allowed in the room.


 
record_type
string
 
Array of objects (RoomSession) 
 
unique_name
string
The unique (within the Telnyx account scope) name of the room.


 
updated_at
string <datetime> 
ISO 8601 timestamp when the room was updated.


 
webhook_event_failover_url
string <url> 
 Default:  ""
The failover URL where webhooks related to this room will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.


 
webhook_event_url
string <url> 
The URL where webhooks related to this room will be sent. Must include a scheme, such as 'https'.


 
webhook_timeout_secs
integer  [ 0 .. 30 ] 
 Default:  null
Specifies how many seconds to wait before timing out a webhook.


 
401
Unauthorized response. Happens when the current user is not a manager account.


404
Resource not found


Response Schema: application/json
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
422
Bad request


patch/rooms/{room_id}
Request samples 
application/json
{}
Response samples 
application/json
{
  • "data": {
    • "active_session_id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
    • "created_at": "2021-04-16T09:46:20.954863Z",
    • "enable_recording": true,
    • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
    • "max_participants": 50,
    • "record_type": "room",
    • "sessions": [
      • {
        • "active": true,
        • "created_at": "2021-04-16T09:46:20.954863Z",
        • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e74",
        • "participants": [ ],
        • "record_type": "room_session",
        • "room_id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
        • "updated_at": "2021-04-16T10:24:55.962200Z"
        }
      ],
    • "unique_name": "My Room",
    • "updated_at": "2021-04-16T10:24:55.962200Z",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_event_url": "https://www.example.com",
    • "webhook_timeout_secs": 25
    }
}
View a list of room sessions.
SecuritybearerAuth 
Request 
path Parameters
room_id
required
string <uuid> 
The unique identifier of a room.


 
 Example:  0ccc7b54-4df3-4bca-a65a-3da1ecc777f0
query Parameters
filter[date_created_at][eq]
string <date> 
ISO 8601 date for filtering room sessions created on that date.


 
 Example:  filter[date_created_at][eq]=2021-04-25
filter[date_created_at][gte]
string <date> 
ISO 8601 date for filtering room sessions created after that date.


 
 Example:  filter[date_created_at][gte]=2021-04-25
filter[date_created_at][lte]
string <date> 
ISO 8601 date for filtering room sessions created before that date.


 
 Example:  filter[date_created_at][lte]=2021-04-25
filter[date_updated_at][eq]
string <date> 
ISO 8601 date for filtering room sessions updated on that date.


 
 Example:  filter[date_updated_at][eq]=2021-04-25
filter[date_updated_at][gte]
string <date> 
ISO 8601 date for filtering room sessions updated after that date.


 
 Example:  filter[date_updated_at][gte]=2021-04-25
filter[date_updated_at][lte]
string <date> 
ISO 8601 date for filtering room sessions updated before that date.


 
 Example:  filter[date_updated_at][lte]=2021-04-25
filter[date_ended_at][eq]
string <date> 
ISO 8601 date for filtering room sessions ended on that date.


 
 Example:  filter[date_ended_at][eq]=2021-04-25
filter[date_ended_at][gte]
string <date> 
ISO 8601 date for filtering room sessions ended after that date.


 
 Example:  filter[date_ended_at][gte]=2021-04-25
filter[date_ended_at][lte]
string <date> 
ISO 8601 date for filtering room sessions ended before that date.


 
 Example:  filter[date_ended_at][lte]=2021-04-25
filter[active]
boolean
Filter active or inactive room sessions.


 
 Example:  filter[active]=true
include_participants
boolean
To decide if room participants should be included in the response.


 
 Example:  include_participants=true
page[size]
integer  [ 1 .. 250 ] 
 Default:  20
The size of the page


 
page[number]
integer  >= 1 
 Default:  1
The page number to load


 
Responses 
200
List room sessions response.


Response Schema: application/json
Array of objects (RoomSession) 
 
object (PaginationMeta) 
 
get/rooms/{room_id}/sessions
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "active": false,
      • "created_at": "2021-04-16T09:46:20.954863Z",
      • "ended_at": "2021-04-16T10:24:55.962200Z",
      • "id": "7b61621f-62e0-4aad-ab11-9fd19e272e73",
      • "participants": [ ],
      • "record_type": "room_session",
      • "room_id": "7b61621f-5fe4-4aad-ab11-9fd19e272e73",
      • "updated_at": "2021-04-16T10:24:55.962200Z"
      }
    ],
  • "meta": {
    • "page_number": 2,
    • "page_size": 25,
    • "total_pages": 3,
    • "total_results": 55
    }
}