Start or find a direct-message conversation with a member
Finds an existing direct-message room between you (the creator) and the given member, or creates one if none exists yet. This always acts as you — there's no way to start a conversation on behalf of a member with another member through this endpoint.
If a DM room between you and toId already exists, it's returned as-is — newlyCreated: false — with no other effect (no messages, mute state, or anything else about that room is touched). Otherwise a new, empty DM room is created and returned with newlyCreated: true.
toId must be one of your subscribers — someone with a subscription record under you, the creator, of any status (active, expired, or cancelled). Channel membership is not required. An id that doesn't exist at all and an id that exists but has never subscribed to you both fail the same way, with a 404 and errorCode: CHAT_DM_ROOM_MEMBER_NOT_FOUND, so this can't be used to probe whether an arbitrary id belongs to some other creator's platform.
toId cannot be your own id — starting a DM with yourself fails with a 400.
Fails with a 400 if the Community feature is not enabled for this creator, or if you've disabled chat for your own account (disabledChat) — in that case no room can be started with you at all, new or existing lookups included. Fails with a 404 if toId has never subscribed to you.
External access policy
An API key and an authorized white-label host are required. Both tier and plan requirements are enforced.
These requirements apply to the white-label creator for backend-to-backend access. TagMango platform access is not supported.
-
Plans: Unrestricted.
-
Tiers: Unrestricted.
Authorization
bearer In: header
Header Parameters
Host name of the dashboard, ex: mydomain.tagmango.com
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api-prod-new.tagmango.com/api/v1/external/community/chatrooms/dm" \ -H "x-whitelabel-host: string" \ -H "Content-Type: application/json" \ -d '{ "toId": "6659ca9e5f2acb7abfdcd8fd" }'{
"_id": "6659ca9e5f2acb7abfdcd8fd",
"roomType": "dm",
"participants": [
{
"name": "John Doe",
"profilePicUrl": "https://linktoprofilepic.com/pic.jpg",
"_id": "6659ca9e5f2acb7abfdcd8fd"
}
],
"newlyCreated": true
}{
"code": 400,
"type": "Bad Request",
"statusMessage": "BAD_REQUEST",
"success": false,
"message": "Invalid request",
"result": "Invalid request"
}{
"code": 401,
"type": "Unauthorized",
"statusMessage": "UNAUTHORIZED",
"message": "Invalid token",
"result": "Invalid token",
"success": false
}{
"code": 403,
"type": "Forbidden",
"statusMessage": "FORBIDDEN",
"errorCode": "WORKSHOP_MANGO_FORBIDDEN",
"message": "You can not access this api with a TagMango account, only available for whitelabel hosts",
"result": "You can not access this api with a TagMango account, only available for whitelabel hosts",
"success": false
}{
"code": 429,
"type": "Too Many Requests",
"statusMessage": "TOO_MANY_REQUESTS",
"message": "Request limit exceeded. try after 10 seconds",
"result": "Request limit exceeded. try after 10 seconds",
"success": false
}