# chat_start_dm

Start Direct Message

## Beschreibung

Find-or-create the account-wide 1-on-1 DM channel with another
internal account member. A second call with the same participant
returns the same `chan_…` id and
un-archives a dormant DM (matching the web UI's "New DM" picker).

Use when `chat_list_channels` doesn't already show a DM with
the partner. Both participants must be active internal members of the
same account; guests cannot create, see, or receive DMs. DMing yourself
is rejected.
`name` on the returned
channel is an opaque internal id — render the partner's handle
in UI copy instead.

## Zugriff

Zugriffsprofil: `basic`. Module: `chat`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja | Account prefix ID (e.g., acct_abc123). |
| `user_id` | string | Ja | Partner's prefix ID (user_…), @handle, or bare handle (e.g., 'kurth' or '@kurth'). Must be an active internal member of the account. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (e.g., acct_abc123)."
    },
    "user_id": {
      "type": "string",
      "description": "Partner's prefix ID (user_…), @handle, or bare handle (e.g., 'kurth' or '@kurth'). Must be an active internal member of the account."
    }
  },
  "required": [
    "account_id",
    "user_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "channel": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Channel prefix ID (chan_…) — pass to chat_send_message / chat_get_messages."
        },
        "workspace_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Always null for account-wide DMs."
        },
        "name": {
          "type": "string",
          "description": "Opaque internal name; render the partner's handle in UI copy."
        },
        "channel_type": {
          "type": "string",
          "enum": [
            "direct"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "is_archived": {
          "type": "boolean"
        },
        "last_message_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "is_member": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "workspace_id",
        "name",
        "channel_type",
        "is_archived",
        "is_member"
      ]
    }
  },
  "required": [
    "channel"
  ],
  "type": "object"
}
```