Messenger Agent¶
Thinklio Built-in Agent Specification Version 0.1 | March 2026
1. Purpose and Problem Statement¶
The Messenger Agent monitors and interacts with external messaging platforms — SMS, WhatsApp, Telegram, Signal, Slack, and others — through a unified interface. It gives users a single place to track incoming messages across platforms, surfaces what needs attention, drafts responses, and (within governance limits) sends autonomously.
The fragmentation problem it addresses is real: a person managing relationships across SMS, WhatsApp, and a team Slack channel has no unified view of what's arrived, what needs a reply, and what can wait. The Messenger Agent aggregates this into a coherent, prioritised view while keeping the user firmly in control of what goes out.
Governance: The Messenger Agent follows the shared governance model defined in 00-governance-model.md. Sending on any platform is a governed action. The governance model is applied per-platform, not globally — a user may permit autonomous SMS replies to Rolodex-matched contacts while requiring approval for all WhatsApp messages.
2. UI Structure¶
Chat Tab¶
Natural language access: - "Any messages I need to deal with today?" - "Draft a reply to Lee Anne's WhatsApp — tell her I'll be home by 7" - "What did Marcus say on Slack yesterday?" - "Send a text to the Cares Communities board number — confirm the meeting is at 10am"
Inbox Tab¶
A unified message feed across all connected platforms, sorted by recency with agent-applied priority grouping: - Needs reply — messages the agent has identified as requiring a response - Conversations — active threads not yet requiring action - Notifications — platform notifications (mention alerts, system messages, etc.)
Each item shows: platform icon, sender name (linked to Rolodex where matched), message preview, timestamp, and priority indicator.
Platforms Tab¶
Connected messaging platforms. Each platform shows connection status, authentication method, and per-platform permission configuration (the governance matrix applied specifically to that platform). Add/remove platforms.
Rules Tab¶
Routing rules for inbound messages, equivalent in structure to the Mail Agent's Rules tab. Conditions based on platform, sender, content; actions include create task, create item, log interaction, notify, or route to Enquiry Agent.
3. Configuration¶
3.1 Admin Configuration¶
| Setting | Description |
|---|---|
| Permitted platforms | Which messaging platforms can be connected in this workspace |
| Default permission matrix | Default per-action, per-platform permission levels for new users |
| Autonomous send constraints | Hard limits: volume per day, permitted senders, platform restrictions |
3.2 Permission Matrix (per-platform, configurable at org → team → user)¶
| Action | Permission Level |
|---|---|
| Read messages | read |
| Draft reply | draft |
| Send — Rolodex-matched sender | configurable |
| Send — unknown sender | configurable |
| Send — group/channel | configurable |
3.3 Platform Connection¶
Each platform uses its own authentication mechanism:
| Platform | Auth Method |
|---|---|
| SMS | Twilio or carrier gateway; API key in Keeper |
| WhatsApp Business API; credentials in Keeper | |
| Telegram | Bot API token or user session; in Keeper |
| Signal | Signal CLI or third-party bridge; in Keeper |
| Slack | OAuth via workspace integration; token in Keeper |
| Others | Platform-specific; credentials in Keeper |
All credentials are managed through Keeper. The Messenger Agent never holds raw credentials.
4. Message Intelligence¶
When reading messages, the agent applies:
- Sender matching — cross-referencing phone numbers, usernames, and display names against Rolodex to identify known contacts
- Priority scoring — based on sender relationship strength, message content signals (questions, urgency language, deadlines), and platform (some users will weight SMS higher than Slack)
- Action detection — identifying messages that contain a request or require a response
- Thread context — maintaining awareness of conversation history to contextualise new messages correctly
The unified inbox summary follows the same pattern as the Mail Agent:
MessengerSummary
├── unread_count integer (total, and per-platform breakdown)
├── needs_reply[]
│ ├── platform string
│ ├── sender string
│ ├── sender_person_id UUID | null
│ ├── preview string
│ ├── urgency enum
│ └── suggested_reply string | null
├── conversations[] (active but no action needed)
└── digest string (natural language summary)
5. Agent Capabilities¶
| Capability | Description |
|---|---|
| Read messages | Retrieve messages from connected platforms |
| Summarise inbox | Natural language summary across platforms |
| Draft reply | Compose a reply without sending |
| Send message | Send on a platform, subject to governance |
| Search messages | Search by sender, platform, keyword, date |
| Log interaction | Create a Rolodex Interaction record from a message thread |
| Create task | Create a Taskmaster task from a message |
| Route to Enquiry | Send an inbound message to the Enquiry Agent as a new Item |
6. Inter-Agent Behaviour¶
- Keeper provides all platform credentials via proxy
- Rolodex is queried to match senders to Person records and log message interactions
- Taskmaster receives tasks created from messages
- Enquiry Agent receives routed inbound messages as Items
- Mail Agent — in unified summary mode, the Mail Agent and Messenger Agent can contribute to a combined "communications" summary across all channels
7. Platform-Specific Notes¶
SMS and WhatsApp: Both are high-sensitivity channels. The governance defaults should be conservative — draft by default, with send_with_approval required before autonomous send is enabled. Users should be explicitly walked through the implications during onboarding.
Slack: Team-channel messages introduce a multi-recipient context that requires additional care. Autonomous send to a Slack channel should be off by default regardless of org settings, given the broadcast nature.
Signal: Signal's architecture makes programmatic access more complex. Integration may require a self-hosted bridge (e.g. signal-cli). This is a phase-two platform.
Platform availability: Not all platforms will be available at launch. The Platforms tab should clearly communicate which platforms are supported, which are coming soon, and which require self-hosted infrastructure.
8. Use Cases¶
UC-1: Morning message check¶
A user asks "any messages needing a reply?" The agent returns a summary: two WhatsApp messages (one from a known contact with a meeting query, one from an unknown number), one SMS from a client, and three Slack mentions. The client SMS is flagged as highest priority.
UC-2: Quick reply via chat¶
A user says "reply to Lee Anne's WhatsApp — I'll call her at 6." The agent drafts the message, shows it for confirmation (or sends autonomously if permission allows), and logs the interaction in Rolodex.
UC-3: Routing inbound support WhatsApp¶
A rule is configured: WhatsApp messages to the business number → create Enquiry Agent Item (type: enquiry). Inbound WhatsApp enquiries are automatically converted to tracked Items.
UC-4: Cross-platform search¶
A user asks "what did Marcus say about the invoice? I think it was on Slack or WhatsApp." The agent searches across both platforms and returns the relevant message thread with date and context.
9. Open Questions¶
- Platform API availability varies significantly by region and account type. WhatsApp Business API requires a Meta-approved business account. SMS via Twilio requires number provisioning. How is platform onboarding managed, and what guidance does Thinklio provide?
- Group chat handling (WhatsApp groups, Slack channels) is qualitatively different from one-to-one messaging. The initial spec treats them as readable but not autonomously writable. Is this the right default?
- Message content, like email content, raises storage questions. Should the Messenger Agent query platforms on demand or maintain a local cache? Caching enables faster search and offline access but introduces data residency considerations.
- Read receipts on some platforms reveal to the sender that a message has been read. Should the agent read messages on behalf of the user without triggering read receipts where possible?
Previous: Calendar Agent | Next: Enquiry Agent