Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
WhatsApp Send (whatsappSend)
| Field | Value |
|---|---|
| Category | whatsapp / tool (dual-purpose) |
| Backend handler | server/nodes/whatsapp/whatsapp_send.py (WhatsAppSendNode); dispatched via BaseNode.execute() -> @Operation("send"), which delegates to server/nodes/whatsapp/_base.py::handle_whatsapp_send |
| Tests | server/tests/nodes/test_whatsapp.py |
| Skill (if any) | server/skills/social_agent/whatsapp-send-skill/SKILL.md |
| Dual-purpose tool | yes - tool name whatsapp_send |
Purpose
Send WhatsApp messages of any supported type (text, image, video, audio,
document, sticker, location, contact) to an individual phone number, a group
JID, a newsletter channel JID, or the connected account itself ("self" - used
for notes-to-self). All traffic is proxied through the Go whatsapp-rpc
service over a persistent WebSocket RPC (not HTTP). Also works as an AI agent
tool when wired to an agent's input-tools handle.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data for template substitution into message, media_url, etc. |
Parameters
Key parameters (see frontend definition for the full list and displayOptions.show rules):
| Name | Type | Default | Required | Notes |
|---|---|---|---|---|
recipient_type |
options | self |
no | One of self, phone, group, channel |
phone |
string | "" |
conditional | Required when recipient_type == 'phone' |
group_id |
string | "" |
conditional | Required when recipient_type == 'group' |
channel_jid |
string | "" |
conditional | Required when recipient_type == 'channel', must end @newsletter |
message_type |
options | text |
yes | text, image, video, audio, document, sticker, location, contact |
message |
string | "" |
conditional | Required when message_type == 'text' |
format_markdown |
boolean | true |
no | When true and text message, convert GFM to WhatsApp syntax via markdown_formatter.to_whatsapp |
media_source |
options | base64 |
conditional | base64, file, or url for media types |
media_data |
string | "" |
conditional | Base64 data when media_source == 'base64' |
file_path |
string/object | "" |
conditional | A file in this workflow's workspace (a path or a file reference, read through coerce_file_param), or an upload dict {type: 'upload', filename, mimeType}. A path outside the workspace is refused |
media_url |
string | "" |
conditional | URL when media_source == 'url'. Checked with services/netpolicy.py on every address it resolves to before the download: cloud metadata and OpenCompany's own ports are refused |
mime_type |
string | "" |
no | Optional override |
caption |
string | "" |
no | Caption for media messages |
filename |
string | "" |
no | Filename for document messages |
latitude |
number | 0 |
conditional | Required for message_type == 'location' |
longitude |
number | 0 |
conditional | Required for message_type == 'location' |
location_name |
string | "" |
no | Location name |
address |
string | "" |
no | Location address |
contact_name |
string | "" |
conditional | Required for message_type == 'contact' |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | The handler result dict (see below). The plugin Output model is WhatsAppSendOutput (message_id, sent, extra="allow"). |
When wired into an AI agent's input-tools handle (usable_as_tool=True, tool name whatsapp_send) the same result payload is returned to the LLM.
Output payload
{
status: 'sent';
recipient: string; // 'self' | phone | group_id | channel_jid
recipient_type: 'self' | 'phone' | 'group' | 'channel';
message_type: string;
timestamp: string; // ISO
preview?: string; // text messages (first 100 chars)
media_source?: string; // media types
caption?: string;
filename?: string;
mime_type?: string;
uploaded_file?: string; // when file_path is an upload dict
location?: { latitude, longitude, name, address };
contact_name?: string;
}
Logic Flow
flowchart TD
A[handle_whatsapp_send] --> B{recipient_type}
B -- self --> R[recipient = 'self']
B -- channel --> C{channel_jid set?}
C -- no --> Eret[success=false<br/>Channel JID required]
C -- yes --> C2{message_type in<br/>text/image/video/audio/document?}
C2 -- no --> Eret2[success=false<br/>Channels only support: ...]
C2 -- yes --> R
B -- group --> G{group_id set?}
G -- no --> Eret3[success=false<br/>Group ID required]
G -- yes --> R
B -- phone --> P{phone set?}
P -- no --> Eret4[success=false<br/>Phone number required]
P -- yes --> R
R --> T{message_type == 'text'?}
T -- yes --> T1{message non-empty?}
T1 -- no --> Eret5[success=false<br/>Message content required]
T1 -- yes --> T2{format_markdown?}
T2 -- yes --> T3[parameters.message =<br/>to_whatsapp message]
T2 -- no --> S
T3 --> S
T -- no --> S
S[await nodes.whatsapp._service.handle_whatsapp_send params] --> S2{data.success?}
S2 -- no --> Eret6[success=false<br/>error from RPC]
S2 -- yes --> F[Build result dict with<br/>status/recipient/type-specific fields]
F --> OK[success=true]
Decision Logic
- Validation (short-circuit) - raised as
ValueErrorand caught by the outertry, turned into asuccess=falseenvelope:channel_jidmissing whenrecipient_type == 'channel'- Channel message type not in
{text, image, video, audio, document}- specifically blockssticker,location,contactfor channels group_idmissing whenrecipient_type == 'group'phonemissing whenrecipient_type == 'phone'- Empty
messagewhenmessage_type == 'text'
- Markdown transform: only runs when
message_type == 'text'ANDformat_markdowntruthy. Overwritesparameters['message']in place before RPC call. - Type-specific result fields:
match message_typeaddspreview,media_source,caption,filename,mime_type,uploaded_file,location, orcontact_namebased on message type. - File upload detection: if
file_pathis a dict withtype == 'upload', the_service.pysend handler uploads bytes and the result includesuploaded_fileandmime_typefrom the upload dict. - File containment: any other
file_pathis read withcoerce_file_paramfrom the workflow's workspace (the node passes itsNodeContext). A path outside it, or a caller with no workspace (thewhatsapp_sendWebSocket command), gets asuccess=falseenvelope; nothing is read.
Side Effects
- Database writes: none directly from this handler. (API-usage cost is recorded by the
@Operationcostmetadata viaBaseNode.execute().) - Broadcasts: none directly - standard node_status transitions come from
BaseNode.execute(). - External calls: WebSocket RPC to the Go
whatsapp-rpcservice vianodes/whatsapp/_service.py::whatsapp_rpc_call. Default URLws://localhost:5683/ws/rpc(overridable viaWHATSAPP_RPC_URL). For media URLs,_service.pyadditionally downloads viahttpx, afternetpolicy.resolved_url_block_reasonaccepts the URL (fetch_policy: the owner's network is allowed, cloud metadata and OpenCompany's own ports never). - File I/O: none in this handler - file uploads are handled in
_service.py. - Subprocess: none.
External Dependencies
- Credentials: none at the node handler level. Pairing state is owned by the Go service; the handler is credential-free.
- Services:
whatsapp-rpc(Go) on port 5683 (default).services.markdown_formatter.to_whatsappwhenformat_markdownis enabled. - Python packages:
asyncio. (httpxis used inside_service.pyfor URL media fetches.) - Environment variables:
WHATSAPP_RPC_URL(optional, defaultws://localhost:5683/ws/rpc).
Edge cases & known limits
- Channel message-type allowlist is hard-coded:
{text, image, video, audio, document}. Any other type returnssuccess=falseeven though the RPC might technically accept it. format_markdownmutatesparameters: the converted text overwrites the incomingmessagebefore the RPC call - downstream code inspecting the raw parameters post-execution will see the converted form.- All exceptions funnel to
success=false: the outertry/exceptcaptures everyValueError, RPC exception, and generic failure, returning the stringified error as the envelopeerror. The handler never raises to the executor. recipient = 'self'is a sentinel string, not a resolved phone number. The Go RPC resolves it to the connected account at send time.- Caption/filename/mime_type: only added to the result payload when truthy in
parameters; consumers must handle their absence. - Text preview is truncated to 100 chars with
"..."suffix when longer - this is output-only and does not change the sent message.
Related
- Skills using this as a tool:
whatsapp-send-skill/SKILL.md - Companion nodes:
whatsappDb,whatsappReceive - Architecture docs: Markdown Formatter (see "Markdown Formatter Service"), WhatsApp RPC via
nodes/whatsapp/_service.py