# Better Messages - REST API Reference

> REST API endpoints for the Better Messages WordPress plugin.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Add participant

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add participant"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/addParticipant"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Adds one or more users to a conversation. The current user must have invite permission for the thread (controlled by the `can_invite()` function and `allow_invite` thread setting). Users who are already participants are skipped. Returns an error if no valid additions can be made.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./add-participant.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./add-participant.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./add-participant.StatusCodes.json")}
>
  
</StatusCodes>

---

## Ban user from thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Ban user from thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/banUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Bans a user from a thread — removes them as a participant and prevents them from rejoining. Requires moderator permission. The ban automatically expires after the given number of minutes. The user is immediately removed from the thread upon banning.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ban-user-from-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ban-user-from-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ban-user-from-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Better Messages REST API

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Better Messages REST API"}
>
</Heading>

The Better Messages REST API exposes every messenger operation — creating conversations, sending messages, managing participants, moderation, friend lists, settings, voice messages, file attachments, and more — over a standard WordPress REST API namespace. It powers both the official Better Messages JavaScript client and the iOS / Android mobile apps, and you can use it directly to build integrations, bots, mobile clients, sync workers, or any external service that needs to read or write messenger data.

**Base URL:** `https://your-site.com/wp-json/better-messages/v1`

All routes are rooted at the `/wp-json/better-messages/v1` namespace and follow standard WordPress REST API conventions.

**Authentication:** Most endpoints require an authenticated WordPress user. Three authentication methods are supported:

- **Cookie authentication** — the default for browser-based requests. Send the standard WordPress nonce header (`X-WP-Nonce`).
- **Application passwords** — for server-to-server or external integrations. Use HTTP Basic auth with the username and an application password (WordPress 5.6+).
- **Custom authentication** — override the auth check via the `better_messages_rest_is_user_authorized` PHP filter. Useful for bridging JWT, OAuth, or custom tokens.

**Guest authentication** — for sites with Guest Chat enabled, unauthenticated visitors can interact with the messenger using two HTTP headers: `BM-Guest-ID` (positive guest database id) and `BM-Guest-Secret` (30-character token returned during guest registration). Guests are identified internally as **negative integer user IDs** so they don't collide with real WordPress users.

**Authorization** — endpoint access depends on user capabilities, thread participation, plugin settings, and any custom `better_messages_capabilities` filter logic. A request that is authenticated but not authorized for a specific thread or action returns `403 Forbidden`. Endpoints marked **Public** in their tag description do not require authentication at all.

**Response format** — all endpoints return JSON. Errors follow the WordPress REST API envelope (`{ code, message, data: { status } }`). Successful responses return the requested resource directly without wrapping.

**Rate limiting** — the API imposes no HTTP-level rate limits or quotas, so polling and read traffic are bounded only by your own server capacity. The optional per-role sending limits in the plugin settings (a cooldown between new conversations, and a cap on replies per hour or per day) apply when a message is sent. They are not signalled with `429` — a rejected send returns `200 OK` with `result: false` and an `errors` object naming the reason.

  
    Contact
  
    [support@better-messages.com](mailto:support@better-messages.com)
  
    URL: [https://www.better-messages.com](https://www.better-messages.com)

---

## Block user

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Block user"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/blockUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Blocks a user from sending messages to the current user. Blocked users cannot start new conversations or send messages in existing conversations with the blocker. Users cannot block themselves or administrators. Role-based restrictions and immunity rules are applied via the `restrictBlockUsers` and `restrictBlockUsersImmun` settings.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./block-user.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./block-user.StatusCodes.json")}
>
  
</StatusCodes>

---

## Calls

Private and group voice/video calling (WebSocket version only)

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Change thread metadata

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Change thread metadata"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/changeMeta"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates a metadata value on a thread. Only thread super-moderators can change metadata. The `allow_invite` key is handled specially — it updates the thread setting directly and triggers info change notifications. All other keys are processed via the `better_messages_change_thread_meta` action hook.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./change-thread-metadata.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./change-thread-metadata.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./change-thread-metadata.StatusCodes.json")}
>
  
</StatusCodes>

---

