Sign in

v58

latestOpenAPI 3.0.3agplraw.githubusercontent.com2026-08-01187461.6 MB
room

Create a room with a user, a group or a circle

With the conversation-creation-all capability a lot of new options where introduced. Before that only $roomType, $roomName, $objectType and $objectId were supported all the time, and $password with the conversation-creation-password capability In case the $roomType is {@see Room::TYPE_ONE_TO_ONE} only the $invite or $participants parameter is supported. The endpoint can also be used unauthenticated by an external call service by signing the request with the configured shared secret via the x-nextcloud-talk-external-service-random and x-nextcloud-talk-external-service-checksum headers (SHA256-HMAC of the random seed and the $owner user ID).

post/ocs/v2.php/apps/spreed/api/{apiVersion}/room

Path parameters

apiVersion'v4' required

Headers

x-nextcloud-talk-external-service-randomstring

Random seed (at least 32 bytes) used together with the owner user ID to generate the SHA256-HMAC request checksum

x-nextcloud-talk-external-service-checksumstring

SHA256-HMAC checksum over the concatenation of the random seed and the owner user ID, signed with the shared external call service secret, to verify authenticity from the external call service

OCS-APIRequestboolean required

Required to be true for the API request to pass

Request body

roomTypeinteger

Type of the room

invitestring

User, group, … ID to invite Deprecated: Use the $participants array instead

roomNamestring

Name of the room, unless the legacy mode providing $invite and $source is used, the name must no longer be empty with the conversation-creation-all capability (Ignored if $roomType is {@see Room::TYPE_ONE_TO_ONE})

sourcestring

Source of the invite ID ('circles' to create a room with a circle, etc.) Deprecated: Use the $participants array instead

objectTypestring

Type of the object (Ignored if $roomType is {@see Room::TYPE_ONE_TO_ONE})

objectIdstring

ID of the object (Ignored if $roomType is {@see Room::TYPE_ONE_TO_ONE})

passwordstring

The room password (only available with conversation-creation-password capability) (Ignored if $roomType is not {@see Room::TYPE_PUBLIC})

readOnly0 | 1

Read only state of the conversation (Default writable) (only available with conversation-creation-all capability)

listable0 | 1 | 2

Scope where the conversation is listable (Default not listable for anyone) (only available with conversation-creation-all capability)

messageExpirationinteger

Seconds after which messages will disappear, 0 disables expiration (Default 0) (only available with conversation-creation-all capability)

lobbyState0 | 1

Lobby state of the conversation (Default lobby is disabled) (only available with conversation-creation-all capability)

lobbyTimerinteger nullable

Timer when the lobby will be removed (Default null, will not be disabled automatically) (only available with conversation-creation-all capability)

sipEnabled0 | 1 | 2

Whether SIP dial-in shall be enabled (only available with conversation-creation-all capability)

permissionsinteger

Default permissions for participants (only available with conversation-creation-all capability)

recordingConsent0 | 1

Whether participants need to agree to a recording before joining a call (only available with conversation-creation-all capability)

mentionPermissions0 | 1

Who can mention at-all in the chat (only available with conversation-creation-all capability)

descriptionstring

Description for the conversation (limited to 2.000 characters) (only available with conversation-creation-all capability)

emojistring nullable

Emoji for the avatar of the conversation (only available with conversation-creation-all capability)

avatarColorstring nullable

Background color of the avatar (Only considered when an emoji was provided) (only available with conversation-creation-all capability)

ownerstring

User ID that will be used as actor and made owner of the conversation. Required when the request is authenticated via the x-nextcloud-talk-external-service-random and x-nextcloud-talk-external-service-checksum headers, otherwise ignored.

presetstring nullable

Identifier of the preset that was used (only available with conversation-preset capability)

Response

Room already existed