# Chats ## Retrieve `client.Chats.Get(ctx, chatID, query) (*Chat, error)` **get** `/v1/chats/{chatID}` Retrieve chat details including metadata, participants, and latest message ### Parameters - `chatID string` Unique identifier of the chat. - `query ChatGetParams` - `MaxParticipantCount param.Field[int64]` Maximum number of participants to return. Use -1 for all; otherwise 0–500. Defaults to all (-1). ### Returns - `type Chat struct{…}` - `ID string` Unique identifier of the chat across Beeper. - `AccountID string` Account ID this chat belongs to. - `Participants ChatParticipants` Chat participants information. - `HasMore bool` True if there are more participants than included in items. - `Items []User` Participants returned for this chat (limited by the request; may be a subset). - `ID string` Stable Beeper user ID. Use as the primary key when referencing a person. - `CannotMessage bool` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `Email string` Email address if known. Not guaranteed verified. - `FullName string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `ImgURL string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `IsSelf bool` True if this user represents the authenticated account's own identity. - `PhoneNumber string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `Username string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `Total int64` Total number of participants in the chat. - `Title string` Display title of the chat as computed by the client/server. - `Type ChatType` Chat type: 'single' for direct messages, 'group' for group chats. - `const ChatTypeSingle ChatType = "single"` - `const ChatTypeGroup ChatType = "group"` - `UnreadCount int64` Number of unread messages. - `IsArchived bool` True if chat is archived. - `IsMuted bool` True if chat notifications are muted. - `IsPinned bool` True if chat is pinned. - `LastActivity Time` Timestamp of last activity. - `LastReadMessageSortKey string` Last read message sortKey. - `LocalChatID string` Local chat ID specific to this Beeper Desktop installation. ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) chat, err := client.Chats.Get( context.TODO(), "!NCdzlIaMjZUmvmvyHU:beeper.com", beeperdesktopapi.ChatGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chat.ID) } ``` ## Create `client.Chats.New(ctx, body) (*ChatNewResponse, error)` **post** `/v1/chats` Create a single/group chat (mode='create') or start a direct chat from merged user data (mode='start'). ### Parameters - `body ChatNewParams` - `AccountID param.Field[string]` Account to create or start the chat on. - `AllowInvite param.Field[bool]` Whether invite-based DM creation is allowed when required by the platform. Used for mode='start'. - `MessageText param.Field[string]` Optional first message content if the platform requires it to create the chat. - `Mode param.Field[ChatNewParamsMode]` Operation mode. Defaults to 'create' when omitted. - `const ChatNewParamsModeCreate ChatNewParamsMode = "create"` - `const ChatNewParamsModeStart ChatNewParamsMode = "start"` - `ParticipantIDs param.Field[[]string]` Required when mode='create'. User IDs to include in the new chat. - `Title param.Field[string]` Optional title for group chats when mode='create'; ignored for single chats on most platforms. - `Type param.Field[ChatNewParamsType]` Required when mode='create'. 'single' requires exactly one participantID; 'group' supports multiple participants and optional title. - `const ChatNewParamsTypeSingle ChatNewParamsType = "single"` - `const ChatNewParamsTypeGroup ChatNewParamsType = "group"` - `User param.Field[ChatNewParamsUser]` Required when mode='start'. Merged user-like contact payload used to resolve the best identifier. - `ID string` Known user ID when available. - `Email string` Email candidate. - `FullName string` Display name hint used for ranking only. - `PhoneNumber string` Phone number candidate (E.164 preferred). - `Username string` Username/handle candidate. ### Returns - `type ChatNewResponse struct{…}` - `ChatID string` Newly created chat ID. - `Status ChatNewResponseStatus` Only returned in start mode. 'existing' means an existing chat was reused; 'created' means a new chat was created. - `const ChatNewResponseStatusExisting ChatNewResponseStatus = "existing"` - `const ChatNewResponseStatusCreated ChatNewResponseStatus = "created"` ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) chat, err := client.Chats.New(context.TODO(), beeperdesktopapi.ChatNewParams{ AccountID: "accountID", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chat.ChatID) } ``` ## List `client.Chats.List(ctx, query) (*CursorNoLimit[ChatListResponse], error)` **get** `/v1/chats` List all chats sorted by last activity (most recent first). Combines all accounts into a single paginated list. ### Parameters - `query ChatListParams` - `AccountIDs param.Field[[]string]` Limit to specific account IDs. If omitted, fetches from all accounts. - `Cursor param.Field[string]` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `Direction param.Field[ChatListParamsDirection]` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `const ChatListParamsDirectionAfter ChatListParamsDirection = "after"` - `const ChatListParamsDirectionBefore ChatListParamsDirection = "before"` ### Returns - `type ChatListResponse struct{…}` - `Preview Message` Last message preview for this chat, if available. - `ID string` Message ID. - `AccountID string` Beeper account ID the message belongs to. - `ChatID string` Unique identifier of the chat. - `SenderID string` Sender user ID. - `SortKey string` A unique, sortable key used to sort messages. - `Timestamp Time` Message timestamp. - `Attachments []Attachment` Attachments included with this message, if any. - `Type AttachmentType` Attachment type. - `const AttachmentTypeUnknown AttachmentType = "unknown"` - `const AttachmentTypeImg AttachmentType = "img"` - `const AttachmentTypeVideo AttachmentType = "video"` - `const AttachmentTypeAudio AttachmentType = "audio"` - `ID string` Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path. - `Duration float64` Duration in seconds (audio/video). - `FileName string` Original filename if available. - `FileSize float64` File size in bytes if known. - `IsGif bool` True if the attachment is a GIF. - `IsSticker bool` True if the attachment is a sticker. - `IsVoiceNote bool` True if the attachment is a voice note. - `MimeType string` MIME type if known (e.g., 'image/png'). - `PosterImg string` Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed. - `Size AttachmentSize` Pixel dimensions of the attachment: width/height in px. - `Height float64` - `Width float64` - `SrcURL string` Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed. - `IsSender bool` True if the authenticated user sent the message. - `IsUnread bool` True if the message is unread for the authenticated user. May be omitted. - `LinkedMessageID string` ID of the message this is a reply to, if any. - `Reactions []Reaction` Reactions to the message, if any. - `ID string` Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise. - `ParticipantID string` User ID of the participant who reacted. - `ReactionKey string` The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face". - `Emoji bool` True if the reactionKey is an emoji. - `ImgURL string` URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed. - `SenderName string` Resolved sender display name (impersonator/full name/username/participant name). - `Text string` Plain-text body if present. May include a JSON fallback with text entities for rich messages. - `Type MessageType` Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages. - `const MessageTypeText MessageType = "TEXT"` - `const MessageTypeNotice MessageType = "NOTICE"` - `const MessageTypeImage MessageType = "IMAGE"` - `const MessageTypeVideo MessageType = "VIDEO"` - `const MessageTypeVoice MessageType = "VOICE"` - `const MessageTypeAudio MessageType = "AUDIO"` - `const MessageTypeFile MessageType = "FILE"` - `const MessageTypeSticker MessageType = "STICKER"` - `const MessageTypeLocation MessageType = "LOCATION"` - `const MessageTypeReaction MessageType = "REACTION"` ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) page, err := client.Chats.List(context.TODO(), beeperdesktopapi.ChatListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` ## Search `client.Chats.Search(ctx, query) (*CursorSearch[Chat], error)` **get** `/v1/chats/search` Search chats by title/network or participants using Beeper Desktop's renderer algorithm. ### Parameters - `query ChatSearchParams` - `AccountIDs param.Field[[]string]` Provide an array of account IDs to filter chats from specific messaging accounts only - `Cursor param.Field[string]` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `Direction param.Field[ChatSearchParamsDirection]` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `const ChatSearchParamsDirectionAfter ChatSearchParamsDirection = "after"` - `const ChatSearchParamsDirectionBefore ChatSearchParamsDirection = "before"` - `Inbox param.Field[ChatSearchParamsInbox]` Filter by inbox type: "primary" (non-archived, non-low-priority), "low-priority", or "archive". If not specified, shows all chats. - `const ChatSearchParamsInboxPrimary ChatSearchParamsInbox = "primary"` - `const ChatSearchParamsInboxLowPriority ChatSearchParamsInbox = "low-priority"` - `const ChatSearchParamsInboxArchive ChatSearchParamsInbox = "archive"` - `IncludeMuted param.Field[bool]` Include chats marked as Muted by the user, which are usually less important. Default: true. Set to false if the user wants a more refined search. - `LastActivityAfter param.Field[Time]` Provide an ISO datetime string to only retrieve chats with last activity after this time - `LastActivityBefore param.Field[Time]` Provide an ISO datetime string to only retrieve chats with last activity before this time - `Limit param.Field[int64]` Set the maximum number of chats to retrieve. Valid range: 1-200, default is 50 - `Query param.Field[string]` Literal token search (non-semantic). Use single words users type (e.g., "dinner"). When multiple words provided, ALL must match. Case-insensitive. - `Scope param.Field[ChatSearchParamsScope]` Search scope: 'titles' matches title + network; 'participants' matches participant names. - `const ChatSearchParamsScopeTitles ChatSearchParamsScope = "titles"` - `const ChatSearchParamsScopeParticipants ChatSearchParamsScope = "participants"` - `Type param.Field[ChatSearchParamsType]` Specify the type of chats to retrieve: use "single" for direct messages, "group" for group chats, or "any" to get all types - `const ChatSearchParamsTypeSingle ChatSearchParamsType = "single"` - `const ChatSearchParamsTypeGroup ChatSearchParamsType = "group"` - `const ChatSearchParamsTypeAny ChatSearchParamsType = "any"` - `UnreadOnly param.Field[bool]` Set to true to only retrieve chats that have unread messages ### Returns - `type Chat struct{…}` - `ID string` Unique identifier of the chat across Beeper. - `AccountID string` Account ID this chat belongs to. - `Participants ChatParticipants` Chat participants information. - `HasMore bool` True if there are more participants than included in items. - `Items []User` Participants returned for this chat (limited by the request; may be a subset). - `ID string` Stable Beeper user ID. Use as the primary key when referencing a person. - `CannotMessage bool` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `Email string` Email address if known. Not guaranteed verified. - `FullName string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `ImgURL string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `IsSelf bool` True if this user represents the authenticated account's own identity. - `PhoneNumber string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `Username string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `Total int64` Total number of participants in the chat. - `Title string` Display title of the chat as computed by the client/server. - `Type ChatType` Chat type: 'single' for direct messages, 'group' for group chats. - `const ChatTypeSingle ChatType = "single"` - `const ChatTypeGroup ChatType = "group"` - `UnreadCount int64` Number of unread messages. - `IsArchived bool` True if chat is archived. - `IsMuted bool` True if chat notifications are muted. - `IsPinned bool` True if chat is pinned. - `LastActivity Time` Timestamp of last activity. - `LastReadMessageSortKey string` Last read message sortKey. - `LocalChatID string` Local chat ID specific to this Beeper Desktop installation. ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) page, err := client.Chats.Search(context.TODO(), beeperdesktopapi.ChatSearchParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` ## Archive `client.Chats.Archive(ctx, chatID, body) error` **post** `/v1/chats/{chatID}/archive` Archive or unarchive a chat. Set archived=true to move to archive, archived=false to move back to inbox ### Parameters - `chatID string` Unique identifier of the chat. - `body ChatArchiveParams` - `Archived param.Field[bool]` True to archive, false to unarchive ### Example ```go package main import ( "context" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) err := client.Chats.Archive( context.TODO(), "!NCdzlIaMjZUmvmvyHU:beeper.com", beeperdesktopapi.ChatArchiveParams{ }, ) if err != nil { panic(err.Error()) } } ``` ## Domain Types ### Chat - `type Chat struct{…}` - `ID string` Unique identifier of the chat across Beeper. - `AccountID string` Account ID this chat belongs to. - `Participants ChatParticipants` Chat participants information. - `HasMore bool` True if there are more participants than included in items. - `Items []User` Participants returned for this chat (limited by the request; may be a subset). - `ID string` Stable Beeper user ID. Use as the primary key when referencing a person. - `CannotMessage bool` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `Email string` Email address if known. Not guaranteed verified. - `FullName string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `ImgURL string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `IsSelf bool` True if this user represents the authenticated account's own identity. - `PhoneNumber string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `Username string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `Total int64` Total number of participants in the chat. - `Title string` Display title of the chat as computed by the client/server. - `Type ChatType` Chat type: 'single' for direct messages, 'group' for group chats. - `const ChatTypeSingle ChatType = "single"` - `const ChatTypeGroup ChatType = "group"` - `UnreadCount int64` Number of unread messages. - `IsArchived bool` True if chat is archived. - `IsMuted bool` True if chat notifications are muted. - `IsPinned bool` True if chat is pinned. - `LastActivity Time` Timestamp of last activity. - `LastReadMessageSortKey string` Last read message sortKey. - `LocalChatID string` Local chat ID specific to this Beeper Desktop installation. # Reminders ## Create `client.Chats.Reminders.New(ctx, chatID, body) error` **post** `/v1/chats/{chatID}/reminders` Set a reminder for a chat at a specific time ### Parameters - `chatID string` Unique identifier of the chat. - `body ChatReminderNewParams` - `Reminder param.Field[ChatReminderNewParamsReminder]` Reminder configuration - `RemindAtMs float64` Unix timestamp in milliseconds when reminder should trigger - `DismissOnIncomingMessage bool` Cancel reminder if someone messages in the chat ### Example ```go package main import ( "context" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) err := client.Chats.Reminders.New( context.TODO(), "!NCdzlIaMjZUmvmvyHU:beeper.com", beeperdesktopapi.ChatReminderNewParams{ Reminder: beeperdesktopapi.ChatReminderNewParamsReminder{ RemindAtMs: 0, }, }, ) if err != nil { panic(err.Error()) } } ``` ## Delete `client.Chats.Reminders.Delete(ctx, chatID) error` **delete** `/v1/chats/{chatID}/reminders` Clear an existing reminder from a chat ### Parameters - `chatID string` Unique identifier of the chat. ### Example ```go package main import ( "context" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) err := client.Chats.Reminders.Delete(context.TODO(), "!NCdzlIaMjZUmvmvyHU:beeper.com") if err != nil { panic(err.Error()) } } ``` # Messages # Reactions ## Add `client.Chats.Messages.Reactions.Add(ctx, messageID, params) (*ChatMessageReactionAddResponse, error)` **post** `/v1/chats/{chatID}/messages/{messageID}/reactions` Add a reaction to an existing message. ### Parameters - `messageID string` - `params ChatMessageReactionAddParams` - `ChatID param.Field[string]` Path param: Unique identifier of the chat. - `ReactionKey param.Field[string]` Body param: Reaction key to add (emoji, shortcode, or custom emoji key) - `TransactionID param.Field[string]` Body param: Optional transaction ID for deduplication and local echo tracking ### Returns - `type ChatMessageReactionAddResponse struct{…}` - `ChatID string` Unique identifier of the chat. - `MessageID string` Message ID. - `ReactionKey string` Reaction key that was added - `Success bool` Whether the reaction was successfully added - `const ChatMessageReactionAddResponseSuccessTrue ChatMessageReactionAddResponseSuccess = true` - `TransactionID string` Transaction ID used for the reaction event ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) response, err := client.Chats.Messages.Reactions.Add( context.TODO(), "messageID", beeperdesktopapi.ChatMessageReactionAddParams{ ChatID: "!NCdzlIaMjZUmvmvyHU:beeper.com", ReactionKey: "x", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ChatID) } ``` ## Delete `client.Chats.Messages.Reactions.Delete(ctx, messageID, params) (*ChatMessageReactionDeleteResponse, error)` **delete** `/v1/chats/{chatID}/messages/{messageID}/reactions` Remove the authenticated user's reaction from an existing message. ### Parameters - `messageID string` - `params ChatMessageReactionDeleteParams` - `ChatID param.Field[string]` Path param: Unique identifier of the chat. - `ReactionKey param.Field[string]` Query param: Reaction key to remove ### Returns - `type ChatMessageReactionDeleteResponse struct{…}` - `ChatID string` Unique identifier of the chat. - `MessageID string` Message ID. - `ReactionKey string` Reaction key that was removed - `Success bool` Whether the reaction was successfully removed - `const ChatMessageReactionDeleteResponseSuccessTrue ChatMessageReactionDeleteResponseSuccess = true` ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) reaction, err := client.Chats.Messages.Reactions.Delete( context.TODO(), "messageID", beeperdesktopapi.ChatMessageReactionDeleteParams{ ChatID: "!NCdzlIaMjZUmvmvyHU:beeper.com", ReactionKey: "x", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", reaction.ChatID) } ```