## Change thread subject

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Change thread subject"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/changeSubject"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates the subject/title of a conversation thread. Only thread super-moderators (admins, thread creators in group contexts) can change the subject. The subject is sanitized and filtered through the `better_messages_change_subject_content` hook before saving.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./change-thread-subject.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./change-thread-subject.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./change-thread-subject.StatusCodes.json")}
>
  
</StatusCodes>

---

## Chat Rooms

Join and leave public or semi-public chat rooms

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Check for new messages

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Check for new messages"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/checkNew"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Polls for new messages and thread updates since the client's last check. This is the primary polling endpoint used in AJAX mode (when WebSocket is not available). Returns delta updates including new messages, updated threads, deleted threads and messages. Also marks visible threads as read. When lastUpdate is 0, returns initial thread data instead of delta.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./check-for-new-messages.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./check-for-new-messages.StatusCodes.json")}
>
  
</StatusCodes>

---

## Clear all messages

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Clear all messages"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/clearMessages"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes all messages from a thread in batches of 50. Resets unread counts and read timestamps for all participants. Requires the `bm_can_administrate` capability or moderator permission. This is a destructive operation — all message content and attachments are permanently removed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./clear-all-messages.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./clear-all-messages.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./clear-all-messages.StatusCodes.json")}
>
  
</StatusCodes>

---

## Conversation Settings

Subject, metadata, mute, and pin settings for conversations

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Conversations

Create, retrieve, delete, and restore conversation threads

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Create call room

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create call room"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/callCreate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a call message in a conversation and generates a room token. Used for multi-participant conversations. The call message is stored with `bpbm_call` metadata. Returns tokens and participant data needed to establish the call. Requires WebSocket version.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-call-room.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-call-room.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete messages

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete messages"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/deleteMessages"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes specific messages from a thread. Only the message sender can delete their own messages. Thread moderators can delete messages from non-moderators, and super-moderators can delete any message except those from other super-moderators. The delete method (hard delete vs. content replacement) is controlled by the plugin's `deleteMessageMethod` setting. When using the replacement method, the response includes updated message objects.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-messages.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-messages.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-messages.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete push subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete push subscription"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pushNotifications/delete"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes a web push notification subscription for the current user. Typically called when the user disables push notifications or the browser subscription is invalidated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-push-subscription.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-push-subscription.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/delete"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Archives a thread for the current user by soft-deleting it. The thread is hidden from the user's conversation list but not permanently removed from the database. Other participants can still see the conversation. Deletion can be restricted via the `restrictThreadsDeleting` plugin setting — when enabled, only administrators can delete threads. The `bp_better_messages_can_delete_thread` filter allows custom permission logic.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Edit message

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Edit message"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/save"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Edits an existing message with new content. Only the original sender can edit their messages, and the `allowEditMessages` setting must be enabled. Forwarded messages cannot be edited. The edit preserves any file attachments from the original message. A history of previous versions is saved internally for audit purposes. The response includes the updated message object.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./edit-message.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./edit-message.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./edit-message.StatusCodes.json")}
>
  
</StatusCodes>

---

## Email unsubscribe

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Email unsubscribe"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/unsubscribe"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Unsubscribes a user from email notifications using a verification token. The token is generated per-user and included in email notification footers. **Public endpoint** — does not require authentication.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./email-unsubscribe.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./email-unsubscribe.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./email-unsubscribe.StatusCodes.json")}
>
  
</StatusCodes>

---

## Erase thread permanently

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Erase thread permanently"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/erase"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Permanently and irreversibly deletes a thread along with all messages, metadata, and participant records. Requires the `bm_can_administrate` capability. Unlike clearing messages, this removes the thread entry itself from the database. Use with extreme caution.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./erase-thread-permanently.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./erase-thread-permanently.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./erase-thread-permanently.StatusCodes.json")}
>
  
</StatusCodes>

---

