> ## Documentation Index > Fetch the complete documentation index at: https://cometchat-22654f5b-docs-restapi-chatapi-eng-39107.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Pin a CometChat message in a one-on-one or group conversation with REST API, as the app or on behalf of a user. # Pin Message For the complete error reference, see [Error Guide](/articles/error-guide). ## OpenAPI ````yaml post /messages/{id}/pin openapi: 3.0.0 info: title: Chat APIs description: Manage messages, users, groups for a particular app using our Chat API. version: '3.0' servers: - url: https://{appId}.api-{region}.cometchat.io/v3 variables: appId: default: appId description: (Required) App ID region: enum: - us - eu - in default: us description: Select Region security: [] tags: - name: API Keys description: The API keys are used to authorise the APIs - name: Roles description: The roles are used to give user access rights - name: Users description: The REST collection for users. - name: Auth Tokens description: The auth tokens are used to login end users using client SDKs. - name: Blocked Users description: The REST collections for blocked users. - name: Friends description: List,add and remove friends by passing UID in path variables - name: Groups description: The REST collections for groups. - name: Banned Users description: Ban and Unban user by passing other UID in path variables. - name: Group Members description: The REST collections for group members. - name: Messages description: The REST collections for messages. - name: Conversations description: The REST collections for conversations. - name: Restrict Features description: Allows Restricting Features - name: Metrics description: Allows accessing Data Metrics - name: Triggers description: Allows adding triggers to a webhook. - name: Webhooks description: Allows accessing Webhooks. - name: Notifications description: Allows configuring Notifications core. - name: Moderation description: The REST collections for Moderations. paths: /messages/{id}/pin: post: tags: - Messages summary: Pin Message description: >- Pins a message in its conversation. Without the onBehalfOf header the message is pinned as the app itself (app_system); with it, the message is pinned as that user and their scope permissions apply. The number of pinned messages per conversation is capped, and the cap is configured per app. Pins made on behalf of a user and pins made as the app count against separate budgets, so an app pin never consumes a user's allowance. Exceeding either returns ERR_PINNED_MESSAGES_LIMIT_EXCEEDED. operationId: pin-message parameters: - name: onBehalfOf in: header description: >- UID of the user to pin the message as. Leave it out to pin the message as the app itself. required: false schema: type: string - name: id in: path description: Id of the message to pin. required: true schema: type: string examples: string: summary: Message ID value: '' responses: '200': description: Pinning a message content: application/json: schema: properties: data: $ref: '#/components/schemas/messageSchema' type: object example: data: id: '2' conversationId: cometchat-uid-1_user_cometchat-uid-2 sender: cometchat-uid-1 receiverType: user receiver: cometchat-uid-2 category: message type: text data: text: Hi, sentAt: 1700210266 updatedAt: 1700210266 pinnedBy: app_system pinnedAt: 1700210300 '400': description: The conversation has reached its pinned message limit content: application/json: schema: type: object example: error: code: ERR_PINNED_MESSAGES_LIMIT_EXCEEDED message: >- The number of pinned messages for the conversation with id cometchat-uid-1_user_cometchat-uid-2 has reached the allowed limit of 100. '403': description: >- Pinned messages are switched off for this app, or the user may not pin content: application/json: schema: type: object example: error: code: ERR_PERMISSION_DENIED message: >- Permission denied for action pinMessage with role default as per RBAC policy. security: - apiKey: [] components: schemas: messageSchema: description: Response data properties: id: type: string conversationId: type: string sender: type: string receiverType: type: string receiver: type: string category: type: string type: type: string data: properties: text: type: string metadata: type: object entities: properties: sender: properties: entity: properties: uid: type: string name: type: string role: type: string avatar: type: string status: type: string createdAt: type: integer conversationId: type: string type: object entityType: type: string type: object receiver: properties: entity: properties: uid: type: string name: type: string role: type: string avatar: type: string status: type: string createdAt: type: integer conversationId: type: string type: object entityType: type: string type: object type: object type: object sentAt: type: integer updatedAt: type: integer pinnedBy: description: >- UID of the user who pinned the message, or app_system when the app pinned it. Left out of the response when the message is not pinned. type: string pinnedAt: description: >- When the message was pinned, in seconds. Left out of the response when the message is not pinned. type: integer savedAt: description: >- When the message was saved, in seconds. Only present for the user who saved it, and left out of the response when they have not saved it. type: integer type: object securitySchemes: apiKey: type: apiKey description: API Key with fullAccess scope(i.e. Rest API Key from the Dashboard). name: apikey in: header ````