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