## Forward message

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Forward message"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/message/{message_id}/forward"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Forwards a message to one or more destination threads. The forwarding feature must be enabled in plugin settings (`enableForwardMessages`). Attachments and voice messages are copied to each destination. Forward attribution tracks the original sender when enabled. The user must have reply access in each destination thread. Limited to a maximum of 20 destination threads per forward operation. Deleted messages and messages the user doesn't have access to cannot be forwarded.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./forward-message.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./forward-message.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./forward-message.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get bad words list

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get bad words list"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/getBlockList"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the configured bad words block list for client-side content filtering. The bad words feature must be enabled in plugin settings. Used by the frontend to prevent sending messages containing blocked words before they reach the server.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-bad-words-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-bad-words-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get conversation suggestions

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get conversation suggestions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/suggestions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns user suggestions for the new conversation screen with optional search filtering. When a threadId is provided, excludes users already participating in that thread. Respects the `disableUsersSearch` setting. Returns up to 50 user profiles (configurable via filter). AI bots are hidden from suggestions in E2E encrypted thread contexts.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-conversation-suggestions.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-conversation-suggestions.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-conversation-suggestions.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get emoji data

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get emoji data"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/getEmojiData"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the emoji dataset for the emoji picker UI, including all categories and individual emoji data. The dataset can be customized via the `better_messages_get_emoji_dataset` filter. **Public endpoint** — does not require authentication.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-emoji-data.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-emoji-data.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get favorited messages

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get favorited messages"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/getFavorited"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all messages starred by the current user across all conversations. Only returns messages the user still has access to. The `disableFavoriteMessages` setting must not be enabled.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-favorited-messages.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-favorited-messages.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get friends list

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get friends list"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/getFriends"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the current user's friends list. This endpoint is entirely filter-driven — the default returns an empty array. BuddyPress, BuddyBoss, and other social plugins hook into the `better_messages_get_friends` filter to provide actual friend data.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-friends-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-friends-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get groups

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get groups"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/getGroups"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns groups the current user belongs to. Like getFriends, this endpoint is filter-driven — the default returns an empty array. BuddyPress, PeepSo, and other group plugins hook into the `better_messages_get_groups` filter to provide group data.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-groups.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-groups.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get @mention suggestions

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get @mention suggestions"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/mentionsSuggestions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns thread participants matching a search query for the @mention autocomplete feature. Searches display_name and user_nicename fields. Excludes the current user and deleted recipients. Returns up to 50 unique user IDs.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-mention-suggestions.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-mention-suggestions.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-mention-suggestions.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get or create private thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get or create private thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/getPrivateThread"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets an existing private 1-on-1 conversation with a specific user, or creates one if it doesn't exist. Supports unique conversation keys for context-specific conversations (e.g., per-product discussions). When a unique key is provided, the endpoint uses `get_unique_pm_thread_id()` instead of the standard PM lookup. Returns full thread data including messages and participants when a thread is found or created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-or-create-private-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-or-create-private-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get report reasons

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get report reasons"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/reports/getReasons"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns available report reason categories for a specific message. Also checks whether the current user has already reported this message — returns an error if they have. The default categories are inappropriate, spam, harassment, offensive, and other, but they can be customized via the `better_messages_get_report_reasons` filter.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-report-reasons.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-report-reasons.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-report-reasons.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get sticker pack

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get sticker pack"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/stickers/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all stickers from a specific sticker pack for display in the sticker picker.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-sticker-pack.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-sticker-pack.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-sticker-pack.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get sticker packs

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get sticker packs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/stickers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the list of available sticker packs configured in the plugin. Each pack includes a preview image and sticker count.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-sticker-packs.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-sticker-packs.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get thread attachments

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get thread attachments"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/thread/{id}/attachments"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all file attachments shared in a conversation thread. Includes images, documents, videos, and other files sent as message attachments.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-thread-attachments.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-thread-attachments.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-thread-attachments.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get thread details

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get thread details"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a specific thread with its newest 80 messages and participant data. Older messages come from `/thread/{id}/loadMore`. Automatically marks the thread as read for the current user. For chat room threads, auto-add users are synced on access. The endpoint also detects messages that have been deleted since the client's last load by comparing the provided loaded message IDs against the database.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-thread-details.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-thread-details.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-thread-details.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get threads for forwarding

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get threads for forwarding"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/threadsPicker"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a list of threads suitable for the message forwarding picker UI. Supports search filtering by thread subject or participant names. Excludes threads with `exclude_from_threads_list` metadata and creator-only threads. Returns up to 20 threads with participant data, images, and pin status. The forwarding feature must be enabled in plugin settings.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-threads-for-forwarding.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-threads-for-forwarding.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get threads list (POST)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get threads list (POST)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/threads"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Same as GET /threads but accepts POST body for parameters. Useful when the exclude list is large and would exceed URL length limits.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-threads-list-post.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-threads-list-post.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get threads list

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get threads list"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/threads"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the current user's conversation list with recent messages and participant data. Threads are ordered by last activity. Deleted threads and threads without messages (except chat rooms and groups) are automatically excluded. Administrators can see pending messages from all users, while regular users only see their own pending messages.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-threads-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-threads-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-threads-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get unique conversation

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get unique conversation"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/getUniqueConversation"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets or creates a conversation identified by a unique key string. The actual thread resolution is handled by addon filters — the core plugin fires `better_messages_get_unique_conversation` filter and returns the resolved thread. This is commonly used for E2E encryption rooms and context-specific conversations. **Public endpoint** — does not require authentication.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-unique-conversation.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-unique-conversation.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get user settings

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get user settings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/userSettings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the current user's configurable messaging preferences. Available settings are dynamic and depend on plugin configuration — they may include email notifications, sound notifications, who can start conversations, and online status visibility. Each setting includes its current value, available options, and display labels.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-user-settings.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-user-settings.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get user suggestions

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get user suggestions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/userSuggestions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns suggested users for starting new conversations. Prioritizes friends (up to 12), then falls back to other users. Respects friends-only and followers-only messaging modes. Can be overridden via the `better_messages_predefined_suggestions_user_ids` filter. Administrators bypass friends-only restrictions.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-user-suggestions.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-user-suggestions.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get users list

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get users list"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/getUsers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a page of the members the Users widget lists, excluding the current user, following the widget's settings: display mode (all members, by role or hand-picked), sort order and search. The route also answers GET with the same parameters.

