Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

Create a chat

$client->chats->create(string accountID, list<string> participantIDs, Type type, ?string messageText, ?string title): ChatNewResponse
POST/v1/chats

Create a direct or group chat from participant IDs. Returns the created chat.

ParametersExpand Collapse
accountID: string

Account to create or start the chat on.

participantIDs: list<string>

User IDs to include in the new chat.

type: Type

‘single’ requires exactly one participantID; ‘group’ supports multiple participants and optional title.

messageText?:optional string

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

title?:optional string

Optional title for group chats; ignored for single chats on most networks.

ReturnsExpand Collapse
string id

Unique identifier of the chat across Beeper.

string accountID

Account ID this chat belongs to.

string network

Display-only human-readable account/network name.

Participants participants

Chat participants information.

string title

Display title of the chat as computed by the client/server.

Type type

Chat type: ‘single’ for direct messages, ‘group’ for group chats.

int unreadCount

Number of unread messages.

?Capabilities capabilities

Chat capabilities reported by the platform.

?string description

Group chat description/topic when available.

?Draft draft

Current draft object for this chat, or null when no draft is set.

?string imgURL

Local filesystem path to the chat avatar image when available.

?bool isArchived

True if chat is archived.

?bool isLowPriority

True if chat is marked low priority.

?bool isMarkedUnread

True if the chat was explicitly marked unread by the authenticated user.

?bool isMuted

True if chat notifications are muted.

?bool isPinned

True if chat is pinned.

?bool isReadOnly

True if messages cannot be sent in this chat.

?\Datetime lastActivity

Timestamp of last activity.

?string lastReadMessageSortKey

Last read message sortKey.

?string localChatID

Local chat ID specific to this installation.

?int messageExpirySeconds

Disappearing-message timer in seconds when available.

?Reminder reminder

Current reminder for this chat, or null when no reminder is set.

?Snooze snooze

Current snooze state for this chat, or null when no snooze is set.

?int unreadMentionsCount

Number of unread messages that mention the authenticated user or @room.

Deprecatedstring chatID
Use id instead.

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

Deprecated?Status status
Inspect the returned Chat instead.

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

Create a chat

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$chat = $client->chats->create(
  accountID: 'accountID',
  participantIDs: ['string'],
  type: 'single',
  messageText: 'messageText',
  title: 'title',
);

var_dump($chat);
{
  "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
{
  "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"
}