Channels Management

Channel Basics

Create a channel

POST /channels/create

Create a new channel. If this call succeeds, The response body will contain the UUID of the newly created channel.

Request JSON Object:

  • name (string) – Channel’s name

  • description (option[string]) – [default: None] Channel description

Response JSON Object:

  • channelUuid (string) – Unique channel id

Delete a channel

DELETE /channels/(string: uuid)

Delete the specified channel.

Parameters:

  • uuid (string) – UUID of the channel to be deleted.

Drop channel image

DELETE /channels/(string: uuid)/image

Allows to remove the image associated with a channel.

Parameters:

  • uuid (string)

Get channel details

GET /channels/(string: uuid)

Return detailed information about this channel.

Parameters:

  • uuid (string) – Channel UUID you want to get details for.

Query Parameters:

  • imgSize (string) – [optional] the desired size of the channel image to return

Response JSON Object:

  • parent (option[string]) – The uuid of the parent channel to this channel (if it is a child channel)

  • isFavorite (boolean) – True if the user has favorited this channel

  • name (string) – Compounded (legacy) name for the channel. Defaults to the canonical name for base channels

  • serviceMode (string) – Current channel mode (panel or conference)

  • reputation (int) – Channel overall reputation on a scale of 1::15

  • clientId (string) – Client identifier

  • favorite (int) – Number of times that this channel has been favourited

  • isStar (boolean) – True if the channel is a star channel

  • isOperator (boolean) – True if the user is an operator in this channel

  • description (option[string]) – Owner’s description of this channel

  • channelName (string) – The canonical name of the channel

  • maxUsers (int) – Maximum amount of users that channel can handle

  • urlName (string) – UUID providing the direct link to this channel in the UI

  • meetingId (string) – Unique identifier that can be used in dial-in or on launchers.

  • isEventRoom (boolean) – True if the channel is an event room

  • makePrivate (boolean) – True if the channel can be switch to private

  • isOrganization (boolean) – True if the channel is a organization channel, used in conferencing

  • friendlyURL (option[string]) – Unique (in client context) URL path to this channel (used by Meeting Launcher)

  • isOwner (boolean) – True if the user owns this channel

  • isMidi (boolean) – True if the channel has midi token assigned

  • parentName (option[string]) – The name of the parent channel to this channel (if it is a child channel)

  • audioQuality (string) – Audio quality settings. Currently, this is ‘toll’ or ‘broadcast’

  • channelUuid (string) – Channel identifier

  • isPrivate (boolean) – True if the channel is private

  • isOpen (boolean) – True if lobby doors are open

  • offAir (boolean) – True channel is Off Air (no content is being sent to listeners in Panel Mode)

  • isRangeEnabled (boolean) – True if the channel allows range filtering

  • isPremium (boolean) – True if the channel has premium token assigned

  • disableWall (boolean) – True Wall is disabled for this channel

  • guestAccess (boolean) – True if guests are allowed in this channel

  • imageUrl (option[string]) – The location of the channel image

Set channel description

POST /channels/(string: uuid)/description

Each channel can be described by a text field up to 200 characters in length.

Parameters:

  • uuid (string) – The channel whose description must be updated.

Request JSON Object:

  • description (string) – A text description for the channel. If the string is empty, the channel’s description is cleared

Set channel image

POST /channels/(string: uuid)/image

Sets or updates the image associated with a channel. Images can be specified either by URL or by adding image binaries directly in the request body. (If both are provided, the URL will be used.) If a URL is specified, the image will be downloaded and saved at the time the call is made.

Parameters:

  • uuid (string) – The channel ID

Query Parameters:

  • url (string) – A URL specifiying where the image may be downloaded. This is required if the image is not specified in the body of the request.

Set channel name

POST /channels/(string: uuid)/rename

Set or update the channel name.

Parameters:

  • uuid (string) – Id of channel to rename

Query Parameters:

  • name (string)

Runtime Operations

Disabling wall messages

POST /channels/(string: uuid)/settings/wall/(string: state)

Wall messages can be disabled for the entire channel. This is most often applicable to panel sessions with a large number of users.

Parameters:

  • uuid (string) – The channel ID

  • state (string) – Can be one of enable/disable

Drop presenters limit

DELETE /channels/(string: uuid)/settings/presenters/limit