It answers only a viewer the Users widget is shown to: one of the mini widget bar, side panel or mobile tab bar has the Users tab on and its role restriction does not hide it from the viewer. A visitor who is not logged in, or a guest, also needs guest chat on. Anyone else gets 401 (not logged in) or 403.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-users-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-users-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-users-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Guests

Guest (non-registered) user registration and profile management

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Health check

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Health check"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ping"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Simple health check endpoint that returns "pong" to verify the REST API is responding. **Public endpoint** — does not require authentication.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./health-check.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./health-check.StatusCodes.json")}
>
  
</StatusCodes>

---

## Join call

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Join call"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/joinCall"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Joins an existing active call session. The message must have `bpbm_call` metadata indicating an active call. Returns a room token and encryption key for the user to connect. The user must be a participant of the conversation. Requires WebSocket version.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./join-call.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./join-call.StatusCodes.json")}
>
  
</StatusCodes>

---

## Join chat room

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Join chat room"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/chat/{id}/join"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Adds the current user as a participant in a chat room. Access is validated against the room's role-based permissions via the `user_can_join()` method and `better_messages_chat_user_can_join` filter. After joining, returns the updated thread data for the chat room.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./join-chat-room.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./join-chat-room.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./join-chat-room.StatusCodes.json")}
>
  
</StatusCodes>

---

## Lazy load data

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Lazy load data"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/lazyPool"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Lazy-loads user profiles and message data by IDs for efficient on-demand data fetching. Used when the client encounters references to users or messages not yet in its local cache. Validates that the current user has access to the thread containing each requested message before returning it. Messages are returned with full formatting, favorite status, and metadata.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./lazy-load-data.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./lazy-load-data.StatusCodes.json")}
>
  
</StatusCodes>

---

## Leave chat room

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Leave chat room"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/chat/{id}/leave"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes the current user from a chat room. Users cannot leave chat rooms that have auto_join enabled — in that case, the endpoint returns an error. After leaving, the user no longer receives messages or notifications for the room.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./leave-chat-room.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./leave-chat-room.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./leave-chat-room.StatusCodes.json")}
>
  
</StatusCodes>

---

