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

# Periskope Whatsapp MCP

> Connect your AI assistant to WhatsApp in seconds using Periskope's hosted MCP server

### What is MCP (Model Context Protocol)

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is a standardized interface that allows AI models like Claude and GPT to interact with external services and tools. It provides a structured way for AI assistants to execute actions, access data, and control applications through predefined functions and commands. In the context of Periskope WhatsApp, MCP enables AI assistants to directly **manage WhatsApp conversations, send messages, handle contacts, and perform other WhatsApp-related operations** programmatically.

## Setup

<Steps>
  <Step title="Connect WhatsApp">
    1. Sign up for an account at [console.periskope.app](https://console.periskope.app)
    2. You will need a phone number that you will use to manage all your WhatsApp chats, groups and communities logged in on WhatsApp.
    3. Open Settings on your WhatsApp App and click on **Link device**
    4. Now scan the QR code shown on Periskope screen

    <Info>
      If you face any errors, click on **refetch QR** to fetch a new QR code.
    </Info>
  </Step>

  <Step title="Add MCP to your AI client">
    Paste the following URL into your AI client's MCP server configuration:

    ```
    https://api.periskope.app/mcp
    ```

    <Tabs>
      <Tab title="Claude Desktop">
        1. Open Claude Desktop and go to **Customize**
        2. Navigate to **Connectors** → **Add custom connector**
        3. Paste `https://api.periskope.app/mcp` as the server URL
        4. Click **Add**

        <Frame caption="Claude Desktop MCP settings">
          <img className="block border rounded-xl shadow" src="https://mintcdn.com/bharatkumarramesh/jmkHMscwYb258Qi5/integrations/mcp/claude-desktop-mcp.png?fit=max&auto=format&n=jmkHMscwYb258Qi5&q=85&s=c4c17ffb9ea1d173f806d29c83680c1b" alt="Claude Desktop MCP setup" width="2364" height="1560" data-path="integrations/mcp/claude-desktop-mcp.png" />
        </Frame>
      </Tab>

      <Tab title="ChatGPT">
        1. Open ChatGPT and go to **Settings**
        2. Navigate to **Apps** → **Add Advanced Settings** → **Turn on Developer mode** → **Create app**
        3. Paste `https://api.periskope.app/mcp` as the server URL
        4. Click **Connect**

        <Frame caption="ChatGPT connector settings">
          <img className="block border rounded-xl shadow" src="https://mintcdn.com/bharatkumarramesh/jmkHMscwYb258Qi5/integrations/mcp/chatgpt-mcp.png?fit=max&auto=format&n=jmkHMscwYb258Qi5&q=85&s=e5c5e510393aff71d2c58080a2dd1b6d" alt="ChatGPT MCP setup" width="1213" height="971" data-path="integrations/mcp/chatgpt-mcp.png" />
        </Frame>
      </Tab>

      <Tab title="Config file">
        Add the following to your `mcp.json` configuration file:

        ```json theme={null}
        {
          "mcpServers": {
            "periskope": {
              "url": "https://api.periskope.app/mcp"
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authorize via OAuth">
    After adding the MCP server URL, your client will open the Periskope authorization page.

    1. **Select your organization** from the list
    2. **Choose the WhatsApp phone(s)** you want to grant access to
    3. Click **Authorize**

    You'll be redirected back to your AI client — fully connected and ready to use.

    <Frame caption="Periskope OAuth authorization screen">
      <img className="block border rounded-xl shadow" src="https://mintcdn.com/bharatkumarramesh/jmkHMscwYb258Qi5/integrations/mcp/oauth-consent.png?fit=max&auto=format&n=jmkHMscwYb258Qi5&q=85&s=a3a6629fd31d5851ef39dce5cd3f4e87" alt="OAuth authorization screen" width="2242" height="1392" data-path="integrations/mcp/oauth-consent.png" />
    </Frame>
  </Step>
</Steps>

## Available Tools

The MCP provides several tools for interacting with Periskope's WhatsApp API:

### Chat Management

* **periskope\_list\_chats**: Lists all WhatsApp chats
* **periskope\_get\_chat**: Gets details about a specific WhatsApp chat
* **periskope\_create\_chat**: Creates a new WhatsApp group chat
* **periskope\_update\_chat\_labels**: Updates the labels of a WhatsApp chat
* **periskope\_update\_chat**: Updates a WhatsApp chat properties on Periskope
* **periskope\_update\_chat\_settings**: Updates the settings of a WhatsApp chat
* **periskope\_search\_chat**: Searches for chats by name
* **periskope\_list\_all\_messages**: Lists all messages across all chats globally
* **periskope\_list\_all\_notifications**: Lists all notifications across all chats globally
* **periskope\_get\_chat\_notifications**: Gets notifications for a specific chat
* **periskope\_get\_chat\_notes**: Gets all private notes in a specific chat

### Message Management

* **periskope\_send\_message**: Sends a WhatsApp message (text, media, or poll) to a specified chat
* **periskope\_list\_messages\_in\_a\_chat**: Lists all messages in a specific WhatsApp chat
* **periskope\_list\_messages\_in\_a\_chat\_by\_id**: Gets a message by its ID
* **periskope\_get\_message\_status**: Gets the delivery status of a message
* **periskope\_react\_to\_message**: Reacts to a message
* **periskope\_forward\_message**: Forwards a message to other chats
* **periskope\_broadcast\_message**: Broadcasts a message to multiple chats at once
* **periskope\_pin\_message**: Pins or unpins a message in a chat
* **periskope\_edit\_message**: Edits a message in a chat
* **periskope\_delete\_message**: Deletes a message from a chat
* **periskope\_search\_message**: Searches for messages by content

### Contact Management

* **periskope\_create\_contact**: Creates a new WhatsApp contact
* **periskope\_list\_contacts**: Lists all WhatsApp contacts
* **periskope\_update\_contact**: Updates a WhatsApp contact
* **periskope\_update\_contact\_labels**: Updates labels for multiple contacts at once
* **periskope\_get\_contact\_by\_id**: Gets a contact by its ID
* **periskope\_search\_contact**: Searches for contacts by name
* **periskope\_check\_contacts**: Checks if given contact IDs exist on WhatsApp

### Group Management

* **periskope\_add\_participants\_to\_group**: Adds participants to a WhatsApp group
* **periskope\_remove\_participants\_from\_group**: Removes participants from a WhatsApp group
* **periskope\_promote\_participants\_to\_admins**: Promotes participants to admins in a WhatsApp group
* **periskope\_demote\_participants\_from\_admins**: Demotes participants from admins in a WhatsApp group

### Ticket Management

* **periskope\_create\_ticket**: Creates a new ticket
* **periskope\_get\_all\_tickets**: Gets all tickets
* **periskope\_get\_ticket**: Gets details about a specific ticket
* **periskope\_update\_ticket**: Updates an existing ticket

### Task Management

* **periskope\_list\_tasks**: Lists all tasks
* **periskope\_get\_task**: Gets details about a specific task
* **periskope\_create\_task**: Creates a new task
* **periskope\_update\_task**: Updates an existing task

### Knowledge Base

* **periskope\_list\_knowledge\_base**: Lists all knowledge base entries (FAQs and documents)
* **periskope\_get\_context\_by\_id**: Fetches a knowledge base FAQ entry by its context ID
* **periskope\_get\_document\_by\_id**: Gets a knowledge base document by its document ID
* **periskope\_create\_faq**: Creates a new FAQ entry in the knowledge base
* **periskope\_update\_faq**: Updates an existing FAQ entry in the knowledge base
* **periskope\_delete\_faq**: Deletes a FAQ entry from the knowledge base
* **periskope\_create\_document**: Uploads a PDF document to the knowledge base via URL or base64
* **periskope\_delete\_document**: Deletes a document from the knowledge base

### Private Notes

* **periskope\_create\_private\_note**: Creates a private internal note in a chat (not visible to customers)
* **periskope\_list\_private\_notes**: Lists all private notes
* **periskope\_get\_private\_note\_by\_id**: Gets a private note by its ID

### Reactions

* **periskope\_get\_reactions**: Gets reactions with optional filtering by chat, message, and time range

### Team Management

* **periskope\_invite\_members**: Invites new team members by email

### AI

* **periskope\_trigger\_ai\_reply**: Triggers an AI-generated reply for a specific chat message

## Use Cases

<Card title="Ticket Management" icon="ticket">
  Close, reopen, reassign, and update tickets directly through natural language. Set priorities, add labels, update status, and manage ticket properties effortlessly.

  <br />

  *"Close all tickets assigned to John and reassign them to Sarah with high priority"*
</Card>

<Card title="Sentiment Analysis" icon="face-smile">
  Understand how customers feel across all your WhatsApp conversations. Fetch recent messages from any chat and ask your AI assistant to analyze tone, flag unhappy customers, and surface conversations that need urgent attention.

  <br />

  *"Read the last 20 messages from the latest 5 chats and tell me which customers seem frustrated"*
</Card>

<Card title="Message Operations" icon="message-dots">
  Send, search, forward, and delete messages on WhatsApp with simple commands. Search message history, bulk forward content, and manage message reactions all through conversation.

  <br />

  *"Search for messages containing 'invoice' in the last week and forward them to the accounting group"*
</Card>

<Card title="Chat Management" icon="messages">
  Create and update chats, manage group settings, and handle chat properties. Set descriptions, images, and control messaging permissions through natural language.

  <br />

  *"Create a new group called 'Project Alpha' with Bob, Alice, and Charlie, and set it to admin-only messages"*
</Card>

<Card title="Group Administration" icon="users">
  Add, remove, demote, and promote group participants with ease. Manage admin privileges and participant access through simple commands.

  <br />

  *"Add the new interns to the 'Marketing Team' group and promote Sarah to admin"*
</Card>

<Card title="Contact Management" icon="address-book">
  Search, update, and manage contact information efficiently. Add labels, update contact properties, and organize your WhatsApp contacts through conversation.

  <br />

  *"Find all contacts labeled as 'VIP' and update their custom properties to include their company names"*
</Card>