# Telegram Signal Integration {% hint style="warning" %} The Telegram Signal Integration is currently in beta. It is recommended to validate its behavior using a demo account before deploying it in a live trading environment. {% endhint %} The Telegram Signal Integration enables the automated reception and execution of trading signals from Telegram channels and groups. By connecting your Telegram account to MetaCopier via the official Telegram API, incoming messages are analyzed by an AI engine to identify actionable trading signals (e.g., open, close, modify). Once a valid signal is detected, it is automatically executed on the linked trading account without any manual intervention. In essence, MetaCopier acts as an intelligent assistant that transforms Telegram messages into executable trading actions. ## Requirements To use the Telegram Signal Integration with MetaCopier, ensure the following: * One or more trading accounts connected to MetaCopier * A Telegram account with access to the signal provider’s channel or group ## Quick Start ### Step 1: Get Telegram API Credentials To communicate with your Telegram, you need to create API credentials. Please follow the steps below: 1. Go to [my.telegram.org](https://my.telegram.org) and log in with your phone number 2. Click on **"API development tools"** 3. If you already have an API configured, proceed to step 6. 4. Fill in the application form: * **App title**: MetaCopier (or any name you prefer) * **Short name**: metacopier (or any name you prefer) * **Platform**: Desktop * **Description**: Trading signal integration 5. Click **"Create application"** 6. Copy and save your **API ID** and **API Hash**
{% hint style="danger" %} Keep your API credentials secure. Never share them with anyone. {% endhint %} ### Step 2: Create a Telegram Account in MetaCopier Navigate to the **Telegram** section in your project and find the **Telegram Signal Integration** section. Click the **"+"** button to add a new Telegram account.
A setup dialog will open. Follow the workflow: 1. Enter your **API ID** and **API Hash** from Step 1 2. Enter your **phone number** in international format (e.g., +1234567890) 3. Select the **region** that matches where your trading accounts are deployed 4. Click **Save** {% hint style="info" %} **Important:** Select a region that matches where your trading accounts are deployed. For example, if your trading account is in New York, select the New York region for your Telegram account. {% endhint %} ### Step 3: Complete Verification After saving, Telegram will send a **verification code** to your Telegram app. Enter the code in MetaCopier to authorize the connection. If you have **Two-Factor Authentication (2FA)** enabled on your Telegram account, you'll also need to enter your 2FA password.
Once verified, a confirmation message will be displayed.
In Telegram, you will receive a notification asking you to confirm the login from the selected region. Please confirm by selecting **“Yes, it’s me.”**
On the Telegram Signal Integration page, the status will change to **“Authorized”**, and your available chats will be loaded.
### Step 4: Add Telegram Connector to Your Trading Account Now you need to link a Telegram chat to your trading account. Go to your **Trading Account** and add the **"Telegram Connector"** feature. In the Telegram Connector dialog: 1. Select the **Telegram Account** you created in Step 2 2. Select the **Chat/Channel** you want to receive signals from 3. Select the **AI Model Tier** (Basic, Standard, or Pro) 4. Configure the connector settings (optional) 5. Click **Save** That's it! Signals from the selected Telegram chat will now be executed on your trading account. {% hint style="info" %} **Multiple Connectors:** You can add multiple Telegram Connectors to the same trading account to receive signals from different channels. You can also connect the same channel to multiple trading accounts. {% endhint %} ### Step 5: Protect Your Account Following signals from untrusted sources can expose your account to significant financial risk. It is essential to understand these risks and implement appropriate safeguards. We strongly recommend using the following features: * [**Risk Limiter**](https://docs.metacopier.io/features/basic-features#risk-limits)**:** This is one of the most important protection tools. We recommend setting a strict limit on the account that is following the signals. The Risk Limiter allows you to automatically close all open positions if a predefined drawdown threshold is exceeded, helping to prevent excessive losses. * [**Max Open Positions**](https://docs.metacopier.io/features/basic-features#max-open-positions)**:** This feature is useful for controlling exposure by limiting the number of simultaneously open positions. It ensures that your account does not exceed a predefined level of activity or risk. * **Maximum Lot Size:** In the Telegram Connector, you can define a *Maximum Allowed Volume* to limit the lot size of each individual position. This helps ensure that no trade exceeds your predefined risk limits. *** ## AI Signal Interpretation MetaCopier uses AI to interpret trading signals from Telegram messages. The AI understands various signal formats commonly used by signal providers. ### Supported Signal Formats The AI can detect signals in various formats: **Simple format:** ``` BUY EURUSD SL: 1.0800 TP: 1.0950 ``` **With lot size:** ``` SELL GOLD 0.5 lot SL 2650 TP1 2620 TP2 2600 ``` **Natural language:** ``` Open a long position on GBPUSD at market price Stop loss at 1.2550, take profit at 1.2700 Volume: 0.1 ``` **Signal provider style:** ``` 🟢 XAUUSD BUY NOW 2680 ✅ TP1: 2695 ✅ TP2: 2710 ❌ SL: 2665 ``` ### AI Instructions Use the **AI Instructions** field to provide specific instructions for better signal interpretation: **Example AI instructions:** * "The signal provider uses GOLD instead of XAUUSD" * "SL/TP values are always in points, not price" * "Ignore messages from admin that contain 'announcement'" * "Volume is specified in mini lots (multiply by 0.1)" * "Only process messages that contain the 🔔 emoji" * "Use half of the lot size defined in the chat message." *** ## AI Model Tier When creating a Telegram Connector, you can choose the AI model tier used for signal interpretation. The tier determines the quality and accuracy of the AI engine that analyzes your Telegram messages. | Tier | Description | Monthly Cost | | ------------ | --------------------------------------------------------------- | ------------------------ | | **Basic** | Default model. Suitable for most standard signal formats. | Free | | **Standard** | Enhanced model with better accuracy for complex signal formats. | $5/month (billed daily) | | **Pro** | Premium model for maximum accuracy and advanced interpretation. | $10/month (billed daily) | {% hint style="warning" %} **The AI Model Tier cannot be changed after the connector is created.** To switch to a different tier, you must delete the connector and create a new one. {% endhint %} When selecting Standard or Pro, a confirmation dialog will appear showing the cost. The charge is calculated on a daily basis (monthly price ÷ 30 days). {% hint style="info" %} **Message Limit:** Each connector can process a maximum of **100 messages per day**. Messages beyond this limit will be ignored. {% endhint %} *** ## Best Practices ### Security **Protect your Telegram credentials:** * Never share your API ID, API Hash, or verification codes * Use 2FA on your Telegram account for extra security ### Performance 1. **Choose the right region:** Select the region closest to your trading account's server for lower latency 2. **Start with a demo account:** Test the integration with a demo account first to verify signals are interpreted correctly 3. **Use AI instructions:** Provide clear AI instructions to help the AI understand your signal provider's format 4. **Monitor regularly:** Check the connector status and review executed trades periodically ### Multiple Signal Providers You can subscribe to multiple signal providers by: 1. Creating separate Telegram Connectors for each channel 2. Using different **magicNumber** values to identify which provider triggered each trade *** ## Troubleshooting ### Telegram Account Issues **"Code Required" status won't change?** 1. Check your Telegram app for the verification code 2. Enter the code exactly as received (no spaces) 3. The code expires after a few minutes - request a new one if needed **"Session Expired" error?** 1. Telegram sessions can expire after inactivity 2. Edit the Telegram account and re-verify with a new code **Chats not loading?** 1. Make sure the account status is "Authorized" 2. You must be a member of the channel/group to see it 3. Private channels require an invite link to join first ### Connector Issues **Signals not being executed?** 1. Check that the connector is **enabled** 2. Verify the Telegram account status is "Authorized" 3. Check if the action is in the **allowedActions** list 4. Review the connector's error message if status is "ERROR" **Wrong symbol being traded?** 1. Use **AI Instructions** to specify symbol name mappings 2. Example: "GOLD means XAUUSD, US30 means DJ30" **Volume not correct?** 1. Set **volumeMode** to `FIXED` and configure **defaultVolume** if signals don't include lot size 2. Set **volumeMode** to `BALANCE_SCALED` and configure **lotsPerThousandBalance** to automatically scale volume based on account balance 3. Set **volumeMode** to `AI` to let AI determine volume based on the signal (customize via AI Instructions, e.g., "use 50% of signal volume") 4. Use **forceVolumeMode** = `true` to always use the configured volumeMode and ignore any volume specified in the signal 5. Use **maxAllowedVolume** as a safety cap for any volume mode 6. Use **AI Instructions** to explain the volume format **SL/TP not being set?** 1. Set **defaultStopLossPoints** and **defaultTakeProfitPoints** 2. Use **AI Instructions** to clarify if values are in points or price *** ## Frequently Asked Questions (FAQ) **Can I use the same Telegram account for multiple trading accounts?**\ Yes. Create one Telegram account at the project level, then add multiple Telegram connectors to different trading accounts, all linked to the same Telegram account. **Does this work with private channels?**\ Yes, as long as your Telegram account is a member of the private channel. **What happens if the signal provider sends multiple signals quickly?**\ Each signal is processed independently. Consider using the *Max Open Positions* feature to limit exposure. **Can I filter which signals to trade?**\ Yes. Use `allowedActions` to restrict specific actions, and apply AI instructions to filter by keywords, emojis, or message patterns. **Is there a delay in signal execution?**\ Signals are processed in near real-time (typically under one second). The primary latency depends on Telegram’s message delivery. **What if the AI misinterprets a signal?**\ Review the trade in your account logs and adjust the AI instructions to improve accuracy. You can also set `allowedActions` to an empty array (`[]`) to pause execution during testing. *** ## Settings details ### Telegram Account | Option | Type | Default | Description | | --------------------- | ------- | ------- | --------------------------------------------------------------------------------- | | `apiId` | number | - | Your Telegram API ID from my.telegram.org | | `apiHash` | string | - | Your Telegram API Hash from my.telegram.org | | `phoneNumber` | string | - | Phone number in international format (+1234567890) | | `regionId` | number | - | Region where the Telegram client runs | | `includePrivateChats` | boolean | `false` | Include private chats in the available chats list (default: only groups/channels) | ### Telegram Connector | Option | Type | Default | Description | | -------------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `telegramAccountFeatureId` | UUID | - | Reference to the Telegram Account feature ID (required) | | `chatId` | number | - | Telegram chat ID to subscribe to (required) | | `chatTitle` | string | - | Chat title (read-only, populated automatically) | | `enabled` | boolean | `true` | Enable/disable signal processing | | `allowedActions` | array | all | Allowed actions: `open`, `close`, `modify`. Empty = all | | `aiInstructions` | string | - | AI instructions for signal interpretation (max 2000 characters). Use this to customize how the AI interprets signals. The default prompt is always included. Examples: symbol mappings, volume adjustments, filtering rules | | `aiTier` | string | `BASIC` | AI model tier: `BASIC` (free), `STANDARD` ($5/month), or `PRO` ($10/month). Can only be set on creation — cannot be changed after the connector is created | | `volumeMode` | string | `FIXED` | Volume calculation mode: `FIXED` (use defaultVolume), `BALANCE_SCALED` (calculate from account balance), or `AI` (let AI determine volume based on signal, customizable via aiInstructions) | | `forceVolumeMode` | boolean | `false` | If `true`, always use `volumeMode` calculation and ignore any volume specified in the signal. If `false`, use signal volume when provided. Note: `forceVolumeMode=true` with `volumeMode=AI` falls back to `defaultVolume` | | `maxAllowedVolume` | number | `1.0` | Maximum allowed volume safety limit (min 0.001). Applies to ALL volume modes. Calculated volume is capped to this value | | `defaultVolume` | number | - | Default lot size if not specified in signal (min 0.001, used when volumeMode=`FIXED`) | | `lotsPerThousandBalance` | number | `0.01` | Lots per 1000 balance (min 0.001, used when volumeMode=`BALANCE_SCALED`). Example: balance 10000 with value 0.01 = 0.1 lots | | `defaultStopLossPoints` | number | - | Default SL in points if not in signal (min 0) | | `defaultTakeProfitPoints` | number | - | Default TP in points if not in signal (min 0) | | `magicNumber` | number | - | Magic number for positions from this connector | | `comment` | string | - | Position comment (max 20 characters) | | `messageExpiryMinutes` | number | `10` | Maximum message age in minutes (1–10080). Messages older than this are skipped (e.g., due to network delays, Telegram outages, or server restarts). Default is 10 | | `confidenceThreshold` | number | `70` | AI confidence threshold (0–100). Only signals with confidence >= this threshold are executed. Lower = more signals (but more false positives), higher = fewer signals (but more reliable) | | `contextMessageCount` | number | `5` | Number of recent messages included as AI context (1–10). Higher values give the AI more context for multi-message signals but consume more tokens | | `status` | string | `PENDING` | Connector status (read-only) | | `errorMessage` | string | - | Error message if status is ERROR (read-only) | | `lastMessageAt` | datetime | - | Last message processed timestamp (read-only) | ### Authorization Status | Status | Description | | ------------------- | ---------------------------------------- | | `PENDING` | Waiting for initial setup | | `CODE_REQUIRED` | Verification code sent to Telegram app | | `PASSWORD_REQUIRED` | 2FA password required | | `AUTHORIZED` | Connected and ready | | `FAILED` | Authorization failed | | `SESSION_EXPIRED` | Session expired, re-authorization needed | | `DISCONNECTED` | Disconnected from Telegram | ### Connector Status | Status | Description | | -------------- | ----------------------------------------- | | `PENDING` | Connector created, waiting for activation | | `ACTIVE` | Receiving and processing messages | | `PAUSED` | Temporarily paused (enabled = false) | | `ERROR` | Error occurred (check error message) | | `DISCONNECTED` | Parent Telegram account disconnected |