Create DM

Prev Next
Post
/api/v1/dm.create

Create a direct message session with another user or more than one user.

The username must belong to a user in the workspace, unless it is a federated username and federation is enabled.

Changelog

Version Description
9.0.0 Required the create-d-other-users permission instead of view-room-administration to use excludeSelf. Limited the response room object to _id, rid, t, and usernames. Rejected usernames that do not exist instead of creating the room without them.
3.18.0 Added excludeSelf option
3.1.0 Added usernames fields
0.59.0 Added
Header parameters
X-Auth-Token
stringRequired

The authToken of the authenticated user.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
X-User-Id
stringRequired

The userId of the authenticated user.

ExamplerbAXPnMktTFbNpwtJ
Body parameters
Example
{
  "username": "kim.dok"
}
Exclude Self
{
  "usernames": "kim.dok,g1",
  "excludeSelf": true
}
OneOf
object
object
username
string Required

The username of the user to open a direct message session.

Examplekim.dok
excludeSelf
boolean

Creates the direct message session excluding the current authenticated user. Requires the create-d-other-users permission. Without it, the request fails with error-not-allowed. With a single username, the request fails with error-invalid-user. Use usernames with at least two usernames instead.

Examplefalse
object
object
usernames
string Required

Comma-separated list of usernames to open a multiple direct message session.

Examplekim.dok,g1
excludeSelf
boolean

Creates the direct message session excluding the current authenticated user. Requires the create-d-other-users permission. Without it, the request fails with error-not-allowed. Include at least two usernames. A single username, in username or usernames, fails with error-invalid-user. An empty usernames value fails with invalid username.

Exampletrue
Responses
200

OK

Example
{
  "room": {
    "_id": "6a1f0c9e2b7d4e8f9a3c5b21",
    "t": "d",
    "rid": "6a1f0c9e2b7d4e8f9a3c5b21",
    "usernames": [
      "g1",
      "rocket.cat"
    ]
  },
  "success": true
}
Exclude Self
{
  "room": {
    "_id": "64f1a2b3c4d5e6f708192a3b",
    "rid": "64f1a2b3c4d5e6f708192a3b",
    "t": "d",
    "usernames": [
      "kim.dok",
      "g1"
    ]
  },
  "success": true
}
Expand All
object
room
object
_id
string
t
string
rid
string
usernames
Array of string
string
success
boolean
400

Bad Request

Empty Usernames
{
  "success": false,
  "error": "invalid username"
}
Missing parameter
{
  "success": false,
  "error": "must have required property 'usernames'\n must have required property 'username'\n must match exactly one schema in oneOf",
  "errorType": "error-invalid-params"
}
Invalid User
{
  "success": false,
  "error": "Invalid user [error-invalid-user]",
  "errorType": "error-invalid-user",
  "details": {
    "method": "createDirectMessage"
  }
}
Permission Error
{
  "success": false,
  "error": "Not allowed [error-not-allowed]",
  "errorType": "error-not-allowed",
  "details": {
    "method": "createDirectMessage"
  }
}
Expand All
object
success
boolean
error
string
errorType
string
details
object
method
string
401

Unauthorized

Authorization Error
{
  "success": false,
  "error": "You must be logged in to do this."
}
object
success
boolean
error
string