Clear the presenter limit, which allows an unlimited number of to be presenters. See the corresponding POST call for more detail about presenter limits.

Parameters:

  • uuid (string) – Channel ID

Get channel TURN credentials

GET /channels/(string: uuid)/turn/credentials

If the client needs the services of a TURN server, it needs to get a list of supported TURN servers as well as the credentials needed to access that server. This function returns a data structure suitable for initialising the WebRTC subsystem to use the TURN service to achieve its connectivity with Horn. It returns a user name and password required by the TURN servers as well as a list of TURN servers that can access this channel. See the WebRTC documentation for more details.

Parameters:

  • uuid (string) – The channel ID for the target channel

Response JSON Object:

  • username (string) – The timestamp:username

  • password (string) – Password to use for this transaction

  • ttl (int) – Life time of the credentials

  • uris (list[string]) – A list of servers to try to connect to.

Get channel population list

GET /channels/populations/(string: channelIds)

Return the current active population for the specified channels. This is the current number of users connected to a live channel. The path parameter is a comma separated list of channel UUIDS. Non-conforming channel uuids are simply dropped. This request is limited to a maximum of 200 channels.

Parameters:

  • channelIds (string) – Comma separated list of channel IDs.

Get data channels URL

GET /channels/(string: uuid)/data/(string: kind)

Return the URL for a data channels on a proper streaming server. This URL can be used by the interface to connect to a given Data Channel WebSocket.

Parameters:

  • uuid (string) – The channel ID for the target channel

  • kind (string) – Kind of a data channel

Response JSON Object:

  • url (string) – The url to connect to for this channel

  • mode (option[string]) – The current mode of the channel

Get proxy for channel

GET /channels/(string: uuid)/proxyfor

Return the URL for the proxy managing the streaming API (websocket) for a given channel. The normal workflow for connecting to a channel (once the user has authenticated) is to select a channel then request the websocket proxy address for the streaming server on which this channel is hosted. The client can then connect to the streaming server and use the streaming API to manage the real time workflow for an active channel. Occasionally, a client may attempt to connect to a channel that is currently being created on a streaming server. The response code in these cases will be 409 (Conflicted). The client should wait for 1 second and re-attempt the connection.

Parameters:

  • uuid (string) – ID of the channel to get proxy for.

Response JSON Object:

  • url (string) – The url to connect to for this channel

  • mode (option[string]) – The current mode of the channel

List active channels

GET /channels/active

Returns the list of current active channels and channels that user owns.

Query Parameters:

  • imgSize (string) – Optional parameter that defines which size of image will be returned

Response JSON Array of Objects:

  • serviceMode (string)

  • description (option[string])

  • channelName (string)

  • participants (channelparticipants)

  • isOwner (boolean)

  • channelUuid (string)

  • imageUrl (option[string])

Set presenters limit

POST /channels/(string: uuid)/settings/presenters/limit/(number: limit)

Set the maximum number of users able to share video (web cam or screenshare) at a given time. Users who are able to share video are “Presenters”. Users who are not able to share video are “Attendees”. The meeting host is able to grant or revoke “Presenter” status from a user at any time during a meeting.

Parameters:

  • uuid (string) – Channel ID

  • limit (number) – Number of presenters

Lobby Configuration

Automatically close lobby door

POST /channels/(string: uuid)/settings/lobby/door/auto-close/(string: state)

If set to “enable”, the lobby door will close whenever the channel becomes empty (i.e. has no users in it). When a channel is mapped to a predictable URL, this ensures that the door won’t be left open by accident after a session has concluded.

Parameters:

  • uuid (string) – The channel ID

  • state (string) – “enable” or “disable”

Setting lobby state

POST /channels/(string: uuid)/settings/lobby/door/(string: state)

Lobby can be set to one of two states: - open - everyone can join the channel - close - users have to wait for an invitation from operator before entering the channel

Parameters:

  • uuid (string) – The channel ID

  • state (string) – Can be one of open/close

Channel Properties

Channel properties are arbitrary attributes that can be assigned to a channel, allowing storage of custom JSON data.

Multiple properties can be set on a single channel, providing a flexible way to store implementation-specific contextual information.

Properties are managed by channel hosts and are visible to all users who have access to the channel. This makes them particularly useful for storing channel-related metadata, configuration settings, or any other custom data that needs to be shared across all channel participants.

