Telegram: Send message

Sends a plain-text message to a Telegram chat, group or channel, as a bot.

• Kind: telegram.send_message
• Palette: Integrations, under Telegram
• Credential: a credential of kind url_token, named in credential

When to use

• Alerts to a phone without running a chat server.
• A personal notification channel for long runs: “the import finished”, “approval waiting”.

The bot token goes in the request URL, which is what the url_token credential kind is for: the token is put into the URL as the request is sent, and the graph holds only the credential’s name.

Connection (with)

Field	Required	Description
chat_id	yes	Target chat id or @username the bot can post to. For example: -1001234567890 or @channelname.

Input (input)

Field	Type	Required	Description
text	string	yes	Message text (plain).

Settings

Beside with and input in the node’s config.

Field	Type	Required	Description
credential	string	yes	Name of the project credential the action authenticates with.
fail_on_error_status	boolean	no	Treat any 4xx/5xx as a failure. On by default: an action either did its job or did not. Default true.
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.
retry_on	array	no	Status codes that fail the node instead of returning, so its retry: policy applies (e.g. [429, 503]).

Output

The HTTP response. The reply is under body: nodes.<id>.output.body.<field>.

Field	Type	Description
status	integer	The HTTP status code.
headers	object	The response headers.
body	object	The response body, parsed as JSON when it is JSON.
body.ok	boolean
body.result	object	The message sent; result.message_id is its id.

How it runs

• On an agent with the connector capability. The managed environments have one, so this needs no agent of your own.
• One POST request to api.telegram.org.
• Any 4xx or 5xx fails the step, unless fail_on_error_status is false. retry: asks again after a 5xx, a 401, 408, 409, 423, 425 or 429, or a 4xx with Retry-After, and not after any other 4xx, which would get the same answer.

Example

version: hyperspool-graph/v1
nodes:
  - id: import
    type: shell
    config: { run: ./import.sh && spool output set rows=1200 }
  - id: tell_me
    type: telegram.send_message
    config:
      credential: telegram
      with: { chat_id: "-1001234567890" }
      input:
        text: { $template: "Import done: {{ nodes.import.output.rows }} rows" }
edges:
  - { from: import, to: tell_me }

Create the credential with spool credential set telegram --kind url-token. The bot has to be a member of the chat, and for a channel an admin of it.

See Connectors for credentials and versions, and the node reference for every other node.