## Leave thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Leave thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/leaveThread"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes the current user from a group conversation. The user will no longer receive messages or notifications for this thread. A single moderator cannot leave a thread — another moderator must be assigned first. The `can_leave()` function validates whether the user is allowed to leave.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./leave-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./leave-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./leave-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Lift call ban

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Lift call ban"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/callUnbanUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Lifts a ban from the conversation's group calls (Better Messages 3.2), the ban a moderator gives with **Remove and Ban from Calls** in a group call (`/groupCallAdmin` with `act` `ban_participant`). The user may join the calls of the conversation again at once. A ban from the conversation itself is lifted separately with `/thread/{id}/unbanUser`. Requires moderator permission in the conversation. Fires the `better_messages_user_unrestricted` action with the type `call_ban` when a ban was lifted.

For its moderators, a conversation object lists the users banned from calls in `restricted.call_ban`, beside `ban` and `mute`, each user ID with the end of the restriction as a Unix time. Since 3.2 the `restricted` lists come with group conversations, integration groups and courses as well as chat rooms.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./lift-call-ban.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./lift-call-ban.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./lift-call-ban.StatusCodes.json")}
>
  
</StatusCodes>

---

## Load more messages

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Load more messages"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/loadMore"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Loads additional messages for a thread, supporting both backward pagination (loading older messages) and forward range loading (loading messages up to a specific point). Also detects and returns any missed messages not in the client's loaded set. Returns up to 80 messages per request. The `mode` parameter controls the loading direction.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./load-more-messages.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./load-more-messages.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./load-more-messages.StatusCodes.json")}
>
  
</StatusCodes>

---

## Make moderator

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Make moderator"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/makeModerator"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Promotes a thread participant to moderator status. For chat rooms, only WordPress administrators can promote moderators. For regular threads, the current user must be a super-moderator. The target user must already be a participant of the thread.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./make-moderator.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./make-moderator.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./make-moderator.StatusCodes.json")}
>
  
</StatusCodes>

---

## Mark all as read

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Mark all as read"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/markAllRead"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Marks all conversations as read for the current user. Updates unread_count to 0 and sets last_read and last_delivered timestamps for every thread the user participates in. Fires the `better_messages_mark_all_read` action hook.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./mark-all-as-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./mark-all-as-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Mark conversation as unread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Mark conversation as unread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/markUnread"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Marks a conversation the current user has read as unread again (Better Messages 3.2). The `unread_count` of the user for it becomes `-1`: the conversation shows a dot in the conversations list and is listed by the unread filter, while no unread total counts it (`get_user_unread_count()`, the conversations count, the totals of the realtime server and the mobile app badge). The mark ends when the user opens the conversation (`messages_mark_thread_read()`, `/openThreads`, `/markAllRead`) or when a new message arrives, which counts from 0. A deleted message keeps it. Nobody is notified.

The route takes the word of the caller that the conversation was read: it writes `-1` whatever count the site holds, since in the WebSocket version the count the site keeps for a conversation read through the realtime connection catches up only at the next sync. The messenger offers the action only on a conversation it shows read. On the WebSocket version the mark reaches the other devices of the user through the realtime server.

Conversation objects carry `unread: -1` for a marked conversation (REST, the `better_messages_rest_thread_item` filter and realtime events). Fires `better_messages_thread_marked_unread` with the thread ID and the user ID.

Refused with 403 when **Settings → Messaging → Conversation Features → Mark as Unread** is off, in a presence-based chat room, and for a user who is not a participant.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./mark-conversation-as-unread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./mark-conversation-as-unread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./mark-conversation-as-unread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Mark threads as read

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Mark threads as read"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/openThreads"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Marks specific threads as read for the current user. Calls `messages_mark_thread_read()` for each provided thread ID, which resets unread counts and updates read timestamps.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./mark-threads-as-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./mark-threads-as-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Media

File attachments, sticker packs, and GIPHY integration

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Message Actions

Emoji reactions, starred/favorite messages, and pinned messages

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Messages

Send, edit, delete, and forward messages within conversations

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Moderate group call

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Moderate group call"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/groupCallAdmin"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Runs a moderator action in a group call, chosen with `act`. Moderators of the conversation may use every action, everyone else only `raise_hand` and `lower_own_hand`. Participants are named by their call identity, `user_` and the user ID (`user_-5` for a guest). Requires WebSocket version.

