# Telegram Webhook API - Instructions for AI Agents

## Endpoint

POST /api/message

## Authentication

You MUST authenticate using one of these methods:

1. Header: `X-Webhook-Secret: <secret>`
2. Query param: `/api/message?secret=<secret>`

## Request

Content-Type: application/json

### Required Fields

- `text` (string): Message text content

### Optional Fields

- `text` (string): Text message content

- `chat_id` (string | number): Override default chat ID (optional, uses TELEGRAM_CHAT_ID env var if not provided)
- `parse_mode` (string): "MarkdownV2" | "HTML" | "Markdown"
- `disable_notification` (boolean): Send silently
- `protect_content` (boolean): Prevent forwarding/saving
- `reply_to_message_id` (number): Reply to specific message
- `message_thread_id` (number): Forum topic ID
- `link_preview_options` (object): Control link previews
  - `is_disabled` (boolean)
  - `url` (string)
  - `prefer_small_media` (boolean)
  - `prefer_large_media` (boolean)
  - `show_above_text` (boolean)

### Reply Markup Options

- `reply_markup` (object): One of:
  - Inline keyboard: `{ "inline_keyboard": [[{ "text": "Button", "url": "https://..." }]] }`
  - Reply keyboard: `{ "keyboard": [[{ "text": "Option 1" }]], "resize_keyboard": true }`
  - Remove keyboard: `{ "remove_keyboard": true }`
  - Force reply: `{ "force_reply": true }`

## Example Request

```bash
curl -X POST https://your-domain.vercel.app/api/message \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your_secret" \
  -d '{
    "text": "Hello from AI agent!",
    "parse_mode": "MarkdownV2"
  }'
```

## Example with Inline Keyboard

```json
{
  "text": "Choose an option:",
  "reply_markup": {
    "inline_keyboard": [
      [
        { "text": "Option A", "callback_data": "a" },
        { "text": "Option B", "callback_data": "b" }
      ],
      [
        { "text": "Visit Site", "url": "https://example.com" }
      ]
    ]
  }
}
```

## Response

### Success

```json
{
  "ok": true,
  "result": { /* Telegram Message object */ }
}
```

### Error

```json
{
  "ok": false,
  "error": "Error description"
}
```

## HTTP Status Codes

- 200: Success
- 400: Bad request (missing/invalid fields)
- 401: Unauthorized (invalid/missing secret)
- 500: Server error or Telegram API error

## Notes for AI Agents

1. Always include authentication header or query param
2. Only `text` field is required - chat_id uses server default
3. Use MarkdownV2 parse_mode for formatted text (escape special chars: `_*[]()~>#+-=|{}.!`)
4. For silent notifications, set `disable_notification: true`
5. Rate limits are determined by Telegram API (generally 30 msg/sec to different chats)