> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periskope.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Pin Message

> This endpoint pins or unpins a message based on the `message_id` or `queue_id`




## OpenAPI

````yaml POST /message/{message_id}/pin
openapi: 3.0.3
info:
  title: API - Local
  description: >-
    #### Welcome to the official Postman collection of Periskope API


    Periskope APIs enable you automate actions on your WhatsApp phone, and the
    Periskope platform


    - Read more about the APIs & webhooks here -
    [https://docs.periskope.app/api-reference/introduction](https://docs.periskope.app/api-reference/introduction)
        
    - We encourage responsible usage of the APIs. Follow these best practices
    and recommendations for safe actions on WhatsApp -
    [https://docs.periskope.app/get-started/best-practices](https://docs.periskope.app/get-started/best-practices)
        

    #### Getting Started


    ##### Pre-requisites:


    1. **Sign up for a free account on Periskope:** To use the Periskope API,
    you need to have an active Periskope account. If you don’t have one, you can
    sign up for a 7-day free trial [here](https://console.periskope.app).
        
    2. **Scan the QR code from WhatsApp to connect your phone:** A connected
    phone is required to use the APIs
        
    3. **Go to** [Settings >
    API](https://console.periskope.app/settings/api), and generate an API key
    for your organization - The API key is used to authenticate every request.
    Please keep this secure
        

    ##### Using Postman:


    1. **Fork the collection so you can edit values and test the APIs in your
    own postman environment:** To fork the collection, click on the three dots
    next to v1. Then click on create a fork (_shortcut: Ctrl + Alt + F)._
        
    2. **Update the value of the variables in the collection:**  
        \- Update the API key with the key generated in Step 3  
        \- Update the phone number with your connected number. This number will be added to the `x-phone` header across requests
        
        It must be in the format of country code+number, with no special characters or spaces _e.g. +91 98745 32456 becomes 919874532456_
        

    For any help or feedback, please contact us at
    [support@periskope.app](https://mailto:support@periskope.app), or ping us on
    [WhatsApp](https://what.sapp.link/periskope)
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.periskope.app/v1
security:
  - bearerAuth: []
tags:
  - name: contacts
  - name: tickets
  - name: tasks
  - name: phones
  - name: message
  - name: queue
  - name: chats
  - name: group
  - name: members
  - name: webhooks
paths:
  /message/{message_id}/pin:
    parameters:
      - name: message_id
        in: path
        required: true
        schema:
          type: string
          example: true_919487126251@c.us_3EB0F754E67BDF3178E76C680224FF7114E2CB95
        description: The message_id or the queue_id of the message to pin or unpin
    post:
      tags:
        - message
      summary: Pin Message
      description: >
        This endpoint pins or unpins a message based on the `message_id` or
        `queue_id`
      operationId: pinMessage
      parameters:
        - name: x-phone
          in: header
          schema:
            type: string
            example: '{{orgPhone}}'
          description: >-
            Please provide the number of the phone you want to call with this
            API in the header. The number must be in country code + number
            format without any characters or spaces, e.g. 919876543210;
            Alternatively, provide the phone_id (phone-xxxxxxxxxxxx) in the
            header
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - pin
              properties:
                pin:
                  type: boolean
                  example: true
                  description: Whether to pin (true) or unpin (false) the message
                time:
                  type: integer
                  enum:
                    - 1
                    - 7
                    - 30
                  example: 7
                  description: |-
                    - Duration in days for how long the message stays pinned
                    - Accepted values: 1 (1 day), 7 (7 days), 30 (30 days)
                    - Defaults to 30 days if not provided
                    - Only applies when pin is true
            examples:
              Pin Message:
                value:
                  pin: true
              Unpin Message:
                value:
                  pin: false
      responses:
        '204':
          description: '204'
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: '*'
            Connection:
              schema:
                type: string
                example: keep-alive
            Date:
              schema:
                type: string
                example: Wed, 22 Jan 2025 10:36:19 GMT
            Keep-Alive:
              schema:
                type: string
                example: timeout=5
            X-Powered-By:
              schema:
                type: string
                example: Express
            X-RateLimit-Limit:
              schema:
                type: string
                example: '10'
            X-RateLimit-Remaining:
              schema:
                type: string
                example: '9'
            X-RateLimit-Reset:
              schema:
                type: string
                example: '1737542181'
            x-periskope-org-id:
              schema:
                type: string
                example: 2997dd64-89bf-48d3-9a22-b314fca017e5
            x-periskope-phone-id:
              schema:
                type: string
                example: phone-bqzvyibhmwkaergr
            x-periskope-trace-id:
              schema:
                type: string
                example: b77a8810-d8ac-11ef-8033-3b03afb6e098
          content:
            application/json:
              schema:
                type: object
                description: _204 No Content_
      x-codeSamples:
        - lang: TypeScript
          label: Node.js
          source: |-
            import { PeriskopeApi } from '@periskope/periskope-client';

            const client = new PeriskopeApi({
              authToken: 'YOUR_API_KEY',
              phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210'
            });

            async function pinMessage() {
              const response = await client.message.pin({
                message_id: 'true_919487126251@c.us_3EB0F754E67BDF3178E76C680224FF7114E2CB95',
                pin: true
              });

              console.log(response);
            }

            pinMessage();
        - lang: cURL
          label: cURL
          source: |-
            curl -X POST \
              https://api.periskope.app/v1/message/{message_id}/pin \
              -H 'Authorization: Bearer <token>' \
              -H 'Content-Type: application/json' \
              -H 'x-phone: YOUR_PHONE_NUMBER' \
              -d '{
                "pin": true
              }'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````