TagMangoTagMango Docs
Community

Start or find a direct-message conversation with a member

POST
/api/v1/external/community/chatrooms/dm

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.

AuthorizationBearer <token>

In: header

Header Parameters

x-whitelabel-host*string

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
}