Access, groups and delivery

These rules and settings apply to every channel type. Each platform's own page covers its setup.

Who may talk to the bot#

allow_from lists the sender ids allowed to talk. Ids depend on the platform: a numeric Telegram user id, a phone number without + for WhatsApp, an email address for email. Each channel page says which.

Direct messages from anyone else get a pairing code:

Hi! I don't recognise you yet. To get access, ask my owner to run: habakkuk pair 4KX9QT. The code works for one hour.

habakkuk pair 4KX9QT

The sender may talk from then on. /whoami in a chat shows who you are to the bot and how you got access.

Approvals and clarifying questions are answered only by allowed senders. A whatsappagent channel only ever hears from the person who created the agent, so its sender is always treated as the owner.

Groups#

In groups the bot answers only when addressed. groups sets the rule per channel:

What counts as addressed depends on the platform; see the table below.

Settings every channel takes#

Platforms that need more settings take them in a block named after the type (email:, sms:, msteams: and so on).

What a chat shows while the agent works#

A turn that runs past 8 seconds shows that it is working. progress sets how:

The plain line never shows a tool name, a command, a path, an id or JSON. It says what kind of work is going on:

After about 20 seconds the line also says how long the turn has run: Working on it… (40s), then (2 min). These lines are translated into every supported language.

Only Telegram and Slack can edit a message. On every other platform plain and detailed show what off shows: the typing indicator where there is one, or one "still working" notice after a minute. The terminal, the terminal UI and the dashboard always show each step.

Approval requests in plain words#

When the agent needs your approval in a chat, it says what it wants to do in everyday words, why it is asking, and how to answer:

I'd like to add a note to decisions.md in your Corner Bakery workspace.
I'm asking because this conversation included a web page or email, and I check with you before acting on those.

Reply yes or no. Reply details to see the exact command.

• The first line comes from the tool call itself, with no model involved, so the same call always reads the same. A shell command is named only when it is one simple step, such as adding to a file, deleting one, git push or contacting a website. Anything longer reads as "I'd like to run a command on your computer", so the line never says less than the command does.
• The second line is there when the reason is more than the permission mode: the turn read outside content, the request came from a chat, the tool always asks, or the reviewer was unsure.
• Reply details to see the exact command or call, with secrets removed and long calls cut short. The approval keeps waiting.
• approvals_detail: full puts the exact call in every request, in a code block. The local web chat does this by default.

Platforms with buttons show Approve and Deny as well. Permissions and approvals covers who may answer and what happens across a restart.

Changing these without a restart#

progress and approvals_detail can be changed while habakkuk serve runs. The change applies from the next message, with no restart. Every way below edits config.yaml in place: comments stay, and the previous file is kept as config.yaml.bak.

• Dashboard. The Config page has two controls for each chat channel: "While working, show" and "Approval requests show".
• In the chat. /progress plain|detailed|off and /approvals summary|full change the channel you are writing in. With no argument they show the current setting. Only the owner can use them.
• Terminal. habakkuk setup channel NAME -progress plain -approvals-detail summary. NAME is the channel's name under channels:, or its type when you have only one of that type.
• By hand. Edit config.yaml; serve notices within a few seconds.

Every other channel setting still needs a restart, and the log says so.

Webhook channels#

Webhook channels (sms, msteams, googlechat, bluebubbles, line, whatsappcloud, messenger, instagram, feishu, dingtalk, wecom, nextcloudtalk) receive at <public_url>/channels/<name>, where <name> is the account name. habakkuk doctor prints each URL. Every request is checked against the platform's signature or signed token, so these paths need no API token, but the platform must reach the server:

http:
  listen: 127.0.0.1:8484
  public_url: https://habakkuk.example.com     # a reverse proxy or tunnel to listen

Remote access shows how to put a proxy or tunnel in front.

Adapter state that the platform cannot give back (where a mailbox was read up to, Teams service URLs, the last ntfy message) is kept in $HABAKKUK_HOME/channels/<type>-<name>.json.

How delivery works#

• Exactly once where it matters. A turn's job ID is derived from the platform message ID, so a redelivered message never runs twice. A finished turn enqueues a delivery job with an ID derived from the turn, so a turn that reruns after a crash does not reply twice. A delivery records each chunk it sends, so a retry resumes at the first unsent chunk.
• Attachments. Photos, files and voice notes are downloaded (up to 25 MB), stored as blobs and copied to the agent's workspace/inbox/ so tools can open them. Images and PDFs also go to the model directly. Voice notes are transcribed through the transcription: provider.
• Sending files. Agents send files with the send_file tool, within each platform's limits.
• Replies arrive whole. Text is not streamed into the chat as it is written. A long turn shows progress instead: one short line that changes as the work moves on, a typing indicator, or a "still working" notice. See above.
• Supervision. Every adapter runs under a supervisor that restarts it with backoff and tears down a connection that stays silent past its limit.

Architecture: channels has the details.

Replies and quotes#

When you reply to a specific message, the agent sees the quoted text before what you typed:

[Replying to you: "Tests pass. Merge it?"]
yes

"you" means the agent's own message; otherwise it names the person, or says "an earlier message" when the platform does not. The quote is cut to 500 characters, and a photo, file or voice note without text shows as (photo), (file NAME) or (voice note).

Messages a chat got from outside its own conversation, such as a scheduled task's result, are covered in Sessions.

Sending without a turn#

habakkuk send -to CHANNEL:CHAT[:THREAD] [-file PATH] TEXT

habakkuk send queues a message or file to a chat as a delivery job, without running a turn; habakkuk serve sends it. Schedules, board cards and an agent's home chat use the same CHANNEL:CHAT[:THREAD] form. The agent that answers the chat sees what was sent on the next message there.

What each platform supports#

Every platform takes a typed yes or no for an approval. Platforms with buttons show Approve and Deny too.