Self-improving AI Employees for everyone
WhatsApp DB (whatsappDb)
| Field | Value |
|---|---|
| Category | whatsapp / tool (dual-purpose) |
| Backend handler | server/nodes/whatsapp/whatsapp_db.py (WhatsAppDbNode); dispatched via BaseNode.execute() -> @Operation("query"), which delegates to server/nodes/whatsapp/_base.py::handle_whatsapp_db |
| Tests | server/tests/nodes/test_whatsapp.py |
| Skill (if any) | server/skills/social_agent/whatsapp-db-skill/SKILL.md |
| Dual-purpose tool | yes - tool name whatsapp_db |
Purpose
Query and operate on the WhatsApp state owned by the Go whatsapp-rpc service:
chat/message history, contacts, groups, and newsletter channels (list, info,
messages, stats, follow/unfollow, create, mute, mark-viewed, react, live
updates, profile pictures). One node, 18 operations switched via the
operation parameter. Also works as an AI agent tool.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Template source for operation parameters |
Parameters
The top-level parameter is operation. Each operation takes its own subset of
parameters, all rendered conditionally via displayOptions.show in the
frontend.
operation enum
| Operation | Required params | Optional params | RPC method |
|---|---|---|---|
chat_history |
chat_type + (phone | group_id) |
group_filter, sender_phone, message_filter, limit, offset, include_media_data |
chat_history (router) |
search_groups |
- | query, limit |
groups |
get_group_info |
group_id_for_info or group_id |
participant_limit |
group_info |
get_contact_info |
contact_phone or phone |
- | contact_info |
list_contacts |
- | query, limit |
contacts |
check_contacts |
phones (comma-separated) |
- | contact_check |
list_channels |
- | refresh, limit |
newsletters |
get_channel_info |
channel_jid (JID or invite link) |
refresh |
newsletter_info |
channel_messages |
channel_jid |
channel_count, before_server_id, message_offset, since, until, media_type, search, refresh, include_media_data |
newsletter_messages |
channel_stats |
channel_jid |
channel_count |
newsletter_stats |
channel_follow |
channel_jid |
- | newsletter_follow |
channel_unfollow |
channel_jid |
- | newsletter_unfollow |
channel_create |
channel_name |
channel_description, picture |
newsletter_create |
channel_mute |
channel_jid |
mute (bool, default true) |
newsletter_mute |
channel_mark_viewed |
channel_jid, server_ids (comma list) |
- | newsletter_mark_viewed |
newsletter_react |
channel_jid, react_server_id |
reaction (emoji) |
newsletter_react |
newsletter_live_updates |
channel_jid, server_ids |
- | newsletter_live_updates |
contact_profile_pic |
profile_pic_jid or phone |
preview |
contact_profile_pic |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | The handler result dict with operation field + operation-specific fields. Plugin Output model is WhatsAppDbOutput (operation, messages, contacts, groups, channels, total, extra="allow"). |
When wired into an AI agent's input-tools handle (usable_as_tool=True, tool name whatsapp_db) the same payload is returned to the LLM.
All payloads include the read-back operation and timestamp. Collection
operations (search_groups, list_contacts, list_channels) apply a soft
limit and return total / returned / has_more plus a human-readable
hint if truncated.
Logic Flow
flowchart TD
A[handle_whatsapp_db] --> B{operation?}
B -- chat_history --> CH[_handle_chat_history]
B -- search_groups --> SG[_handle_search_groups]
B -- get_group_info --> GGI[_handle_get_group_info]
B -- get_contact_info --> GCI[_handle_get_contact_info]
B -- list_contacts --> LC[_handle_list_contacts]
B -- check_contacts --> CC[_handle_check_contacts]
B -- list_channels --> LCH[_handle_list_channels]
B -- get_channel_info --> GCHI[_handle_get_channel_info]
B -- channel_messages --> CM[_handle_channel_messages]
B -- channel_stats --> CS[_handle_channel_stats]
B -- channel_follow --> CF[_handle_channel_follow]
B -- channel_unfollow --> CU[_handle_channel_unfollow]
B -- channel_create --> CC2[_handle_channel_create]
B -- channel_mute --> CMU[_handle_channel_mute]
B -- channel_mark_viewed --> CMV[_handle_channel_mark_viewed]
B -- newsletter_react --> NR[_handle_newsletter_react]
B -- newsletter_live_updates --> NLU[_handle_newsletter_live_updates]
B -- contact_profile_pic --> CPP[_handle_contact_profile_pic]
B -- unknown --> Eret[raise ValueError<br/>Unknown operation: X]
CH --> V1{validate params}
V1 -- missing --> Eret
V1 -- ok --> X1[await whatsapp_chat_history_handler]
X1 -- success=false --> Eret
X1 -- ok --> MAY{include_media_data?}
MAY -- yes --> MED[_enrich_messages_with_media<br/>semaphore=5, parallel gather]
MAY -- no --> OUT
MED --> OUT[Return envelope]
SG --> OTHERS[... similar pattern for each op:<br/>validate, whatsapp_rpc_call,<br/>raise-on-error, limit+shape result]
OTHERS --> OUT
Eret -.-> EE[Outer try/except<br/>returns success=false envelope<br/>with str error]
Decision Logic
- Operation dispatch: single
if/elifchain; unknown operation raisesValueErrorcaptured by the outertry/except. - Invite link vs JID resolution for channel ops:
_resolve_channel_identifier(value): returns{'invite': url}if value starts withhttp://orhttps://, else{'jid': value}. Used where the RPC accepts either (newsletter_info,newsletter_stats)._resolve_to_jid(value, rpc_call): if value is an invite link, callsnewsletter_infofirst to look up the JID, then returns that JID. Used where the RPC only acceptsjid(newsletter_messages,newsletter_follow,newsletter_unfollow,newsletter_mute,newsletter_mark_viewed,newsletter_react,newsletter_live_updates). RaisesValueErrorif lookup fails.
- Result truncation for LLM safety (prevents context overflow):
search_groups: returns only{jid, name}per group, defaultlimit=20get_group_info: returns only{phone, name, is_admin}per participant, defaultparticipant_limit=50list_contacts: returns only{phone, name, jid}, defaultlimit=50list_channels: returns only{jid, name, subscriber_count}, defaultlimit=20
- Media enrichment (
include_media_data=true):- Filters
messagesto those whosemessage_type(ortype) is in{image, video, audio, document, sticker}- theMEDIA_MESSAGE_TYPESfrozenset. - Runs
_enrich_messages_with_mediawithasyncio.Semaphore(5)andasyncio.gather(..., return_exceptions=True)- per-message failures are swallowed intomedia_errorrather than propagating. - Each message mutated in place:
media_data(base64) andmedia_mime_typeon success,media_erroron failure.
- Filters
- Success flag handling is defensive: many RPC responses are plain lists (e.g.
groups,newsletters,contact_check). The handler accepts bothlist(treated as success) anddict(checkssuccess != False). server_idsparsing:channel_mark_viewedandnewsletter_live_updatesaccept a comma-separated string, split, strip, andint()each token. Non-integer values raiseValueError.
Side Effects
- Database writes: none.
- Broadcasts: none - standard
node_statuscomes fromBaseNode.execute(). - External calls: WebSocket RPC to the Go service (
whatsapp_rpc_callandhandle_whatsapp_chat_historyinnodes/whatsapp/_service.py). Forchannel_messagesandchat_historywithinclude_media_data=true, one additionalmediaRPC call per media message (up to 5 in parallel). - File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services:
whatsapp-rpcGo service (defaultws://localhost:5683/ws/rpc). - Python packages:
asyncio. - Environment variables:
WHATSAPP_RPC_URL.
Edge cases & known limits
- Channel ops silently transform invite links: a user-supplied invite link becomes a JID via an extra
newsletter_inforound-trip in_resolve_to_jid. If that lookup fails, the envelope error isCould not resolve invite link to channel JID: <value>. _enrich_messages_with_mediaswallows per-item errors: failed downloads becomemedia_errorfields, never a failed envelope. The count of failures is not summarised.- Truncation hints are best-effort:
hintis only populated whentotal > limit. Callers must not rely on it being a specific string - only on the truncation itself. search_groupsis client-side filtering: the RPC returns all groups, the handler filters byquery.lower() in group.name.lower()and then truncates. For very large group counts this still pulls the full list from the Go service.- Return shape inconsistency: operations that return
resultmerge it via**resultinto the envelope, which may add unexpected top-level keys if the RPC evolves. - Unknown operation raises in-band; callers get
success=falsewitherror = "Unknown operation: X".
Related
- Skills using this as a tool:
whatsapp-db-skill/SKILL.md - Companion nodes:
whatsappSend,whatsappReceive - Architecture docs:
CLAUDE.md-> "WhatsApp Channel (Newsletter) Architecture" and "WhatsApp Integration" sections