# Messages ## Search `client.Messages.Search(ctx, query) (*CursorSearch[Message], error)` **get** `/v1/messages/search` Search messages across chats using Beeper's message index ### Parameters - `query MessageSearchParams` - `AccountIDs param.Field[[]string]` Limit search to specific account IDs. - `ChatIDs param.Field[[]string]` Limit search to specific chat IDs. - `ChatType param.Field[MessageSearchParamsChatType]` Filter by chat type: 'group' for group chats, 'single' for 1:1 chats. - `const MessageSearchParamsChatTypeGroup MessageSearchParamsChatType = "group"` - `const MessageSearchParamsChatTypeSingle MessageSearchParamsChatType = "single"` - `Cursor param.Field[string]` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `DateAfter param.Field[Time]` Only include messages with timestamp strictly after this ISO 8601 datetime (e.g., '2024-07-01T00:00:00Z' or '2024-07-01T00:00:00+02:00'). - `DateBefore param.Field[Time]` Only include messages with timestamp strictly before this ISO 8601 datetime (e.g., '2024-07-31T23:59:59Z' or '2024-07-31T23:59:59+02:00'). - `Direction param.Field[MessageSearchParamsDirection]` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `const MessageSearchParamsDirectionAfter MessageSearchParamsDirection = "after"` - `const MessageSearchParamsDirectionBefore MessageSearchParamsDirection = "before"` - `ExcludeLowPriority param.Field[bool]` Exclude messages marked Low Priority by the user. Default: true. Set to false to include all. - `IncludeMuted param.Field[bool]` Include messages in 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. - `Limit param.Field[int64]` Maximum number of messages to return. - `MediaTypes param.Field[[]string]` Filter messages by media types. Use ['any'] for any media type, or specify exact types like ['video', 'image']. Omit for no media filtering. - `const MessageSearchParamsMediaTypeAny MessageSearchParamsMediaType = "any"` - `const MessageSearchParamsMediaTypeVideo MessageSearchParamsMediaType = "video"` - `const MessageSearchParamsMediaTypeImage MessageSearchParamsMediaType = "image"` - `const MessageSearchParamsMediaTypeLink MessageSearchParamsMediaType = "link"` - `const MessageSearchParamsMediaTypeFile MessageSearchParamsMediaType = "file"` - `Query param.Field[string]` Literal word search (non-semantic). Finds messages containing these EXACT words in any order. Use single words users actually type, not concepts or phrases. Example: use "dinner" not "dinner plans", use "sick" not "health issues". If omitted, returns results filtered only by other parameters. - `Sender param.Field[string]` Filter by sender: 'me' (messages sent by the authenticated user), 'others' (messages sent by others), or a specific user ID string (user.id). ### Returns - `type Message struct{…}` - `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.Messages.Search(context.TODO(), beeperdesktopapi.MessageSearchParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` ## List `client.Messages.List(ctx, chatID, query) (*CursorSortKey[Message], error)` **get** `/v1/chats/{chatID}/messages` List all messages in a chat with cursor-based pagination. Sorted by timestamp. ### Parameters - `chatID string` Unique identifier of the chat. - `query MessageListParams` - `Cursor param.Field[string]` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `Direction param.Field[MessageListParamsDirection]` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `const MessageListParamsDirectionAfter MessageListParamsDirection = "after"` - `const MessageListParamsDirectionBefore MessageListParamsDirection = "before"` ### Returns - `type Message struct{…}` - `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.Messages.List( context.TODO(), "!NCdzlIaMjZUmvmvyHU:beeper.com", beeperdesktopapi.MessageListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` ## Send `client.Messages.Send(ctx, chatID, body) (*MessageSendResponse, error)` **post** `/v1/chats/{chatID}/messages` Send a text message to a specific chat. Supports replying to existing messages. Returns a pending message ID. ### Parameters - `chatID string` Unique identifier of the chat. - `body MessageSendParams` - `Attachment param.Field[MessageSendParamsAttachment]` Single attachment to send with the message - `UploadID string` Upload ID from uploadAsset endpoint. Required to reference uploaded files. - `Duration float64` Duration in seconds (optional override of cached value) - `FileName string` Filename (optional override of cached value) - `MimeType string` MIME type (optional override of cached value) - `Size MessageSendParamsAttachmentSize` Dimensions (optional override of cached value) - `Height float64` - `Width float64` - `Type string` Special attachment type (gif, voiceNote, sticker). If omitted, auto-detected from mimeType - `const MessageSendParamsAttachmentTypeGif MessageSendParamsAttachmentType = "gif"` - `const MessageSendParamsAttachmentTypeVoiceNote MessageSendParamsAttachmentType = "voiceNote"` - `const MessageSendParamsAttachmentTypeSticker MessageSendParamsAttachmentType = "sticker"` - `ReplyToMessageID param.Field[string]` Provide a message ID to send this as a reply to an existing message - `Text param.Field[string]` Text content of the message you want to send. You may use markdown. ### Returns - `type MessageSendResponse struct{…}` - `ChatID string` Unique identifier of the chat. - `PendingMessageID string` Pending message ID ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) response, err := client.Messages.Send( context.TODO(), "!NCdzlIaMjZUmvmvyHU:beeper.com", beeperdesktopapi.MessageSendParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.PendingMessageID) } ``` ## Update `client.Messages.Update(ctx, messageID, params) (*MessageUpdateResponse, error)` **put** `/v1/chats/{chatID}/messages/{messageID}` Edit the text content of an existing message. Messages with attachments cannot be edited. ### Parameters - `messageID string` - `params MessageUpdateParams` - `ChatID param.Field[string]` Path param: Unique identifier of the chat. - `Text param.Field[string]` Body param: New text content for the message ### Returns - `type MessageUpdateResponse struct{…}` - `ChatID string` Unique identifier of the chat. - `MessageID string` Message ID. - `Success bool` Whether the message was successfully edited ### Example ```go package main import ( "context" "fmt" "github.com/beeper/desktop-api-go" ) func main() { client := beeperdesktopapi.NewClient( ) message, err := client.Messages.Update( context.TODO(), "messageID", beeperdesktopapi.MessageUpdateParams{ ChatID: "!NCdzlIaMjZUmvmvyHU:beeper.com", Text: "x", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", message.ChatID) } ```