Telegram Bot AI Integration Troubleshooting Journal

Purpose

Integrating Google’s generative AI—Gemini—into a Telegram Bot.

Implementation Steps

1. Create a Telegram Bot

1. Create a new bot in Telegram’s BotFather.
2. Set the bot’s commands (commands can accept parameters while being called).

2. Obtain a Gemini API Key

• Create an API key on the Google AI platform.
• The Gemini 1.5 Flash model supports up to 15 queries per minute.

3. Connect Home Assistant (HA) + Nabu Casa

Telegram Bot needs to communicate with Home Assistant, with two available methods:

Method 1: Polling

• Sends requests continuously to achieve real-time communication.
• May result in duplicate messages due to network issues.
• No need to expose public IP or configure HTTPS.
• Telegram discourages this method due to frequent server queries.

Method 2: Webhook (Recommended)

• When the bot receives a new command, it sends a request to HA.
• Requires public access, usually needing:
  • Static public IP or dynamic DNS.
  • A valid SSL certificate.
• Since I subscribe to Nabu Casa cloud service, this solves the public access issue conveniently.

Home Assistant Configuration

1. Configure configuration.yaml

telegram_bot:
  - platform: webhooks
    api_key: !secret telegram_bot_api_key
    allowed_chat_ids:
      - !secret personal_id
      - !secret group_id
    trusted_networks:
      - 149.154.160.0/20 # Telegram server IP
      - 91.108.4.0/22 # Telegram server IP
      - 127.0.0.1 # Required for Nabu Casa

2. Add rest_command

ask_gemini:
  url: !secret gemini_flash_url
  method: post
  payload: '{"contents":[{"parts":[{"text":"{{ prompt }}"}]}]}'
  content_type: 'application/json'

3. Set up Automation

alias: telegram command /gemini
description: 'Handle /gemini command'
triggers:
  - platform: event
    event_type: telegram_command
    event_data:
      command: /gemini
  - platform: event
    event_type: telegram_command
    event_data:
      command: /gemini@my_telegram_bot
conditions: []
actions:
  - service: rest_command.ask_gemini
    data:
      prompt: "{% for word in trigger.event.data['args'] %}{{ word }} {% endfor %}"
    response_variable: gemini_response
  - if:
      - condition: template
        value_template: "{{ gemini_response['status'] == 200 }}"
    then:
      - service: telegram_bot.send_message
        data:
          message: >
            {{
              gemini_response['content']['candidates'][0]['content']['parts'][0]['text']
            }}
          target:
            - "{{ trigger.event.data['chat_id'] }}"
          parse_mode: plain_text
mode: single

Troubleshooting Notes

1. trusted_networks** must include **127.0.0.1

   • When using Nabu Casa, requests arrive at HA as 127.0.0.1.
   • The default IP whitelist does not include 127.0.0.1, which can cause Webhook to reject valid Telegram messages.
   • HA now follows Telegram’s recommendation of embedding a random **32-character **secret_token in the Webhook URL, minimizing security risks.

2. YAML configurations for ****telegram_bot****** API Key and Chat ID should be quoted**

   • Prevents parsing errors.

3. Restart HA after modifying telegram_bot section in YAML configurations

   • Simply reloading YAML files will not apply changes.

4. Automation triggers should support both command formats

   • /gemini (used in private chat or direct calls).
   • /gemini@my_telegram_bot (in group chats, Telegram appends the bot ID).
   • If the bot ID is missing in group chats, the command may not trigger automation.

5. Check Webhook status

   curl https://api.telegram.org/bot{{bot_token}}/getWebhookInfo
   

6. Webhook prevents usage of ****getUpdates****** API**

   • Webhook and getUpdates API are mutually exclusive.
   • To use getUpdates (e.g., retrieving chat_id), first delete the Webhook:

     curl https://api.telegram.org/bot{{bot_token}}/deleteWebhook
     

   • Webhook will automatically rebind after HA restarts.

7. Gemini API response structure

   • Currently extracting responses using gemini_response['content']['candidates'][0]['content']['parts'][0]['text'].
   • This structure is based on observed test data and may change in future updates.

📌 If you’re also experimenting with Telegram Bot + AI, let’s connect! 😊