API Reference

Chats

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Start a direct chat

client.Chats.Start(ctx, body) (*ChatStartResponse, error)

POST/v1/chats/start

Resolve a user/contact and open a direct chat. Reuses and returns an existing direct chat when one is found. Available in Beeper v4.2.808+.

ParametersExpand Collapse

body ChatStartParams

AccountID param.Field[string]

Account to create or start the chat on.

User param.Field[ChatStartParamsUser]

Contact-like user payload used to resolve the best identifier.

ID stringOptional

Known user ID when available.

Email stringOptional

Email candidate.

FullName stringOptional

Display name hint used for ranking only.

PhoneNumber stringOptional

Phone number candidate (E.164 preferred).

Username stringOptional

Username/handle candidate.

AllowInvite param.Field[bool]Optional

Whether invite-based DM creation is allowed when required by the platform.

MessageText param.Field[string]Optional

Optional first message content if the platform requires it to create the chat.

ReturnsExpand Collapse

type ChatStartResponse struct{…}

DeprecatedChatID string

Use id instead.

DEPRECATED - use id instead. Compatibility alias for older clients.

DeprecatedStatus stringOptional

Inspect the returned Chat instead.

DEPRECATED - legacy start-chat status for older clients. New clients should inspect the returned Chat instead.

One of the following:

const ChatStartResponseStatusExisting ChatStartResponseStatus = "existing"

const ChatStartResponseStatusCreated ChatStartResponseStatus = "created"

Start a direct chat

Go

HTTP

TypeScript

Python

Go

CLI Tool

PHP

package main

import (
  "context"
  "fmt"

  "github.com/beeper/desktop-api-go"
  "github.com/beeper/desktop-api-go/option"
)

