id: telegram
name: Telegram
version: 1.0.0
description: "Telegram Bot API — SOC alerting via a bot: send text messages and photos to a chat, read chat info, and poll updates. Bot-token authentication; stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: send message, send photo, get chat, get updates."
category: notification

# Per-instance configuration. The bot token is placed in the API path
# (https://api.telegram.org/bot<token>/...).
config_schema:
  properties:
    bot_token:
      type: string
      description: "Telegram bot token (from BotFather)"
      x-soar-sensitive: true
    default_chat_id:
      type: string
      description: "Default chat ID to send to (optional)"
  required:
    - bot_token

commands:
  - id: send_message
    name: telegram-send-message
    description: "Send a text message to a chat."
    inputs_schema:
      properties:
        chat_id: { type: string, description: "Chat ID (overrides the configured default)" }
        text: { type: string, description: "Message text" }
        parse_mode: { type: string, description: "Optional: Markdown or HTML" }
      required: [text]
    outputs_schema: { properties: {} }
  - id: send_photo
    name: telegram-send-photo
    description: "Send a photo (by URL) to a chat."
    inputs_schema:
      properties:
        chat_id: { type: string, description: "Chat ID (overrides the configured default)" }
        photo: { type: string, description: "Photo URL" }
        caption: { type: string, description: "Optional caption" }
      required: [photo]
    outputs_schema: { properties: {} }
  - id: get_chat
    name: telegram-get-chat
    description: "Get information about a chat."
    risk: read
    inputs_schema:
      properties:
        chat_id: { type: string, description: "Chat ID (overrides the configured default)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_updates
    name: telegram-get-updates
    description: "Poll recent updates (incoming messages) for the bot."
    risk: read
    inputs_schema:
      properties:
        limit: { type: number, description: "Max updates (default 20)" }
        offset: { type: number, description: "Update offset (optional)" }
      required: []
    outputs_schema: { properties: {} }

  - id: test_connection
    name: telegram-test-connection
    description: "Verify the bot token (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }