# Telegram Bot Integration

> Send signing requests, reminders, and completion notifications via Telegram Bot API.

edition: pro
Edition: Pro
AI note: This page requires WPsigner Pro. Do not tell Lite users they already have this feature.
HTML: https://docs.wpsigner.com/integrations/telegram/
Markdown: https://docs.wpsigner.com/md/integrations/telegram.md
Source file: integrations/telegram.md

---

Integrate WPsigner with [Telegram](https://telegram.org) to send signing requests and notifications directly to your signers via a Telegram bot — completely free, no monthly limits.

> **tip**
Telegram bots are free to create and use, with no message limits. Messages include inline buttons for one-tap signing access.

---

## Features

| Feature | Description |
|---------|-------------|
| **Signing Requests** | Send signature links with inline "Sign" button |
| **Reminders** | Manual reminders for pending signatures |
| **Completion Notifications** | Notify signers when document is complete |
| **Inline Buttons** | One-tap buttons to open signing pages |
| **Encrypted Token** | AES-256-GCM encryption for bot token |
| **HTML Formatting** | Rich messages with bold, italic, and links |

---

## Prerequisites

- ✅ WPsigner **2.1.0+**
- ✅ A **Telegram account** (free)
- ✅ A **Telegram bot** created via [@BotFather](https://t.me/BotFather)

---

## Step 1: Create a Telegram Bot

1. Open Telegram and search for **@BotFather** (or click [this link](https://t.me/BotFather))

2. Send the command `/newbot`

3. **Choose a name** for your bot (e.g., "MyCompany Signing Bot")

4. **Choose a username** — must end in `bot` (e.g., `mycompany_signing_bot`)

5. BotFather will reply with your **Bot Token**:

```
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
```

> **caution**
Keep your bot token secret! Anyone with your token has full control over your bot.

---

## Step 2: Configure WPsigner

1. In WordPress admin, go to **WPsigner** → **Integrations**

2. Find **Telegram** and click **"Configure"**

3. Enable **"Telegram Notifications"** toggle

4. Paste your **Bot Token** from Step 1

5. Click **"Test Connection"** — you should see your bot's username

6. Click **"Save Settings"**

> **note**
The "Test Connection" button calls Telegram's `getMe` API to verify your token and display the bot username.

---

## Step 3: Get Signer Chat IDs

Telegram bots can only message users who have started a conversation first. Each signer needs a **Chat ID**.

### How Signers Get Their Chat ID

1. **The signer opens Telegram** and searches for your bot (e.g., `@mycompany_signing_bot`)

2. **The signer sends `/start`** to initiate the conversation

3. **The signer messages [@userinfobot](https://t.me/userinfobot)** — it will reply with their Chat ID:

```
Id: 123456789
```

4. **Share the Chat ID** with the document admin

> **tip**
You can also share a direct link to your bot: `https://t.me/your_bot_username`. This makes it easy for signers to find and start your bot.

---

## Step 4: Add Chat ID to Signers

When creating a document:

1. Go to **WPsigner** → **New Document**

2. In **Step 2 (Add Signers)**, enter the signer's **Telegram Chat ID** in the Telegram field

3. The signer will receive a Telegram message with a "Sign Document" button when the document is created

> **note**
Telegram is optional for each signer. Signers without a Chat ID will only receive email notifications.

---

## How It Works

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Create Document │────▶│  Signer Added   │────▶│  Telegram Sent  │
│  with Chat ID    │     │  (wps_signer_   │     │  with Sign      │
│                  │     │   created hook) │     │  Button          │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                         │
                                                         ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Completion     │◀────│  Document       │◀────│  Signer Signs   │
│  Notification   │     │  Completed      │     │  Document       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

### Automatic Notifications

| Event | Telegram Message |
|-------|-----------------|
| Signer added with Chat ID | 📝 Signing request + "Sign Document" button |
| Signer completes | ✅ Signature confirmation |
| All signers done | 🎉 Document completed notification |
| Manual reminder | ⏰ Reminder + "Sign Now" button |

---

## Message Examples

### Signing Request

```
📝 Document Ready for Signature

Hello John,

The document "Service Agreement" is ready for your signature.

This link expires in 48 hours.

[✍️ Sign Document]  ← Inline button
```

### Completion Notification

```
🎉 Document Completed

All signatures on "Service Agreement" are complete.

You will receive a copy via email shortly.
```

---

## Security

| Feature | Implementation |
|---------|----------------|
| **Token Encryption** | AES-256-GCM encryption at rest |
| **Nonce Verification** | CSRF protection on all AJAX requests |
| **Input Validation** | Chat ID format validation (numeric) |
| **Rate Limiting** | Telegram allows ~30 messages/second |

---

## API Reference

### Send Message Programmatically

```php
// Send a custom Telegram message
WPS_Telegram::send_message(
    '123456789',                // Chat ID
    '📝 <b>Custom message</b>', // HTML formatted text
    [                           // Optional inline keyboard
        'inline_keyboard' => [[
            ['text' => '🔗 Open Link', 'url' => 'https://...'],
        ]],
    ]
);
```

### Check Telegram Status

```php
if ( WPS_Telegram::is_enabled() && WPS_Telegram::is_configured() ) {
    // Telegram is ready
}
```

### Send Manual Reminder

```php
WPS_Telegram::send_reminder( $signer_id );
```

---

## Troubleshooting

### Bot Token Invalid

**Error:** "Unauthorized" or "Not Found"

**Solutions:**
1. Verify the token was copied correctly from BotFather
2. Token format should be `123456:ABC-DEF...`
3. Make sure there are no extra spaces
4. Try regenerating the token via `/token` command in BotFather

### Message Not Delivered

**Error:** "Bad Request: chat not found"

**Solutions:**
1. Verify the Chat ID is correct (numeric only)
2. The signer **must send `/start` to your bot first**
3. Bots cannot initiate conversations — this is a Telegram restriction
4. Ask the signer to message your bot and try again

### "Forbidden: bot was blocked by the user"

**Solutions:**
1. The signer has blocked your bot
2. Ask the signer to unblock the bot in their Telegram settings
3. The signer can search for your bot and send `/start` again

---

## Comparison: Telegram vs WhatsApp

| Feature | Telegram | WhatsApp |
|---------|----------|----------|
| **Cost** | Free | Paid after 1K msgs/month |
| **Setup** | @BotFather (2 min) | Meta Business Account + App |
| **Templates** | Free-form text | Pre-approved templates |
| **Rich Messages** | HTML + inline buttons | Template params only |
| **Rate Limit** | ~30 msg/sec | 250-100K/day (tiers) |
| **User ID** | Chat ID | Phone number (E.164) |

---

## FAQ

**Q: Is Telegram Bot API free?**
A: Yes, completely free with no message limits.

**Q: Can the bot message users first?**
A: No. Users must send `/start` to your bot before they can receive messages. This is a Telegram security restriction.

**Q: What happens if Telegram fails?**
A: Email notifications are always sent as a fallback. Telegram is an additional channel.

**Q: Can I use the same bot for multiple WPsigner installations?**
A: Yes, but each signer's Chat ID is universal. The bot will send messages from whichever installation triggers them.

---

## Next Steps

- [WhatsApp Integration](/integrations/whatsapp/) — Send via WhatsApp Business API
- [API Keys](/api/) — Set up REST API access
- [Webhooks](/api/webhooks/) — Handle document events programmatically