func main() {
  client := beeperdesktopapi.NewClient(
    option.WithAccessToken("My Access Token"),
  )
  response, err := client.Chats.Start(context.TODO(), beeperdesktopapi.ChatStartParams{
    AccountID: "accountID",
    User: beeperdesktopapi.ChatStartParamsUser{

    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

200 example

{
  "id": "!team_launch_planning:beeper.com",
  "accountID": "matrix",
  "network": "Beeper",
  "participants": {
    "hasMore": false,
    "items": [
      {
        "id": "@kishanbagaria:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Kishan Bagaria",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "kishanbagaria:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@batuhan:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Batuhan İçöz",
        "imgURL": "imgURL",
        "isSelf": true,
        "phoneNumber": "phoneNumber",
        "username": "batuhan:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@mattwondra:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Matt Wondra",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "mattwondra:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@adamvy:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Adam Van Ymeren",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "adamvy:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      }
    ],
    "total": 4
  },
  "title": "Launch Planning",
  "type": "group",
  "unreadCount": 0,
  "capabilities": {
    "allowedReactions": [
      "string"
    ],
    "archive": true,
    "attachments": {
      "foo": {
        "mimeTypes": {
          "foo": -2
        },
        "caption": -2,
        "maxCaptionLength": 0,
        "maxDuration": 0,
        "maxHeight": 0,
        "maxSize": 0,
        "maxWidth": 0,
        "viewOnce": true
      }
    },
    "customEmojiReactions": true,
    "delete": -2,
    "deleteChat": true,
    "deleteChatForEveryone": true,
    "deleteForMe": true,
    "deleteMaxAge": 0,
    "disappearingTimer": {
      "omitEmptyTimer": true,
      "timers": [
        0
      ],
      "types": [
        "afterRead"
      ]
    },
    "edit": -2,
    "editMaxAge": 0,
    "editMaxCount": 0,
    "formatting": {
      "foo": -2
    },
    "locationMessage": -2,
    "markAsUnread": true,
    "maxTextLength": 0,
    "messageRequest": {
      "acceptWithButton": -2,
      "acceptWithMessage": -2
    },
    "participantActions": {
      "ban": -2,
      "invite": -2,
      "kick": -2,
      "leave": -2,
      "revokeInvite": -2
    },
    "poll": -2,
    "reaction": -2,
    "reactionCount": 0,
    "readReceipts": true,
    "reply": -2,
    "state": {
      "avatar": {
        "level": -2
      },
      "description": {
        "level": -2
      },
      "disappearingTimer": {
        "level": -2
      },
      "title": {
        "level": -2
      }
    },
    "thread": -2,
    "typingNotifications": true
  },
  "description": "description",
  "draft": {
    "text": "text",
    "attachments": {
      "foo": {
        "id": "id",
        "type": "file",
        "audioDurationSeconds": 0,
        "fileName": "fileName",
        "filePath": "filePath",
        "fileSize": 0,
        "mimeType": "mimeType",
        "size": {
          "height": 0,
          "width": 0
        },
        "stickerID": "stickerID"
      }
    }
  },
  "imgURL": "imgURL",
  "isArchived": false,
  "isLowPriority": true,
  "isMarkedUnread": true,
  "isMuted": false,
  "isPinned": false,
  "isReadOnly": true,
  "lastActivity": "2026-05-05T20:12:30.969Z",
  "lastReadMessageSortKey": "862756563",
  "localChatID": "5541",
  "messageExpirySeconds": 0,
  "reminder": {
    "dismissOnIncomingMessage": true,
    "remindAt": "2025-08-31T23:30:12.520Z"
  },
  "snooze": {
    "snoozeUntil": "2025-08-31T23:30:12.520Z",
    "userSnoozedAt": "2025-08-31T23:30:12.520Z"
  },
  "unreadMentionsCount": 0,
  "chatID": "!team_launch_planning:beeper.com",
  "status": "created"
}

Returns Examples

200 example

{
  "id": "!team_launch_planning:beeper.com",
  "accountID": "matrix",
  "network": "Beeper",
  "participants": {
    "hasMore": false,
    "items": [
      {
        "id": "@kishanbagaria:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Kishan Bagaria",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "kishanbagaria:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@batuhan:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Batuhan İçöz",
        "imgURL": "imgURL",
        "isSelf": true,
        "phoneNumber": "phoneNumber",
        "username": "batuhan:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@mattwondra:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Matt Wondra",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "mattwondra:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      },
      {
        "id": "@adamvy:beeper.com",
        "cannotMessage": false,
        "email": "email",
        "fullName": "Adam Van Ymeren",
        "imgURL": "imgURL",
        "isSelf": false,
        "phoneNumber": "phoneNumber",
        "username": "adamvy:beeper.com",
        "isAdmin": true,
        "isNetworkBot": true,
        "isPending": true
      }
    ],
    "total": 4
  },
  "title": "Launch Planning",
  "type": "group",
  "unreadCount": 0,
  "capabilities": {
    "allowedReactions": [
      "string"
    ],
    "archive": true,
    "attachments": {
      "foo": {
        "mimeTypes": {
          "foo": -2
        },
        "caption": -2,
        "maxCaptionLength": 0,
        "maxDuration": 0,
        "maxHeight": 0,
        "maxSize": 0,
        "maxWidth": 0,
        "viewOnce": true
      }
    },
    "customEmojiReactions": true,
    "delete": -2,
    "deleteChat": true,
    "deleteChatForEveryone": true,
    "deleteForMe": true,
    "deleteMaxAge": 0,
    "disappearingTimer": {
      "omitEmptyTimer": true,
      "timers": [
        0
      ],
      "types": [
        "afterRead"
      ]
    },
    "edit": -2,
    "editMaxAge": 0,
    "editMaxCount": 0,
    "formatting": {
      "foo": -2
    },
    "locationMessage": -2,
    "markAsUnread": true,
    "maxTextLength": 0,
    "messageRequest": {
      "acceptWithButton": -2,
      "acceptWithMessage": -2
    },
    "participantActions": {
      "ban": -2,
      "invite": -2,
      "kick": -2,
      "leave": -2,
      "revokeInvite": -2
    },
    "poll": -2,
    "reaction": -2,
    "reactionCount": 0,
    "readReceipts": true,
    "reply": -2,
    "state": {
      "avatar": {
        "level": -2
      },
      "description": {
        "level": -2
      },
      "disappearingTimer": {
        "level": -2
      },
      "title": {
        "level": -2
      }
    },
    "thread": -2,
    "typingNotifications": true
  },
  "description": "description",
  "draft": {
    "text": "text",
    "attachments": {
      "foo": {
        "id": "id",
        "type": "file",
        "audioDurationSeconds": 0,
        "fileName": "fileName",
        "filePath": "filePath",
        "fileSize": 0,
        "mimeType": "mimeType",
        "size": {
          "height": 0,
          "width": 0
        },
        "stickerID": "stickerID"
      }
    }
  },
  "imgURL": "imgURL",
  "isArchived": false,
  "isLowPriority": true,
  "isMarkedUnread": true,
  "isMuted": false,
  "isPinned": false,
  "isReadOnly": true,
  "lastActivity": "2026-05-05T20:12:30.969Z",
  "lastReadMessageSortKey": "862756563",
  "localChatID": "5541",
  "messageExpirySeconds": 0,
  "reminder": {
    "dismissOnIncomingMessage": true,
    "remindAt": "2025-08-31T23:30:12.520Z"
  },
  "snooze": {
    "snoozeUntil": "2025-08-31T23:30:12.520Z",
    "userSnoozedAt": "2025-08-31T23:30:12.520Z"
  },
  "unreadMentionsCount": 0,
  "chatID": "!team_launch_planning:beeper.com",
  "status": "created"
}