Skip to main content

Create a room composition.

POST 
/room_compositions

Asynchronously create a room composition.

Request ​

Body

required

Parameters that can be defined during room composition creation.

    format stringnullable

    Default value: mp4

    The desired format of the room composition.

    resolution stringnullable

    Default value: 1280x720

    The desired resolution (width/height in pixels) of the resulting video of the room composition. Both width and height are required to be between 16 and 1280; and width * height should not exceed 1280 * 720

    session_id uuidnullable

    id of the room session associated with the room composition.

    video_layout

    object

    Describes the video layout of the room composition in terms of regions.

    property name*

    VideoRegion

    x_pos integernullable

    Default value: 0

    X axis value (in pixels) of the region's upper left corner relative to the upper left corner of the whole room composition viewport.

    y_pos integernullable

    Default value: 0

    Y axis value (in pixels) of the region's upper left corner relative to the upper left corner of the whole room composition viewport.

    z_pos integernullable

    Possible values: >= -99 and <= 99

    Default value: 0

    Regions with higher z_pos values are stacked on top of regions with lower z_pos values

    height integernullable

    Possible values: >= 16

    Height of the video region

    width integernullable

    Possible values: >= 16

    Width of the video region

    max_columns integernullable

    Possible values: >= 1 and <= 1000

    Maximum number of columns of the region's placement grid. By default, the region has as many columns as needed to layout all the specified video sources.

    max_rows integernullable

    Possible values: >= 1 and <= 1000

    Maximum number of rows of the region's placement grid. By default, the region has as many rows as needed to layout all the specified video sources.

    video_sources uuid[]

    Array of video recording ids to be composed in the region. Can be "*" to specify all video recordings in the session

    Describes the video layout of the room composition in terms of regions.

    webhook_event_url url

    The URL where webhooks related to this room composition will be sent. Must include a scheme, such as 'https'.

    webhook_event_failover_url urlnullable

    The failover URL where webhooks related to this room composition will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

    webhook_timeout_secs integernullable

    Possible values: <= 30

    Specifies how many seconds to wait before timing out a webhook.

Responses ​

202: Create room composition response.

Schema

    data

    object

    id uuid

    A unique identifier for the room composition.

    room_id uuid

    Identify the room associated with the room composition.

    session_id uuid

    Identify the room session associated with the room composition.

    user_id uuid

    Identify the user associated with the room composition.

    status string

    Possible values: [completed, enqueued, processing]

    Shows the room composition status.

    size_mb float

    Shows the room composition size in MB.

    download_url string

    Url to download the composition.

    duration_secs integer

    Shows the room composition duration in seconds.

    format string

    Possible values: [mp4]

    Shows format of the room composition.

    created_at datetime

    ISO 8601 timestamp when the room composition was created.

    updated_at datetime

    ISO 8601 timestamp when the room composition was updated.

    ended_at datetime

    ISO 8601 timestamp when the room composition has ended.

    started_at datetime

    ISO 8601 timestamp when the room composition has stated.

    completed_at datetime

    ISO 8601 timestamp when the room composition has completed.

    video_layout

    object

    Describes the video layout of the room composition in terms of regions. Limited to 2 regions.

    property name*

    VideoRegion

    x_pos integernullable

    Default value: 0

    X axis value (in pixels) of the region's upper left corner relative to the upper left corner of the whole room composition viewport.

    y_pos integernullable

    Default value: 0

    Y axis value (in pixels) of the region's upper left corner relative to the upper left corner of the whole room composition viewport.

    z_pos integernullable

    Possible values: >= -99 and <= 99

    Default value: 0

    Regions with higher z_pos values are stacked on top of regions with lower z_pos values

    height integernullable

    Possible values: >= 16

    Height of the video region

    width integernullable

    Possible values: >= 16

    Width of the video region

    max_columns integernullable

    Possible values: >= 1 and <= 1000

    Maximum number of columns of the region's placement grid. By default, the region has as many columns as needed to layout all the specified video sources.

    max_rows integernullable

    Possible values: >= 1 and <= 1000

    Maximum number of rows of the region's placement grid. By default, the region has as many rows as needed to layout all the specified video sources.

    video_sources uuid[]

    Array of video recording ids to be composed in the region. Can be "*" to specify all video recordings in the session

    Describes the video layout of the room composition in terms of regions. Limited to 2 regions.

    webhook_event_url url

    The URL where webhooks related to this room composition will be sent. Must include a scheme, such as 'https'.

    webhook_event_failover_url urlnullable

    The failover URL where webhooks related to this room composition will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

    webhook_timeout_secs integernullable

    Possible values: <= 30

    Specifies how many seconds to wait before timing out a webhook.

    record_type string

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

Schema

    errors

    Error[]

  • Array [

    • code intrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object

  • ]

Request samples

curl -L 'https://api.telnyx.com/v2/room_compositions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "format": "mp4",
  "resolution": "800x600",
  "session_id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777b0",
  "video_layout": {},
  "webhook_event_url": "https://example.com",
  "webhook_event_failover_url": "https://failover.example.com",
  "webhook_timeout_secs": 25
}'

Response samples

{
  "data": {
    "completed_at": "2022-02-25T05:39:56.377426Z",
    "download_url": null,
    "duration_secs": 84,
    "ended_at": "2022-02-24T23:22:24.577677Z",
    "format": "mp4",
    "id": "7103dc53-ee59-4b54-a58b-c77d99ceb037",
    "record_type": "composition",
    "resolution": "1280x720",
    "room_id": "f981dbb3-228a-44e9-ac54-e87f0e2658b0",
    "session_id": "8f728d7b-00e2-4c59-8c27-f564b828df87",
    "size_mb": 6,
    "started_at": "2022-02-24T23:21:00.077209Z",
    "status": "enqueued",
    "user_id": "12a04ec9-0f91-4a91-9f3a-a19d9931182e",
    "video_layout": {
      "first": {
        "height": 720,
        "video_sources": [
          "*"
        ],
        "width": 1280,
        "x_pos": 0,
        "y_pos": 0,
        "z_pos": 0
      }
    },
    "webhook_event_url": "https://webhook.site/544663ce-b692-4f9c-80ed-e5ad97cd5c02"
  }
}