The actions:

- `lock_room`, `unlock_room`: keep everyone but moderators from joining, or let them join again
- `set_broadcast_mode`, `set_participatory_mode`: switch the call between broadcast and participatory mode
- `mute_all`, `unmute_all`: mute or unmute everyone's microphone, or with `identities` only the people listed
- `end_call` (3.2): end the call for everyone, taking out the people in `identities`
- `remove_participant`: take `identity` out of the call. They can join again.
- `ban_participant` (3.2): Remove and Ban from Calls. Takes `identity` out of the call and keeps them from the conversation's calls for `duration` minutes, and with `chat` also bans them from the conversation where that is offered (`canBanFromChat` of `/groupCallStart`: group conversations and chat rooms). Answers with the updated thread data. Lift the ban with `/thread/{id}/callUnbanUser`.
- `mute_participant`, `unmute_participant`: stop `identity` from sending audio and video, or let them again
- `mute_mic`, `unmute_mic`: mute or unmute the microphone of `identity`
- `promote_participant`, `demote_participant`: in broadcast mode, let `identity` speak and show video, or make them a viewer again
- `pin_participant`, `unpin_participant`: pin `identity` in the call, or unpin them
- `spotlight_participant`, `unspotlight_participant` (3.2): put `identity` in the spotlight for everyone, up to four people, or take them out of it
- `ask_camera`, `ask_microphone`, `ask_camera_microphone` (3.2): ask `identity` to turn on their camera, their microphone, or both in one ask. Once in 30 seconds for each moderator, person and device, and never yourself. Answers `{ "asked": true }`.
- `raise_hand`, `lower_own_hand`: raise or lower your own hand
- `lower_hand`: lower the hand of `identity`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./moderate-group-call.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./moderate-group-call.StatusCodes.json")}
>
  
</StatusCodes>

---

## Moderation

Block users, mute/ban users in threads, and report messages

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Mute thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Mute thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/mute"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Mutes notifications for a thread. The current user will no longer receive push notifications, browser notifications, or email notifications for new messages in this thread. The mute state is stored per-user in the recipients table. Fires thread update actions so other tabs/devices reflect the change.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./mute-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./mute-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./mute-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Mute user in thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Mute user in thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/muteUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Mutes a user within a specific thread, preventing them from sending messages for a duration. Requires moderator permission in the thread. The target user must be a current participant. The mute automatically expires after the given number of minutes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./mute-user-in-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./mute-user-in-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./mute-user-in-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Participants

Add, remove, promote, and search thread members

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Pin conversation

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Pin conversation"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/makePinned"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Pins a conversation to the top of the current user's thread list. Pinned conversations always appear above unpinned ones regardless of last activity time. The pin state is stored per-user in the recipients table.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./pin-conversation.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./pin-conversation.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./pin-conversation.StatusCodes.json")}
>
  
</StatusCodes>

---

## Pin message

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Pin message"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/pinMessage"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Pins a message to a thread. Only one message can be pinned per thread at a time — pinning a new message automatically unpins the previous one. Requires the `can_pin_messages` permission (controlled by the `better_messages_can_pin_messages` filter). The message must exist and belong to the specified thread.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./pin-message.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./pin-message.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./pin-message.StatusCodes.json")}
>
  
</StatusCodes>

---

## Register guest

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Register guest"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/guests/register"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Registers a new anonymous guest user for chat. Guest access must be enabled in plugin settings. The user must not be logged in. A display name is auto-generated using an alliterative name generator if not provided. The generated name must be unique. Returns the guest's credentials (ID and secret token) along with WebSocket profile data for real-time connectivity. **Public endpoint** — does not require authentication.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./register-guest.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./register-guest.StatusCodes.json")}
>
  
</StatusCodes>

---

## Remove moderator

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove moderator"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/unmakeModerator"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes moderator status from a thread participant. For chat rooms, only WordPress administrators can demote moderators. For regular threads, the current user must be a super-moderator. The target user remains a regular participant after demotion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./remove-moderator.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./remove-moderator.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./remove-moderator.StatusCodes.json")}
>
  
