Telegram

Talks to a Telegram bot in both directions: push a notification into a group, or let someone in that group type a command and get an answer back.

Type: telegram · Category: Notification · Ports: one input · one output

When to use it

• Notifying a shift group where people actually look
• Letting a supervisor ask for a number without opening the Platform
• Getting alerts to phones without an SMS contract
• Sending a position — a pin, a named place, or a live share that follows a vehicle

Settings

Setting	Key	Default	Purpose
Connection	connectionId	—	Which bot.
Mode	mode	send	Send — dispatch a message, or Receive — messages / commands.
Action	action	message	Send mode only. What kind of thing to send — see Actions.
Chat ID	to	—	Chat or channel. Blank uses the connection's default chat.
Body	body	—	Templated message text.
Commands	commands	—	Receive mode: which commands to handle, e.g. /data.

A node's Mode decides its ports: a send node has an input and a receive node has an output.

Actions

A send node also carries an action. It defaults to Message, so a pipeline saved before actions existed opens on exactly the panel it always had.

Action	Sends
Message	Text and attachments. The original behaviour.
Location	A pin — optionally a live one that this platform then moves.
Venue	A named place: a titled card rather than bare coordinates.
Move live location	Drives a live pin an earlier node started.
Stop live location	Ends one.
Ask for the recipient's location	Shows the button that lets a person send theirs back.

All six share the connection, the recipient and {{path}} interpolation — only the last step differs, which is why they are one node with a dropdown rather than six node types.

Sending a position

Field	Key	Notes
Latitude / Longitude	latitude / longitude	Required.
Accuracy (m)	horizontalAccuracy	Optional, 0–1500.
Heading	heading	Optional, 1–360 degrees.
Live period	livePeriod	0 = a fixed pin. Otherwise 15 minutes, 1 hour, 8 hours or 24 hours (Telegram's maximum).
Title / Address	title / address	Venue only.

The coordinate fields are text, not number inputs, on purpose. The useful case is not typing a latitude — it is binding one — and a number input cannot hold {{payload.location.latitude}}.

Example A — sending

Mode: send
To:   -1001234567890
Body: ⚠️ {{payload.name}} — {{payload.tagPath}} is {{payload.value}} (limit {{payload.limit}})

Example B — receiving a command

A shift lead types /data LINE1 in the group and gets an answer back.

Telegram (receive, /data) → Python (parse argument) → SQL (query) → Telegram (send)

Out of the receive node

{
  "payload": {
    "command": "/data",
    "args": ["LINE1"],
    "chatId": -1001234567890,
    "from": { "id": 4471, "username": "shiftlead_a" }
  }
}

A path that does not exist becomes empty

{{payload.data}} against a message with no data field renders as nothing at all — you get Value: rather than Value: {{payload.data}}. A raw token arriving in somebody's inbox looks like data the author meant to send, so a blank is the safer failure.

The practical consequence is that a mistyped path is invisible: the message still sends, just missing a piece. Send one to yourself, or watch a Debug node, before wiring it to an escalation.

The database nodes do the opposite with the same syntax — there an unresolved token is left as literal text.

Example C — a live location that follows a vehicle

Start the live share, keep the message id, and move the same pin as new positions arrive.

1. Start it. A send node with action Location and a live period:

Action:       Location — a pin, optionally live
Chat ID:      -1001234567890
Latitude:     {{payload.lat}}
Longitude:    {{payload.lon}}
Live period:  8 hours

Out

{
  "payload": {
    "channel": "telegram", "action": "location", "sent": true,
    "live": true, "messageId": 5512, "messageIds": [5512]
  }
}

2. Keep that messageId. It is the handle for every later move and for the stop, and there is no way to look it up again. Store it in a tag or a pipeline variable.

3. Move it. A second node with action Move live location:

Action:      Move live location
Message ID:  {{payload.messageId}}
Latitude:    {{payload.lat}}
Longitude:   {{payload.lon}}

4. Stop it when the job ends, with action Stop live location and the same message id.

Example D — asking someone where they are

Action: Ask for the recipient's location
Body:   Please share your location so we can dispatch the nearest crew.
Button: Share my location

The answer does not come back out of this node. Pressing the button sends a fresh location message that arrives as a normal inbound update, so the flow that reads it is a receive node. The node says so in its own output (awaitingReply: true), so a run shows what it is waiting for.

Gotchas

• Carry chatId through and bind the reply's Chat ID to it. Otherwise the answer goes to whichever chat is typed into the send node, rather than to whoever asked.
• Treat from and args as untrusted. A command node is a door into your database; validate the arguments before they reach a query.
• A live location cannot be moved in several chats at once. Telegram identifies one by (chat, message id) and those ids differ per chat, so a node that fanned a live share out to three chats got three handles back and there is no single id that moves all of them. The node says so rather than silently editing whichever chat sorted first — use one node per chat.
• A missing coordinate is an error, not a pin in the Atlantic. {{payload.lat}} against a message with no lat renders as empty, and (0, 0) is a real point off the coast of Africa that Telegram accepts without complaint. A required coordinate that resolves to nothing fails loudly and names the field.
• A bot cannot start a conversation. Somebody must message it, or add it to the group, first. → Notification providers
• One bot token, one installation. Telegram hands a bot's incoming messages to exactly one poller, so a receive node on a test server sharing production's token gets some of the commands and production gets the rest. Give each installation its own bot. 1.0.8 The node no longer says token in use elsewhere: the check behind it fired on a single installation's own restart and made a healthy bot flicker between connected and failed, so it was removed. A shared token now shows only as commands that go missing. → One bot token, one installation
• Read the line under the node. 1.0.7 It says whether the bot is connected and how many messages have gone in and out — receiving · 12 in · 5 out — which is how a receive node that has heard nothing is told apart from one whose bot is down. The counts reset when the pipeline stops, unless another running pipeline shares the bot. 1.0.8 The line shows only while the pipeline runs — on a stopped pipeline a bot's last receiving · 12 in read as the stopped node still being live. → Connection status under a node
• A send that reached some recipients is not sent again. 1.0.8 Telegram sends once per chat. When one chat fails, the node carries on with the others, then retries only the chats that received nothing and whose failure looks temporary, within the node's own retry count and delay. If anybody already has the message, the node is not re-run as a whole — before 1.0.8 a retry re-sent to everyone, once per retry. A chat that got the text but not an attachment is never retried, because that would repeat the text. The node's error names who was missed: delivered to 2 of 3 recipient(s); failed: ….
• Failed sends show on the connection. 1.0.8 The bot's status message counts them — · 5 out · 2 failed (last: …) — so a bot whose sends all fail no longer looks merely quiet. A failed send does not change the bot's state: the bot may be fine and one chat id wrong.
• A disabled connection fails the node. 1.0.7 Before 1.0.7 a disabled bot went on polling and sending.