Skip to main content
Create Direct Conversation
Returns an existing DM between the caller and the target user, or creates one if it does not yet exist. Only one direct conversation can exist per user pair per project — this endpoint is idempotent. Returns 201 when a new conversation was created, 200 when an existing one was found.

Body Parameters

string
required
The ID of the user to start a direct conversation with. Must belong to the same project.
string
Service key only, and required with one: the user this request acts as. One side of the conversation; userId is the other. A user token always acts as its own user and must not send it (400 chat/acting-user-not-allowed).

Response

Returns a Conversation object with type: "direct".
Direct conversations cannot be updated or deleted, and members cannot leave them. They persist as long as either user’s account exists.

Error Responses

A user token sent actingUserId, even naming its own user. Only a service key names the user it acts as; a user token always acts as its own user.
Returned when a service key names an actingUserId that isn’t a user in this project.
A service key sent no actingUserId.