# Messages

## Search

`$client->messages->search(?list<string> accountIDs, ?list<string> chatIDs, ?ChatType chatType, ?string cursor, ?\Datetime dateAfter, ?\Datetime dateBefore, ?Direction direction, ?bool excludeLowPriority, ?bool includeMuted, ?int limit, ?list<MediaType> mediaTypes, ?string query, ?string sender): CursorSearch<Message>`

**get** `/v1/messages/search`

Search messages across chats using Beeper's message index

### Parameters

- `accountIDs?:optional list<string>`

  Limit search to specific account IDs.

- `chatIDs?:optional list<string>`

  Limit search to specific chat IDs.

- `chatType?:optional ChatType`

  Filter by chat type: 'group' for group chats, 'single' for 1:1 chats.

- `cursor?:optional string`

  Opaque pagination cursor; do not inspect. Use together with 'direction'.

- `dateAfter?:optional \Datetime`

  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?:optional \Datetime`

  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?:optional Direction`

  Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided.

- `excludeLowPriority?:optional bool`

  Exclude messages marked Low Priority by the user. Default: true. Set to false to include all.

- `includeMuted?:optional 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?:optional int`

  Maximum number of messages to return.

- `mediaTypes?:optional list<MediaType>`

  Filter messages by media types. Use ['any'] for any media type, or specify exact types like ['video', 'image']. Omit for no media filtering.

- `query?:optional 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?:optional 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

- `Message`

  - `string id`

    Message ID.

  - `string accountID`

    Beeper account ID the message belongs to.

  - `string chatID`

    Unique identifier of the chat.

  - `string senderID`

    Sender user ID.

  - `string sortKey`

    A unique, sortable key used to sort messages.

  - `\Datetime timestamp`

    Message timestamp.

  - `?list<Attachment> attachments`

    Attachments included with this message, if any.

  - `?bool isSender`

    True if the authenticated user sent the message.

  - `?bool isUnread`

    True if the message is unread for the authenticated user. May be omitted.

  - `?string linkedMessageID`

    ID of the message this is a reply to, if any.

  - `?list<Reaction> reactions`

    Reactions to the message, if any.

  - `?string senderName`

    Resolved sender display name (impersonator/full name/username/participant name).

  - `?string text`

    Plain-text body if present. May include a JSON fallback with text entities for rich messages.

  - `?Type type`

    Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

### Example

```php
<?php

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

$client = new Client();

$page = $client->messages->search(
  accountIDs: [
    'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc',
    'local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU',
  ],
  chatIDs: ['!NCdzlIaMjZUmvmvyHU:beeper.com', '1231073'],
  chatType: 'group',
  cursor: '1725489123456|c29tZUltc2dQYWdl',
  dateAfter: new \DateTimeImmutable('2025-08-01T00:00:00Z'),
  dateBefore: new \DateTimeImmutable('2025-08-31T23:59:59Z'),
  direction: 'before',
  excludeLowPriority: true,
  includeMuted: true,
  limit: 20,
  mediaTypes: ['any'],
  query: 'dinner',
  sender: 'sender',
);

var_dump($page);
```

## List

`$client->messages->list(string chatID, ?string cursor, ?Direction direction): CursorSortKey<Message>`

**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.

- `cursor?:optional string`

  Opaque pagination cursor; do not inspect. Use together with 'direction'.

- `direction?:optional Direction`

  Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided.

### Returns

- `Message`

  - `string id`

    Message ID.

  - `string accountID`

    Beeper account ID the message belongs to.

  - `string chatID`

    Unique identifier of the chat.

  - `string senderID`

    Sender user ID.

  - `string sortKey`

    A unique, sortable key used to sort messages.

  - `\Datetime timestamp`

    Message timestamp.

  - `?list<Attachment> attachments`

    Attachments included with this message, if any.

  - `?bool isSender`

    True if the authenticated user sent the message.

  - `?bool isUnread`

    True if the message is unread for the authenticated user. May be omitted.

  - `?string linkedMessageID`

    ID of the message this is a reply to, if any.

  - `?list<Reaction> reactions`

    Reactions to the message, if any.

  - `?string senderName`

    Resolved sender display name (impersonator/full name/username/participant name).

  - `?string text`

    Plain-text body if present. May include a JSON fallback with text entities for rich messages.

  - `?Type type`

    Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

### Example

```php
<?php

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

$client = new Client();

$page = $client->messages->list(
  '!NCdzlIaMjZUmvmvyHU:beeper.com',
  cursor: '1725489123456|c29tZUltc2dQYWdl',
  direction: 'before',
);

var_dump($page);
```

## Send

`$client->messages->send(string chatID, ?Attachment attachment, ?string replyToMessageID, ?string text): MessageSendResponse`

**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.

- `attachment?:optional Attachment`

  Single attachment to send with the message

- `replyToMessageID?:optional string`

  Provide a message ID to send this as a reply to an existing message

- `text?:optional string`

  Text content of the message you want to send. You may use markdown.

### Returns

- `MessageSendResponse`

  - `string chatID`

    Unique identifier of the chat.

  - `string pendingMessageID`

    Pending message ID

### Example

```php
<?php

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

$client = new Client();

$response = $client->messages->send(
  '!NCdzlIaMjZUmvmvyHU:beeper.com',
  attachment: [
    'uploadID' => 'uploadID',
    'duration' => 0,
    'fileName' => 'fileName',
    'mimeType' => 'mimeType',
    'size' => ['height' => 0, 'width' => 0],
    'type' => 'gif',
  ],
  replyToMessageID: 'replyToMessageID',
  text: 'text',
);

var_dump($response);
```

## Update

`$client->messages->update(string messageID, string chatID, string text): MessageUpdateResponse`

**put** `/v1/chats/{chatID}/messages/{messageID}`

Edit the text content of an existing message. Messages with attachments cannot be edited.

### Parameters

- `chatID: string`

  Unique identifier of the chat.

- `messageID: string`

- `text: string`

  New text content for the message

### Returns

- `MessageUpdateResponse`

  - `string chatID`

    Unique identifier of the chat.

  - `string messageID`

    Message ID.

  - `bool success`

    Whether the message was successfully edited

### Example

```php
<?php

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

$client = new Client();

$message = $client->messages->update(
  'messageID', chatID: '!NCdzlIaMjZUmvmvyHU:beeper.com', text: 'x'
);

var_dump($message);
```