텔레그램 챗봇


모바일 또는 데스크톱 장치에서 송수신 기능을 사용하여 홈어시스턴트와 메시지 또는 명령을 주고받습니다.

이 통합구성요소는 polling 플랫폼 또는 다음으로 구성된 Telegram Bot account에서 메시지를 보내거나 이전에 보낸 메시지를 편집하는 알림 서비스를 만듭니다. webhooks 및 메시지 수신시 이벤트를 트리거합니다.

메시지를 받을 필요가 없는 경우 broadcast 플랫폼을 대신 사용할 수 있습니다.

알림 서비스

제공 서비스 : send_message, send_photo, send_document, send_location, send_sticker, edit_message, edit_replymarkup, edit_caption, answer_callback_query, delete_message, leave_chat.

telegram_bot.send_message 서비스

알림을 보냅니다.

Service data attribute Optional Description
message no 알림의 메시지 본문.
title yes 알림의 제목입니다. 예: ‘%title\n%message’.
target yes 알림을 보낼 사전 승인 된 chat_id 또는 user_id의 배열. 첫 번째로 허용되는 chat_id가 기본값.
parse_mode yes 메시지 텍스트 파서: html 혹은 markdown.
disable_notification yes 메시지를 자동으로 보내기위한 True/False. iOS 사용자와 웹 사용자는 알림을 받지 않으며, Android 사용자는 소리없이 알림을 받습니다. 기본값은 False.
disable_web_page_preview yes 메시지의 링크에 대한 링크 미리보기를 사용하지 않는 경우 True/false.
keyboard yes 사용자 정의 키보드를 만들기 위한 쉼표로 구분된 command line 목록. []로 사용자 정의 키보드가 없는 것으로 재설정. 예: ["/command1, /command2", "/command3"]
inline_keyboard yes 콜백 데이터가 연결된 버튼이 있는 사용자 지정 인라인 키보드를 만들기 위해 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.send_photo 및 telegram_bot.send_sticker 서비스

사진을 보냅니다.

Service data attribute Optional Description
url no 이미지의 원격 경로.
file no 이미지의 로컬 경로.
caption yes 이미지의 제목.
username yes HTTP 기본 인증이 필요한 URL의 사용자 이름.
password yes HTTP 기본 인증이 필요한 URL의 비밀번호.
authentication yes 사용할 인증 방법을 정의하십시오. digest는 HTTP 다이제스트 인증을 사용합니다. 기본은 basic 입니다.
target yes 알림을 보낼 사전승인된 chat_id 또는 user_id의 배열입니다. 첫 번째로 허용되는 chat_id가 기본값.
disable_notification yes 메시지를 조용히 보내기 True/false. iOS 사용자와 웹 사용자는 알림을 받지 않으며, Android 사용자는 소리없이 알림을 받습니다. 기본값은 False.
verify_ssl yes HTTPS URL에 대한 서버의 SSL 인증서를 확인하는 경우 True/false. 기본값은 True.
keyboard yes 커스텀 키보드를 만들기 위한 쉼표로 구분된 command line 목록. []로 사용자 정의 키보드가 없는 것으로 재설정. 예: ["/command1, /command2", "/command3"]
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.send_video 서비스

비디오 보내기.

Service data attribute Optional Description
url no 비디오의 원격 경로.
file no 비디오의 로컬 경로.
caption yes 비디오의 제목.
username yes HTTP 기본 인증이 필요한 URL의 사용자 이름.
password yes HTTP 기본 인증이 필요한 URL의 비밀번호.
authentication yes 사용할 인증 방법을 정의하십시오. digest는 HTTP 다이제스트 인증을 사용합니다. 기본은 basic 입니다.
target yes 알림을 보낼 사전 승인된 chat_id 또는 user_id의 배열입니다. 첫 번째로 허용되는 chat_id가 기본값입니다.
disable_notification yes 메시지를 자동으로 보내려면 True/False 입니다. iOS 사용자와 웹 사용자는 알림을 받지 않습니다. Android 사용자에게는 소리가 들리지 않는 알림이 수신됩니다. 기본값은 False입니다.
verify_ssl yes HTTPS URL에 대한 서버의 SSL 인증서를 확인하는 True/False 기본값은 True.
keyboard yes 커스텀 키보드를 만들기 위한 쉼표로 구분된 command line 목록. []로 사용자 정의 키보드가 없는 것으로 재설정. 예: ["/command1, /command2", "/command3"]
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.send_document 서비스