Delete channel property

DELETE /channels/(string: uuid)/properties/(string: key)

Allows to delete a property tied to a channel.

Parameters:

  • uuid (string) – The channel ID

  • key (string) – The property key

Get channel property

GET /channels/(string: uuid)/properties/(string: key)

Allows to get arbitrary properties tied to a channel UUID, it can persist various kinds of custom state and/or data that are relevant to third party integrations. When requesting a properties the value will be return as a JSON in the response body.

Parameters:

  • uuid (string) – The channel ID

  • key (string) – The property key

Response: JSON

List channel properties

GET /channels/(string: uuid)/properties

Allows to list all keys of properties tied to a channel UUID

Parameters:

  • uuid (string) – The channel ID

Set channel property

POST /channels/(string: uuid)/properties/(string: key)

Allows to set arbitrary properties tied to a channel UUID, it can persist various kinds of custom state and/or data that are relevant to third party integrations. Value for the property should be send as a json in the request body. The call will accept any json, save it under given key and allow to fetch it back.

Parameters:

  • uuid (string) – The channel ID

  • key (string) – The property key

Request: JSON

Channel Configuration

Auto-lock attendees

POST /channels/(string: uuid)/settings/attendees/(string: state)

If enabled, attendees will be automatically locked (muted, won’t be able to unmute themselves) in a channel. This call can be only be made by host.

Parameters:

  • uuid (string) – The channel ID

  • state (string) – Can be one of mute/unmute

Speech to text transcription

POST /channels/(string: uuid)/settings/speech2text/(string: state)

Enables automatic speech to text transcription for a given channel. Note: use of this option may incur metered charges depending on your organization’s license agreement, so the call can only be made by users who have the “Customer Admin” role.

Parameters:

  • uuid (string) – The channel ID

  • state (string) – Can be one of enable/disable

Enabling midi to a channel

POST /channels/(string: uuid)/settings/midi/(string: state)

If enabled, MIDI features will be available for a channel. This call can be only be made by Channel Owner

Parameters:

  • uuid (string) – The channel ID

  • state (string) – Can be one of enable/disable

Other Channel Routes

Finds channel ID by meeting ID

GET /channels

Looks for channel based on meetingId. This is used by our SIP engine to find channel when user connects via phone and enters meeting ID via SIP dialing.

Query Parameters:

  • meetingId (string) – Unique meeting identifier

Response JSON Object:

  • uuid (string) – The uuid of channel

Get client ID by channel ID

GET /channels/(string: channelUuid)/client

Helper to get client id associated with a channel.

Parameters:

  • channelUuid (string)

Response JSON Object:

  • id (string) – Client identifier

List channels

GET /channels

List all channels matching given criteria. This method returns all channels where user has at least channel operator privileges. Customer Admins will get all channels within given customer context.

Query Parameters:

  • limit (string) – Limit amount of results. Needed for implementing pagination

  • offset (string) – Offset at which start looking for results in database. Needed for implementing pagination

  • search (string) – String to filter channels by

  • imgSize (string) – [optional] The desired size of the channel image to return

  • sort (string) – By what column sort results. Possible values: [“created”, “name”]. Default is “created”

  • order (string) – In which order sort results. Possible values: [“asc”, “desc”]. Default is “desc”

Response JSON Object:

  • name (string) – The channel’s horn name which is unique

  • urlName (option[string]) – [default: None]

  • friendlyURL (option[string]) – A human readable name for this channel as part of its URL which is also unique in the client context

  • isOwner (boolean) – If provided it indicates whatever user requesting this channel info is an owner of it or not This field is optional because there are cases where it won’t be provided - i.e. when we list all channels from arrakis w/o any limitation. If the field is provided, it means requesting user has to be operator of this channel

  • parentName (option[string]) – [default: None] The parent name for this channel if it is the child of a star channel

  • channelUuid (string) – The channel UUID

  • isOpen (boolean) – True if lobby doors are open

  • guestAccess (boolean) – True if guests are allowed in this channel

  • imageUrl (option[string]) – [default: None] URL for image of channel

  • parentId (option[string]) – [default: None] The parent id for this channel if it is the child of a star channel

  • created (long) – Timestamp at which channel was created (in seconds)