</StatusCodes>

---

## Remove participant

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove participant"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/removeParticipant"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes a user from a conversation. The current user must be a super-moderator or thread moderator. Moderators cannot remove super-moderators unless the requester is also a super-moderator. The removed user loses access to the conversation and stops receiving notifications.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./remove-participant.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./remove-participant.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./remove-participant.StatusCodes.json")}
>
  
</StatusCodes>

---

## Report message

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Report message"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/reports/reportMessage"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Reports a message for moderator review. Each user can only report a specific message once. Users cannot report their own messages. The report category must be one of the allowed categories (default: inappropriate, spam, harassment, offensive, other — customizable via the `better_messages_get_report_reasons` filter). The description is limited to 500 characters by default (customizable via filter).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./report-message.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./report-message.StatusCodes.json")}
>
  
</StatusCodes>

---

## Restore thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Restore thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/restore"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Restores a previously archived/deleted thread back to the user's conversation list. Sets the is_deleted flag to 0 and updates the last_update timestamp. Subject to the same permission restrictions as thread deletion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./restore-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./restore-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./restore-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Save push subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Save push subscription"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pushNotifications/save"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Saves a web push notification subscription for the current user. The subscription data should contain the browser push API endpoint and encryption keys. Subscriptions are stored in user meta and used for sending push notifications when new messages arrive.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./save-push-subscription.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./save-push-subscription.StatusCodes.json")}
>
  
</StatusCodes>

---

## Save user settings

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Save user settings"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/userSettings/save"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates a single user preference. Supported options include `email_notifications`, `who_can_start_conversations`, `sound_notifications`, and `online_status`. Values are typically 'yes' or 'no'. The online_status option additionally triggers a WebSocket profile update and returns the full updated user item when WebSocket is enabled.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./save-user-settings.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./save-user-settings.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search GIFs

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search GIFs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/gifs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Searches for animated GIFs via the GIPHY integration. The GIPHY feature must be enabled and a valid API key must be configured in plugin settings.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./search-gi-fs.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search-gi-fs.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search-gi-fs.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search participants

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search participants"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/searchParticipants"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Searches for participants within a specific thread by display name or username. Returns matching user IDs excluding the current user and deleted recipients.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./search-participants.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search-participants.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search-participants.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Comprehensive search across users, friends, and message content. User search can be disabled via the `disableUsersSearch` plugin setting. Results are separated into friend matches and non-friend matches. Message search returns thread IDs with match counts (limited to 10 results). The response includes full thread and user data for rendering search results.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Send message

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Send message"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/send"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Sends a message to a conversation thread. The current user must have reply access. Supports file attachments, message metadata, and offline message sync via temporary IDs. If moderation is enabled, the message enters a pending queue instead of being delivered immediately. The temp_id and temp_time parameters enable offline-first messaging — the server validates that temp_time is within ±600 seconds of server time. After sending, the thread is automatically marked as read for the sender.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./send-message.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./send-message.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./send-message.StatusCodes.json")}
>
  
</StatusCodes>

---

## Settings & Notifications

User messaging preferences and push notification subscriptions

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Start group call

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Start group call"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/groupCallStart"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Starts or joins a group voice/video call in a thread. The response includes a room token and the current call mode (participatory or broadcast). In broadcast mode, non-moderators receive a receive-only token. Moderators can lock the room, mute participants, and switch between participatory and broadcast modes via the group call admin endpoint (`/groupCallAdmin`). Requires WebSocket version.

Since 3.2 a person banned from the conversation's calls, or from a chat room, is refused with a 403 that says until when, and the answer also carries `canPublish`, `micMuted`, the call's `recording` and, for moderators, `canBanFromChat`. A call that cannot take more people is refused with `group_call_full`. The `better_messages_group_call_join_custom_error` filter can refuse with a message of its own.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./start-group-call.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./start-group-call.StatusCodes.json")}
>
  
</StatusCodes>

---

