Skip to content

Telegram Bot Integration

Integrate WPsigner with Telegram to send signing requests and notifications directly to your signers via a Telegram bot — completely free, no monthly limits.

Features

Section titled “Features”
FeatureDescription
Signing RequestsSend signature links with inline “Sign” button
RemindersManual reminders for pending signatures
Completion NotificationsNotify signers when document is complete
Inline ButtonsOne-tap buttons to open signing pages
Encrypted TokenAES-256-GCM encryption for bot token
HTML FormattingRich messages with bold, italic, and links

Prerequisites

Section titled “Prerequisites”
  • ✅ WPsigner 2.1.0+
  • ✅ A Telegram account (free)
  • ✅ A Telegram bot created via @BotFather

Step 1: Create a Telegram Bot

Section titled “Step 1: Create a Telegram Bot”

  1. Open Telegram and search for @BotFather (or click this link)

  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

Step 2: Configure WPsigner

Section titled “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”

Step 3: Get Signer Chat IDs

Section titled “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

Section titled “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 — it will reply with their Chat ID:

Id: 123456789
  1. Share the Chat ID with the document admin

Step 4: Add Chat ID to Signers

Section titled “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

How It Works

Section titled “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

Section titled “Automatic Notifications”
EventTelegram 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

Section titled “Message Examples”

Signing Request

Section titled “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

Section titled “Completion Notification”
🎉 Document Completed


All signatures on "Service Agreement" are complete.


You will receive a copy via email shortly.

Security

Section titled “Security”
FeatureImplementation
Token EncryptionAES-256-GCM encryption at rest
Nonce VerificationCSRF protection on all AJAX requests
Input ValidationChat ID format validation (numeric)
Rate LimitingTelegram allows ~30 messages/second

API Reference

Section titled “API Reference”

Send Message Programmatically

Section titled “Send Message Programmatically”
// 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

Section titled “Check Telegram Status”
if ( WPS_Telegram::is_enabled() && WPS_Telegram::is_configured() ) {
    // Telegram is ready
}

Send Manual Reminder

Section titled “Send Manual Reminder”
WPS_Telegram::send_reminder( $signer_id );

Troubleshooting

Section titled “Troubleshooting”

Bot Token Invalid

Section titled “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

Section titled “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”

Section titled “”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

Section titled “Comparison: Telegram vs WhatsApp”
FeatureTelegramWhatsApp
CostFreePaid after 1K msgs/month
Setup@BotFather (2 min)Meta Business Account + App
TemplatesFree-form textPre-approved templates
Rich MessagesHTML + inline buttonsTemplate params only
Rate Limit~30 msg/sec250-100K/day (tiers)
User IDChat IDPhone number (E.164)

FAQ

Section titled “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

Section titled “Next Steps”