# Analytics MCP

### Introduction

The PayRam Telegram Analytics Bot provides direct access to PayRam analytics from Telegram. Once configured, authorized users can query payments, users, payouts, and activity without accessing the PayRam dashboard.

The bot connects securely to the PayRam Analytics server and responds only in allowlisted chats, enabling teams to monitor metrics, generate summaries, and obtain insights directly within Telegram.

***

### Prerequisites

Before setting up the PayRam Telegram Analytics Bot, ensure the following requirements are met:

* A server (VPS or dedicated machine) where the bot will be deployed and run
* A running PayRam server with analytics enabled
* PayRam dashboard **admin credentials** (email and password)
* A Telegram bot token created using **@BotFather**
  * Refer to this guide for setup instructions: <https://blog.devgenius.io/how-to-set-up-your-telegram-bot-using-botfather-fd1896d68c02>
* An OpenAI API key for generating analytics responses
* Docker installed on the server

***

### Installation

{% stepper %}
{% step %}

#### Run the setup script

```
./setup_payram_agent.sh
```

{% endstep %}

{% step %}

#### Provide required configuration details

* During the setup process, you will be prompted to enter the following information:

  * **Publicly accessible PayRam Server URL**
    * This URL must be reachable by the analytics bot.

  <figure><img src="/files/1ucGWmeILVRDa9ygVbqq" alt=""><figcaption></figcaption></figure>

  * **PayRam dashboard admin credentials**
    * The admin email and password used to authenticate the analytics bot with your PayRam server.

<figure><img src="/files/hj16AZ0LgfO06KL2T9ze" alt=""><figcaption></figcaption></figure>

* **OpenAI API Key**
  * Required to enable AI-powered analytics responses.
* **Telegram Bot Token**
  * The token generated via **@BotFather** for your Telegram bot.
* **Allowed Telegram Users**

  * A comma-separated list of Telegram usernames that are permitted to interact with the bot.

  <figure><img src="/files/26Gsp0j54brzTUuMdGjz" alt=""><figcaption></figcaption></figure>
* **Auto-Updates (Optional)**

  * Choose whether the analytics bot should automatically update itself when new versions of the Analytics MCP server are released.

  <figure><img src="/files/zvrge6EHAYCpQRct5UQ9" alt=""><figcaption></figcaption></figure>
* **Start Container After Setup (Optional)**

  * Choose whether to start the analytics agent Docker container immediately after the setup completes.

  <figure><img src="/files/nBQCAuzyFDA4rdrQl0rC" alt=""><figcaption></figcaption></figure>

If you choose to start the container during setup, the Analytics MCP server will be installed and running once the process completes. You can then open Telegram and begin using the bot.
{% endstep %}

{% step %}

#### Using the Telegram Analytics Bot

Once the setup is complete, open Telegram and send a message to the bot from an allowlisted chat. The bot will respond with PayRam analytics in the same chat.

**Example Queries:**

* **“Show me today’s payments summary.”**
* **“Create a payment link for 3 USD on the main project with email <example@gmail.com> and customerId cust-123.”**
* **“Top paying users this week.”**
* **“Deposit distribution by chain for the last 7 days.”**
* **“Payouts by currency for December.”**
* **“User growth compared to the previous period.”**
  {% endstep %}
  {% endstepper %}

> <mark style="color:$warning;">**Access Control Note**</mark>
>
> <mark style="color:$warning;">If you message the bot from a chat that is not allowlisted, it will respond with an</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">**“Access denied”**</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">message along with the</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`chat_id`</mark><mark style="color:$warning;">. Add this</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`chat_id`</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">using the allowlist update command, then retry your request.</mark>

### Managing Bot Access

You can grant access to additional users or groups without rerunning the full setup by using the commands below.

#### Add Telegram Usernames (Recommended)

Use this option to allow individual Telegram users to interact with the analytics bot:

```bash
./setup_payram_agent.sh --add-telegram-usernames "alice,@bob,t.me/carol"
```

> <mark style="color:$warning;">**Notes:**</mark>
>
> * <mark style="color:$warning;">Usernames can be provided with or without the</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`@`</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">prefix or</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`t.me/`</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">format.</mark>
> * <mark style="color:$warning;">Multiple usernames must be comma-separated.</mark>

#### Add Telegram Chat IDs (For Groups)

Use this to allow Telegram groups or chats:

```bash
./setup_payram_agent.sh --add-telegram-chat-ids "12345,67890"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payram.com/mcp/analytics-mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.