## Start new conversation

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Start new conversation"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/new"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a new conversation thread and sends the first message. Recipients are validated against plugin restrictions (friends-only mode, blocking, etc.). If message moderation is enabled, the message will be placed in a pending queue for admin approval. Supports file attachments and E2E encryption addon integration. Returns an error with detailed messages if the conversation cannot be created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./start-new-conversation.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./start-new-conversation.StatusCodes.json")}
>
  
</StatusCodes>

---

## Start private call

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Start private call"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/callStart"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Initiates a private 1-on-1 voice or video call. Can auto-create a conversation thread if thread_id is 0 or not provided. Only works for conversations with exactly 2 participants. The user must have reply permission in the conversation. Returns a room token and encryption key for establishing the call connection. Fires the `better_messages_call_created` action hook. Requires WebSocket version.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./start-private-call.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./start-private-call.StatusCodes.json")}
>
  
</StatusCodes>

---

## Suggest thread for recipients

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Suggest thread for recipients"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/suggest"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Checks if a conversation can be started with the given recipients. When a single recipient is specified without the forceNew flag, it looks for an existing PM thread and returns its ID. Otherwise, it validates whether the current user has permission to start a new conversation with the specified recipients.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./suggest-thread-for-recipients.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./suggest-thread-for-recipients.StatusCodes.json")}
>
  
</StatusCodes>

---

## Toggle favorite

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Toggle favorite"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/favorite"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Stars or unstars a message for the current user. Starred messages can be retrieved later via the getFavorited endpoint. The `disableFavoriteMessages` setting must not be enabled. The operation is idempotent — starring an already-starred message still returns success.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./toggle-favorite.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./toggle-favorite.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./toggle-favorite.StatusCodes.json")}
>
  
</StatusCodes>

---

## Toggle reaction

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Toggle reaction"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/reactions/save"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Adds or removes an emoji reaction on a message. If the user has already reacted with the same emoji, it is removed (toggle behavior). Users cannot react to their own messages. The emoji must be in the configured reactions list. Returns the updated message with all current reactions.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./toggle-reaction.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./toggle-reaction.StatusCodes.json")}
>
  
</StatusCodes>

---

## Unban user from thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Unban user from thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/unbanUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes a ban restriction from a user, allowing them to rejoin the thread. Requires moderator permission. Note that unbanning does not automatically re-add the user as a participant — they must rejoin or be re-invited.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./unban-user-from-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./unban-user-from-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./unban-user-from-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Unblock user

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Unblock user"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/unblockUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes a block on a previously blocked user, allowing them to send messages again. The user must have been blocked first.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./unblock-user.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./unblock-user.StatusCodes.json")}
>
  
</StatusCodes>

---

## Unmute thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Unmute thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/unmute"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Restores notifications for a previously muted thread. The user will receive notifications for new messages again. Fires thread update actions for real-time sync.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./unmute-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./unmute-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./unmute-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Unmute user in thread

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Unmute user in thread"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/unmuteUser"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes a mute restriction from a user in a thread, allowing them to send messages again. Requires moderator permission.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./unmute-user-in-thread.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./unmute-user-in-thread.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./unmute-user-in-thread.StatusCodes.json")}
>
  
</StatusCodes>

---

## Unpin conversation

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Unpin conversation"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/unmakePinned"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes a conversation from the user's pinned list. The conversation returns to its normal position based on last activity time.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./unpin-conversation.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./unpin-conversation.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./unpin-conversation.StatusCodes.json")}
>
  
</StatusCodes>

---

## Unpin message

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Unpin message"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/thread/{id}/unpinMessage"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Removes the pinned message from a thread. Requires the `can_pin_messages` permission. After unpinning, no message will be pinned in the thread until a new one is explicitly pinned.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./unpin-message.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./unpin-message.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./unpin-message.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update guest profile

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update guest profile"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/guests/update"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates a guest user's display name. The current user must be authenticated as a guest (negative user ID). The new name must be unique among all guests. Returns updated credentials and WebSocket profile data.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-guest-profile.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-guest-profile.StatusCodes.json")}
>
  
</StatusCodes>

---

## Users & Search

User suggestions, friends, groups, and search across users and messages

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Utility

Health checks, emoji data, lazy loading, and miscellaneous endpoints

```mdx-code-block

<DocCardList items={useCurrentSidebarCategory().items}/>
```