문서를 보냅니다.

Service data attribute Optional Description
url no 문서의 원격 경로.
file no 문서의 로컬 경로.
caption yes 문서의 제목.
username yes HTTP 기본 인증이 필요한 URL의 사용자 이름.
password yes HTTP 기본 인증이 필요한 URL의 비밀번호.
authentication yes 사용할 인증 방법을 정의하십시오. digest는 HTTP 다이제스트 인증을 사용합니다. 기본은 basic 입니다.
target yes 알림을 보낼 사전 승인된 chat_id 또는 user_id의 배열입니다. 첫 번째로 허용되는 chat_id가 기본값입니다.
disable_notification yes 메시지를 자동으로 보내려면 True/False 입니다. iOS 사용자와 웹 사용자는 알림을 받지 않습니다. Android 사용자에게는 소리가 들리지 않는 알림이 수신됩니다. 기본값은 False입니다.
verify_ssl yes HTTPS URL에 대한 서버의 SSL 인증서를 확인하는 True/False 기본값은 True.
keyboard yes 커스텀 키보드를 만들기 위한 쉼표로 구분된 command line 목록. []로 사용자 정의 키보드가 없는 것으로 재설정. 예: ["/command1, /command2", "/command3"]
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.send_location 서비스

위치를 전송합니다.

Service data attribute Optional Description
latitude no 보낼 위도.
longitude no 보낼 경도.
target yes 알림을 보낼 사전승인된 chat_id 또는 user_id의 배열입니다. 첫 번째로 허용되는 chat_id가 기본값입니다.
disable_notification yes 메시지를 자동으로 보내려면 True/false입니다. iOS 사용자와 웹 사용자는 알림을받지 않으며, Android 사용자는 소리없이 알림을 받습니다. 기본값은 False입니다.
keyboard yes 커스텀 키보드를 만들기 위한 쉼표로 구분된 command line 목록. []로 사용자 정의 키보드가 없는 것으로 재설정. 예: ["/command1, /command2", "/command3"]
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.edit_message 서비스

대화에서 이전에 보낸 메시지를 편집합니다.

Service data attribute Optional Description
message_id no 편집할 메시지의 ID. 누른 버튼에서 콜백에 응답할 때 원본 메시지의 ID는 {{trigger.event.data.message.message_id}}에 있습니다. "last"를 사용하여 chat_id에 전송된 마지막 메시지 참조 가능.
chat_id no 메시지를 편집할 chat_id.
message no 알림 메시지 본문.
title yes 알림의 제목입니다. ‘% title \ n % message’로 구성됩니다.
parse_mode yes 메시지 텍스트 파서 : html 혹은 markdown.
disable_web_page_preview yes 메시지의 링크에 대한 링크 미리보기를 사용하지 않도록 설정하는 경우 True/False.
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.edit_caption 서비스

이전에 보낸 메시지의 캡션을 편집합니다.

