Link WhatsApp with a pairing code

[onechat] / README.rst

diff --git a/README.rst b/README.rst
index c94f226192c24ddecad6a899d3e16d3b4c7f3dc7..fd6cb95b67e99124f6b6254fb51f2d7bf9b10a77 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -105,7 +105,10 @@ its tool calls, and a finished one goes on from its log, and its reply
 comes back in the same way. When the user stops a subagent, the chat
 gets a note, and the report of the subagent is logged, but it starts no
 turn. Each model call of a subagent has the name in the ``agent`` field
-of ``agent/usage.jsonl``.
+of ``agent/usage.jsonl``. ``agent/work.json`` holds the names of the
+running subagents. A subagent that runs when the daemon stops goes on at
+the next start: the chat gets the note that the daemon restarted, and
+the subagent gets the same note and goes on from its log.
 
 ``agent/config.json`` holds the settings of the agent. The first start
 writes it with the defaults and a random ID. Do not change the ID: the
@@ -169,6 +172,50 @@ write of a message can make the message repeat once. A network failure
 or a rate limit makes the bot wait and try again, and does not stop the
 daemon.
 
+**********
+ WhatsApp
+**********
+
+The daemon connects to the WhatsApp account of the user as a linked
+device. The terminal client and Telegram take three commands:
+
+``/whatsapp pair PHONE``
+   Links the account of PHONE, the number with its country code, such as
+   ``+15550001111``. The daemon answers with the steps and then with a
+   pairing code in its own message: in WhatsApp on the phone, open
+   Linked devices, tap Link a device, then tap Link with phone number
+   instead, and enter the code. The code expires in about 2 minutes, and
+   the same command gives a new code. When the link succeeds, the daemon
+   answers with the linked number.
+
+``/whatsapp status``
+   Shows the link: not linked, linked and connected, or linked and
+   disconnected, with the times of the connection.
+
+``/whatsapp unlink``
+   Ends the link and deletes the session. When WhatsApp is disconnected,
+   the phone does not get the logout, so remove the device in Linked
+   devices on the phone.
+
+The answers go only to the client that asked, and the commands do not go
+to the agent, so the agent never gets the phone number or the code. The
+chat gets only the notes that WhatsApp is linked or unlinked.
+
+The session is ``whatsapp/session.db`` in the data directory, with mode
+0600 in a directory with mode 0700. It gives full access to the WhatsApp
+account, so the daemon refuses the file when its mode is not 0600. The
+shell of the agent runs as the user, so it can read the session. If the
+session leaks, remove the linked device in WhatsApp on the phone, and
+the session stops working. Without the file, WhatsApp is not linked.
+
+When the session holds a linked device, the daemon connects at its
+start, and after a network failure it connects again by itself. When a
+disconnection lasts 10 minutes, all clients get one notice, and one more
+when the connection comes back. When WhatsApp ends the connection for
+good, for example because another program uses the same session, all
+clients get a notice at once. When the user removes the device in the
+phone, the daemon deletes the session and tells all clients one time.
+
 *******
  Probe
 *******