Telegram Bot API

Access the Telegram Bot API with managed authentication. Send messages, photos, polls, locations, and more through your Telegram bot.

Quick Start

# Get bot info
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/telegram/:token/getMe')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/telegram/:token/{method}

The :token placeholder is automatically replaced with your bot token from the connection configuration. Replace {method} with the Telegram Bot API method name (e.g., sendMessage, getUpdates).

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Telegram bot connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=telegram&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'telegram'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response: json { "connection": { "connection_id": "e8f5078d-e507-4139-aabe-1615181ea8fc", "status": "ACTIVE", "creation_time": "2026-02-07T10:37:21.053942Z", "last_updated_time": "2026-02-07T10:37:59.881901Z", "url": "https://connect.maton.ai/?session_token=...", "app": "telegram", "metadata": {} } }

Open the returned url in a browser to complete the bot token configuration.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Telegram connections (multiple bots), specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/telegram/:token/getMe')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'e8f5078d-e507-4139-aabe-1615181ea8fc')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Bot Information

Get Bot Info

GET /telegram/:token/getMe

Returns information about the bot.

Response: json { "ok": true, "result": { "id": 8523474253, "is_bot": true, "first_name": "Maton", "username": "maton_bot", "can_join_groups": true, "can_read_all_group_messages": true, "supports_inline_queries": true } }

Getting Updates

Get Updates (Long Polling)

POST /telegram/:token/getUpdates
Content-Type: application/json

{
  "limit": 100,
  "timeout": 30,
  "offset": 625435210
}

Get Webhook Info

GET /telegram/:token/getWebhookInfo

Set Webhook

POST /telegram/:token/setWebhook
Content-Type: application/json

{
  "url": "https://example.com/webhook",
  "allowed_updates": ["message", "callback_query"],
  "secret_token": "your_secret_token"
}

Delete Webhook

POST /telegram/:token/deleteWebhook
Content-Type: application/json

{
  "drop_pending_updates": true
}

Sending Messages

Send Text Message

POST /telegram/:token/sendMessage
Content-Type: application/json

{
  "chat_id": 6442870329,
  "text": "Hello, World!",
  "parse_mode": "HTML"
}

With HTML Formatting:

POST /telegram/:token/sendMessage
Content-Type: application/json

{
  "chat_id": 6442870329,
  "text": "<b>Bold</b> and <i>italic</i> with <a href=\"https://example.com\">link</a>",
  "parse_mode": "HTML"
}

With Inline Keyboard:

POST /telegram/:token/sendMessage
Content-Type: application/json

{
  "chat_id": 6442870329,
  "text": "Choose an option:",
  "reply_markup": {
    "inline_keyboard": [
      [
        {"text": "Option 1", "callback_data": "opt1"},
        {"text": "Option 2", "callback_data": "opt2"}
      ],
      [
        {"text": "Visit Website", "url": "https://example.com"}
      ]
    ]
  }
}

Send Photo

POST /telegram/:token/sendPhoto
Content-Type: application/json

{
  "chat_id": 6442870329,
  "photo": "https://example.com/image.jpg",
  "caption": "Image caption"
}

Send Document

POST /telegram/:token/sendDocument
Content-Type: application/json

{
  "chat_id": 6442870329,
  "document": "https://example.com/file.pdf",
  "caption": "Document caption"
}

Send Video

POST /telegram/:token/sendVideo
Content-Type: application/json

{
  "chat_id": 6442870329,
  "video": "https://example.com/video.mp4",
  "caption": "Video caption"
}

Send Audio

POST /telegram/:token/sendAudio
Content-Type: application/json

{
  "chat_id": 6442870329,
  "audio": "https://example.com/audio.mp3",
  "caption": "Audio caption"
}

Send Location

POST /telegram/:token/sendLocation
Content-Type: application/json

{
  "chat_id": 6442870329,
  "latitude": 37.7749,
  "longitude": -122.4194
}

Send Contact

POST /telegram/:token/sendContact
Content-Type: application/json

{
  "chat_id": 6442870329,
  "phone_number": "+1234567890",
  "first_name": "John",
  "last_name": "Doe"
}

Send Poll

POST /telegram/:token/sendPoll
Content-Type: application/json

{
  "chat_id": 6442870329,
  "question": "What is your favorite color?",
  "options": [
    {"text": "Red"},
    {"text": "Blue"},
    {"text": "Green"}
  ],
  "is_anonymous": false
}

Send Dice

POST /telegram/:token/sendDice
Content-Type: application/json

{
  "chat_id": 6442870329,
  "emoji": "🎲"
}

Supported emoji: 🎲 🎯 🎳 🏀 ⚽ 🎰

Editing Messages

Edit Message Text

POST /telegram/:token/editMessageText
Content-Type: application/json

{
  "chat_id": 6442870329,
  "message_id": 123,
  "text": "Updated message text"
}

