Add responses for Telegram bot actions (#41692)

Author: hanwg

source/_integrations/telegram_bot.markdown

@@ -209,6 +209,8 @@ Send a notification.
 | `reply_to_message_id`      | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                           |
 | `message_thread_id`        | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_photo`
 
 Send a photo.
@@ -235,6 +237,8 @@ Send a photo.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_video`
 
 Send a video.
@@ -260,6 +264,8 @@ Send a video.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_animation`
 
 Send an animation.
@@ -286,6 +292,8 @@ Send an animation.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_voice`
 
 Send a voice message.
@@ -311,6 +319,8 @@ Send a voice message.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_sticker`
 
 Send a sticker.
@@ -336,6 +346,8 @@ Send a sticker.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_document`
 
 Send a document.
@@ -362,6 +374,8 @@ Send a document.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_location`
 
 Send a location.
@@ -381,6 +395,8 @@ Send a location.
 | `reply_to_message_id`  | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %}                                                                                                                       |
 | `message_thread_id`    | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_poll`
 
 Send a poll.
@@ -399,6 +415,8 @@ Send a poll.
 | `reply_to_message_id`     | yes      | Mark the message as a reply to a previous message. In `telegram_callback` handling, for example, you can use {% raw %}`{{ trigger.event.data.message.message_id }}`{% endraw %} |
 | `message_thread_id`       | yes      | Send the message to a specific topic or thread.|
 
+This action returns a [send message response](#send-message-response).
+
 ### Action `telegram_bot.send_chat_action`
 
 Send a chat action. Use it to notify the user with the relevant "typing" action when a bot response may be delayed, so they know a message is coming soon. Telegram clears this status after 5 seconds or when the reply arrives.
@@ -512,6 +530,40 @@ Sets the bot's reaction for a given message.
 | `reaction`          | no       | Emoji to react to the message with. |
 | `is_big`            | yes      | Whether to use a large variant of the reaction animation.        |
 
+## Response schemas for actions
+
+{% tip %}
+
+Responses can be accessed using the `response_variable` of actions.
+You can refer to the [send a message then edit it after a delay](#example-send_message-then-edit-it-after-a-delay) automation for an example of usage of the response.
+
+{% endtip %}
+
+### Send message response
+
+Response schema:
+
+| Data attribute | Optional | Type                 | Description                                                               |
+| -------------- | -------- | -------------------- | ------------------------------------------------------------------------- |
+| `chats`        | no       | list                 | A list of chat objects. Each object represents a successful message sent. |
+
+Chat object schema:
+
+| Data attribute | Optional | Type    | Description                             |
+| ---------------| -------- | ------- | --------------------------------------- |
+| `chat_id`      | no       | integer | The target chat_id of the sent message. |
+| `message_id`   | no       | integer | The id of the message.                  |
+
+Example response:
+
+```yaml
+chats:
+  - chat_id: 1234567890
+    message_id: 100
+  - chat_id: -1234567890
+    message_id: 200
+```
+
 ## Telegram notification platform
 
 {% warning %}
@@ -1011,6 +1063,27 @@ actions:
       disable_web_page_preview: true
 ```
 
+## Example: send_message then edit it after a delay
+
+{% raw %}
+
+```yaml
+actions:
+  - action: telegram_bot.send_message
+    data:
+      message: testing
+    response_variable: response
+  - delay:
+      seconds: 5
+  - action: telegram_bot.edit_message
+    data:
+      message: done testing
+      chat_id: "{{ response.chats[0].chat_id }}"
+      message_id: "{{ response.chats[0].message_id }}"
+```
+
+{% endraw %}
+
 ## Example: send_message to a topic within a group
 
 ```yaml