Skip to content

Chat apps ​

People can get their Notesflow notices in Telegram, Signal (experimental) and, where a workspace brings its own business account, WhatsApp. They can also reply there: tick a step that is theirs, mark a notice read, or send a note that is saved in today's journal.

Setting up the bot (operators) ​

  1. In Telegram, ask @BotFather for a new bot and copy its token.
  2. In /admin → Chat apps, paste the token and press Try and save. Notesflow asks Telegram who the bot is and tells it where to deliver messages. The token is kept only if both work. It is sealed with NOTESFLOW_SECRET and never shown again.

How messages reach Notesflow:

  • A webhook, when NOTESFLOW_API_URL is an https address Telegram can reach. Telegram posts to /api/chat/telegram/webhook with a secret only this bot knows, and anything without it is refused.
  • Asking, otherwise: the server asks Telegram every few seconds. This suits a deployment behind a firewall. Run one server that asks.

The environment can set the bot instead of the console: NOTESFLOW_TELEGRAM_TOKEN, with NOTESFLOW_TELEGRAM_MODE (webhook or poll) to choose how messages arrive. Set NOTESFLOW_TELEGRAM_API to use your own Bot API server. A bot set in the console replaces the environment's.

A workspace's package must include Chat apps.

Setting up Signal (operators, experimental) ​

Signal has no official way for a program to send messages. Notesflow goes through signal-cli-rest-api, which you run yourself with a phone number of its own. It can stop working when Signal changes, and Signal may ban a number it takes for a bot.

  1. Run signal-cli-rest-api in its normal or native mode (not json-rpc, which hands messages out only over a socket), somewhere the Notesflow server can reach.
  2. Register or link a number to it, following its own instructions.
  3. In /admin → Chat apps → Signal, give the bridge's address (such as http://signal-cli:8080) and the number with its country code, and press Try and save. Notesflow asks the bridge whether it answers and has that number, and keeps them only if both.

The server asks the bridge for new messages every few seconds; run one server that asks. The environment can set the bridge instead: NOTESFLOW_SIGNAL_URL and NOTESFLOW_SIGNAL_NUMBER. A bridge set in the console replaces the environment's.

Setting up WhatsApp (workspace admins) ​

WhatsApp is never the deployment's: a workspace that wants it brings its own WhatsApp Business account and pays Meta for its messages. It needs the Decide what notices say in chat apps permission and a package that includes Chat apps.

  1. In Meta's developer console, make an app with WhatsApp, and note the phone number id (not the number), a permanent access token, and the app's app secret.
  2. In the workspace's console → WhatsApp, give the three and press Try and save. Notesflow asks Meta whose number it is and keeps them, sealed, only if Meta answers.
  3. In Meta's app, set the webhook to the address the console shows, with its verify token, and subscribe it to messages. Meta needs an https address it can reach, so the API's NOTESFLOW_API_URL must be public.
  4. Optionally, have Meta approve a template (category Utility) whose body takes one parameter, such as Notesflow: 1 Reply 1 to mark it read., and give its name and language.

WhatsApp lets a business write freely only within 24 hours of the person writing to it. Inside them a notice comes with Done and Mark read buttons. Outside them it goes as the template, or, with no template, not at all: it stays in the person's inbox. Removing the account disconnects everybody's WhatsApp in this workspace.

What a message says (workspace admins) ​

Telegram's and Meta's servers read everything a bot or a business sends; nobody between the two ends reads a Signal message. So each workspace decides, in its console and for each app, how many words go there (this needs the Decide what notices say in chat apps permission):

SettingA message says
Just a linkThat there is something new, and a link
Who, and which page (Telegram's and WhatsApp's default)Who did what, on which page; never what a page or comment says
Who, which page, and what was said (Signal's default)Also the words: the comment, the task, the step

People may choose fewer for themselves, never more. A message about a page somebody can no longer read says only that there is something. Links in messages go to Notesflow, which checks what the reader may see every time.

Replies, and sign-in rules ​

A connected chat may only:

  • mark a notice read;
  • tick the step a your step is next notice is about;
  • save a message in today's journal.

Telegram and WhatsApp have buttons for the first two. Signal has none, so a Signal notice ends Reply 1 to mark it read (and 2 to tick the step). A reply that quotes a notice answers that one; otherwise it answers the newest notice of the last day; the same numbers work on WhatsApp. Each chat account may send 30 messages in ten minutes; past that, nothing is answered.

Nothing is read back into the chat: there is no search and no page text on request. In a workspace that requires two-step sign-in or its own single sign-on, all replies are refused, because a chat app is neither.

Connecting (everybody) ​

In Settings → Notifications → Telegram, press Connect Telegram and open the link within ten minutes. It works once, from your own Telegram account. Notices then arrive within the hours you set under When your phone may interrupt you, counted with your phone against the day's reminders. Send /stop to the bot, or press Disconnect, to stop.

For Signal, press Connect Signal in the same place. It shows a message such as link K7QM4TZB and the deployment's number: send that message to that number from your own Signal within ten minutes. Send stop, or press Disconnect, to stop.

Where the workspace has WhatsApp, press Connect WhatsApp and open the link: it fills in the message to send to the workspace's number. WhatsApp is connected for that workspace only.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.