Service data attribute Optional Description
message_id no 편집할 메시지의 ID. 누른 버튼에서 콜백에 응답할 때 원본 메시지의 ID는 {{trigger.event.data.message.message_id}}에 있습니다. "last"를 사용하여 chat_id에 전송된 마지막 메시지 참조 가능.
chat_id no 캡션을 편집할 chat_id.
caption no 알림의 메시지 본문.
disable_web_page_preview yes 메시지의 링크에 대한 링크 미리보기를 사용하지 않도록 설정하는 경우 True/False.
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] or [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.edit_replymarkup 서비스

이전에 보낸 메시지의 인라인 키보드를 편집합니다.

Service data attribute Optional Description
message_id no 편집할 메시지의 ID. 누른 버튼에서 콜백에 응답할 때 원본 메시지의 ID는 {{trigger.event.data.message.message_id}}에 있습니다. "last"를 사용하여 chat_id에 전송된 마지막 메시지 참조 가능.
chat_id no reply_markup을 편집할 수 있는 chat_id.
disable_web_page_preview yes 메시지의 링크에 대한 링크 미리보기를 사용하지 않도록 설정하는 경우 True/False.
inline_keyboard yes 연관된 콜백 데이터가 있는 버튼으로 사용자 정의 인라인 키보드를 만들기 위한 쉼표로 구분된 command line 목록. 예: ["/button1, /button2", "/button3"] 혹은 [[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]

telegram_bot.answer_callback_query 서비스

온라인 키보드 버튼을 클릭하여 생성된 콜백 쿼리에 응답합니다. 답변은 채팅 화면 상단에 알림 또는 경보로 사용자에게 표시됩니다.

Service data attribute Optional Description
message no 알림의 형식이 지정되지 않은 문자 메시지 본문.
callback_query_id no 콜백 응답의 고유 ID telegram_callback 이벤트 데이터: {{ trigger.event.data.id }}
show_alert yes permanent notification를 표시하려면 True/false입니다. 기본값은 False입니다.

telegram_bot.delete_message 서비스

대화에서 이전에 보낸 메시지를 삭제합니다.

Service data attribute Optional Description
message_id no 메시지의 ID를 삭제하십시오. 누른 버튼으로 콜백에 응답하면 원래 메시지의 ID : {{ trigger.event.data.message.message_id }}. "last"를 사용하여 chat_id에 전송된 마지막 메시지 참조 가능.
chat_id no 메시지를 삭제할 chat_id.

telegram_bot.leave_chat 서비스

추가된 채팅 그룹에서 봇을 제거합니다.

Service data attribute Optional Description
chat_id no 봇을 제거할 위치의 chat_id

telegram 알림 플랫폼

telegram notification platform을 작동하기 위해 telegram_bot 연동이 필요하며 알림 (메시지, 사진, 문서 및 위치)을 전송하기 위한 사용자 정의 단축키 (notify.USERNAME)를 생성하도록 설계되었습니다. 이전 문법으로 특정 chat_id에 추가하여 이전 버전과의 호환성을 허용합니다.

필요한 YAML 설정은 다음같이 줄어듭니다. :

notify:
  - name: NOTIFIER_NAME
    platform: telegram
    chat_id: USER_CHAT_ID

이벤트 트리거 (Event triggering)

/thecommand 혹은 /othercommand with some args 같은 것들.

홈어시스턴트가 수신하면 이벤트 버스에서 telegram_command 이벤트를 다음과 같은 event_data와 함께 시작합니다. :

command: "/thecommand"
args: "<any other text following the command>"
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
chat_id: "<origin chat id>"
chat: "<chat info>"

/로 시작하지 않는 다른 메시지는 간단한 텍스트로 처리되어 다음 이벤트 _event와 함께 이벤트 버스에서 telegram_text 이벤트를 발생시킵니다. :

text: "some text received"
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
chat_id: "<origin chat id>"
chat: "<chat info>"

예를 들어 press from an inline button에서 메시지가 전송되면 콜백 쿼리가 수신됩니다. 홈어시스턴트는 다음과 같이 telegram_callback 이벤트를 시작합니다.

data: "<data associated to action callback>"
message: <message origin of the action callback>
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
id: "<unique id of the callback>"
chat_instance: "<chat instance>"
chat_id: "<origin chat id>"

설정 샘플

간단한 핑퐁 사례

alias: 'Telegram bot that reply pong to ping'
trigger:
  platform: event
  event_type: telegram_command
  event_data:
    command: '/ping'
action:
  - service: notify.notify
    data:
      message: 'pong'

notify.telegram과의 키보드 상호 작용을 보여주는 예

trigger:
  platform: event
  event_type: telegram_command
  event_data:
    command: '/start'
action:
  - service: notify.telegram
    data:
      message: 'commands'
      data:
        keyboard:
          - '/ping, /alarm'
          - '/siren'

관련 명령 “/siren”을 트리거하는 자동화.

trigger:
  platform: event
  event_type: telegram_command
  event_data:
    command: '/siren'
action:
  - service: homeassistant.turn_on
    entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0
  - delay:
      seconds: 10
  - service: homeassistant.turn_off
    entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0

실제 event_data 사용을 보여주는 예제 :

- alias: 'Kitchen Telegram Speak'
  trigger:
    platform: event
    event_type: telegram_command
    event_data:
      command: '/speak'
  action:
    - service: notify.kitchen_echo
      data_template:
        message: >
          Message from {{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}

콜백 쿼리 및 인라인 키보드를 사용한 샘플 자동화

‘EDIT’, ‘NO’ 및 ‘REMOVE BUTTON’ 버튼이 있는 인라인 키보드를 표시하는 일반 텍스트의 간단한 리피터로 구성된 단순한 자동화 기능을 갖춘 인라인 키보드의 일부 콜백 기능을 보여주는 간단한 예

  • ‘EDIT’, ‘NO’ 및 ‘REMOVE BUTTON’
  • ‘NO’를 누르면 간단한 알림만 표시됩니다. (콜백 쿼리에 응답).
  • ‘REMOVE BUTTON’를 누르면 해당 버튼을 제거하는 인라인 키보드가 변경됩니다.

텍스트 반복 :

- alias: 'Telegram bot that repeats text'
  trigger:
    platform: event
    event_type: telegram_text
  action:
    - service: telegram_bot.send_message
      data_template:
        title: '*Dumb automation*'
        target: '{{ trigger.event.data.user_id }}'
        message: 'You said: {{ trigger.event.data.text }}'
        disable_notification: true
        inline_keyboard:
          - "Edit message:/edit_msg, Don't:/do_nothing"
          - "Remove this button:/remove button"

메시지 에디터 :

- alias: 'Telegram bot that edits the last sent message'
  trigger:
    platform: event
    event_type: telegram_callback
    event_data:
      command: '/edit_msg'
  action:
    - service: telegram_bot.answer_callback_query
      data_template:
        callback_query_id: '{{ trigger.event.data.id }}'
        message: 'Editing the message!'
        show_alert: true
    - service: telegram_bot.edit_message
      data_template:
        message_id: '{{ trigger.event.data.message.message_id }}'
        chat_id: '{{ trigger.event.data.chat_id }}'
        title: '*Message edit*'
        inline_keyboard:
          - "Edit message:/edit_msg, Don't:/do_nothing"
          - "Remove this button:/remove button"
        message: >
          Callback received from {{ trigger.event.data.from_first }}.
          Message id: {{ trigger.event.data.message.message_id }}.
          Data: {{ trigger.event.data.data }}

키보드 에디터 :

- alias: 'Telegram bot that edits the keyboard'
  trigger:
    platform: event
    event_type: telegram_callback
    event_data:
      command: '/remove button'
  action:
    - service: telegram_bot.answer_callback_query
      data_template:
        callback_query_id: '{{ trigger.event.data.id }}'
        message: 'Callback received for editing the inline keyboard!'
    - service: telegram_bot.edit_replymarkup
      data_template:
        message_id: 'last'
        chat_id: '{{ trigger.event.data.chat_id }}'
        inline_keyboard:
          - "Edit message:/edit_msg, Don't:/do_nothing"

‘NO’ 답변만 인지 :

- alias: 'Telegram bot that simply acknowledges'
  trigger:
    platform: event
    event_type: telegram_callback
    event_data:
      command: '/do_nothing'
  action:
    - service: telegram_bot.answer_callback_query
      data_template:
        callback_query_id: '{{ trigger.event.data.id }}'
        message: 'OK, you said no!'

텔레그램 콜백은 일반 메시지와 동일한 방식으로 인수 및 명령을 지원합니다.

- alias: 'Telegram bot repeats arguments on callback query'
  trigger:
    platform: event
    event_type: telegram_callback
    event_data:
      command: '/repeat'
  action:
    - service: telegram_bot.answer_callback_query
      data_template:
        show_alert: true
        callback_query_id: '{{ trigger.event.data.id }}'
        message: 'I repeat: {{trigger.event.data["args"]}}'

이 경우, /repeat 1 2 3으로 콜백을 하면 팝업창에 I repeat: [1, 2, 3] 라고 알림이 뜹니다.

telegram_bot 기능을 보다 복잡하게 사용하려면 AppDaemon을 사용하는 것이 좋습니다.

이것이 바로 이전의 4가지의 자동화가 간단한 AppDaemon 앱을 통한 방법입니다 :

import appdaemon.plugins.hass.hassapi as hass


class TelegramBotEventListener(hass.Hass):
    """Event listener for Telegram bot events."""

    def initialize(self):
        """Listen to Telegram Bot events of interest."""
        self.listen_event(self.receive_telegram_text, "telegram_text")
        self.listen_event(self.receive_telegram_callback, "telegram_callback")

    def receive_telegram_text(self, event_id, payload_event, *args):
        """Text repeater."""
        assert event_id == "telegram_text"
        user_id = payload_event["user_id"]
        msg = "You said: ``` %s ```" % payload_event["text"]
        keyboard = [
            [("Edit message", "/edit_msg"), ("Don't", "/do_nothing")],
            [("Remove this button", "/remove button")],
        ]
        self.call_service(
            "telegram_bot/send_message",
            title="*Dumb automation*",
            target=user_id,
            message=msg,
            disable_notification=True,
            inline_keyboard=keyboard,
        )

    def receive_telegram_callback(self, event_id, payload_event, *args):
        """Event listener for Telegram callback queries."""
        assert event_id == "telegram_callback"
        data_callback = payload_event["data"]
        callback_id = payload_event["id"]
        chat_id = payload_event["chat_id"]
        # keyboard = ["Edit message:/edit_msg, Don't:/do_nothing",
        #             "Remove this button:/remove button"]
        keyboard = [
            [("Edit message", "/edit_msg"), ("Don't", "/do_nothing")],
            [("Remove this button", "/remove button")],
        ]

        if data_callback == "/edit_msg":  # Message editor:
            # Answer callback query
            self.call_service(
                "telegram_bot/answer_callback_query",
                message="Editing the message!",
                callback_query_id=callback_id,
                show_alert=True,
            )

            # Edit the message origin of the callback query
            msg_id = payload_event["message"]["message_id"]
            user = payload_event["from_first"]
            title = "*Message edit*"
            msg = "Callback received from %s. Message id: %s. Data: ``` %s ```"
            self.call_service(
                "telegram_bot/edit_message",
                chat_id=chat_id,
                message_id=msg_id,
                title=title,
                message=msg % (user, msg_id, data_callback),
                inline_keyboard=keyboard,
            )

        elif data_callback == "/remove button":  # Keyboard editor:
            # Answer callback query
            self.call_service(
                "telegram_bot/answer_callback_query",
                message="Callback received for editing the " "inline keyboard!",
                callback_query_id=callback_id,
            )

            # Edit the keyboard
            new_keyboard = keyboard[:1]
            self.call_service(
                "telegram_bot/edit_replymarkup",
                chat_id=chat_id,
                message_id="last",
                inline_keyboard=new_keyboard,
            )

        elif data_callback == "/do_nothing":  # Only Answer to callback query
            self.call_service(
                "telegram_bot/answer_callback_query",
                message="OK, you said no!",
                callback_query_id=callback_id,
            )