Edit Message Caption

POST /telegram/:token/editMessageCaption
Content-Type: application/json

{
  "chat_id": 6442870329,
  "message_id": 123,
  "caption": "Updated caption"
}

Edit Message Reply Markup

POST /telegram/:token/editMessageReplyMarkup
Content-Type: application/json

{
  "chat_id": 6442870329,
  "message_id": 123,
  "reply_markup": {
    "inline_keyboard": [
      [{"text": "New Button", "callback_data": "new"}]
    ]
  }
}

Delete Message

POST /telegram/:token/deleteMessage
Content-Type: application/json

{
  "chat_id": 6442870329,
  "message_id": 123
}

Forwarding & Copying

Forward Message

POST /telegram/:token/forwardMessage
Content-Type: application/json

{
  "chat_id": 6442870329,
  "from_chat_id": 6442870329,
  "message_id": 123
}

Copy Message

POST /telegram/:token/copyMessage
Content-Type: application/json

{
  "chat_id": 6442870329,
  "from_chat_id": 6442870329,
  "message_id": 123
}

Chat Information

Get Chat

POST /telegram/:token/getChat
Content-Type: application/json

{
  "chat_id": 6442870329
}

Get Chat Administrators

POST /telegram/:token/getChatAdministrators
Content-Type: application/json

{
  "chat_id": -1001234567890
}

Get Chat Member Count

POST /telegram/:token/getChatMemberCount
Content-Type: application/json

{
  "chat_id": -1001234567890
}

Get Chat Member

POST /telegram/:token/getChatMember
Content-Type: application/json

{
  "chat_id": -1001234567890,
  "user_id": 6442870329
}

Bot Commands

Set My Commands

POST /telegram/:token/setMyCommands
Content-Type: application/json

{
  "commands": [
    {"command": "start", "description": "Start the bot"},
    {"command": "help", "description": "Get help"},
    {"command": "settings", "description": "Open settings"}
  ]
}

Get My Commands

GET /telegram/:token/getMyCommands

Delete My Commands

POST /telegram/:token/deleteMyCommands
Content-Type: application/json

{}

Bot Profile

Get My Description

GET /telegram/:token/getMyDescription

Set My Description

POST /telegram/:token/setMyDescription
Content-Type: application/json

{
  "description": "This bot helps you manage tasks."
}

Set My Name

POST /telegram/:token/setMyName
Content-Type: application/json

{
  "name": "Task Bot"
}

Files

Get File

POST /telegram/:token/getFile
Content-Type: application/json

{
  "file_id": "AgACAgQAAxkDAAM..."
}

Response: json { "ok": true, "result": { "file_id": "AgACAgQAAxkDAAM...", "file_unique_id": "AQAD27ExGysnfVBy", "file_size": 7551, "file_path": "photos/file_0.jpg" } }

Download files from: https://api.telegram.org/file/bot<token>/<file_path>

Callback Queries

Answer Callback Query

POST /telegram/:token/answerCallbackQuery
Content-Type: application/json

{
  "callback_query_id": "12345678901234567",
  "text": "Button clicked!",
  "show_alert": false
}

Code Examples

JavaScript

// Send a message
const response = await fetch(
  'https://gateway.maton.ai/telegram/:token/sendMessage',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chat_id: 6442870329,
      text: 'Hello from JavaScript!'
    })
  }
);
const data = await response.json();
console.log(data);

Python

import os
import requests

# Send a message
response = requests.post(
    'https://gateway.maton.ai/telegram/:token/sendMessage',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={
        'chat_id': 6442870329,
        'text': 'Hello from Python!'
    }
)
print(response.json())

Python (urllib)

import urllib.request, os, json

data = json.dumps({
    'chat_id': 6442870329,
    'text': 'Hello from Python!'
}).encode()
req = urllib.request.Request(
    'https://gateway.maton.ai/telegram/:token/sendMessage',
    data=data,
    method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
response = json.load(urllib.request.urlopen(req))
print(json.dumps(response, indent=2))

Response Format

All Telegram Bot API responses follow this format:

Success: json { "ok": true, "result": { ... } }

Error: json { "ok": false, "error_code": 400, "description": "Bad Request: chat not found" }

Notes

• :token is automatically replaced with your bot token from the connection
• Chat IDs are integers for private chats and can be negative for groups
• All methods support both GET and POST, but POST is recommended for methods with parameters
• Text messages have a 4096 character limit
• Captions have a 1024 character limit
• Polls support 2-10 options
• File uploads require multipart/form-data (use URLs for simplicity)
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with telegram. For example:

• Correct: https://gateway.maton.ai/telegram/:token/sendMessage
• Incorrect: https://gateway.maton.ai/:token/sendMessage

Resources

• Telegram Bot API Documentation
• Available Methods
• Formatting Options
• Inline Keyboards
• Bot Commands
• Maton Community
• Maton Support