whatsapp-mcp-manual

Stars9

Forks13

UpdatedJuly 19, 2026 at 08:12

Progressive-disclosure usage manual for the WhatsApp Cloud API MCP tool. Read this when you need detail beyond the one-line action descriptions: the 24-hour customer-service window and approved templates, send vs reply vs react, check/read/search, media attachments, contacts/accounts/status basics, the notification transient-hook vs persistent-context split, and external-delivery side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

Lingtai-AI

Lingtai-AI/lingtai-kernel

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

12 files

SKILL.md

readonly

name	whatsapp-mcp-manual
description	Progressive-disclosure usage manual for the WhatsApp Cloud API MCP tool. Read this when you need detail beyond the one-line action descriptions: the 24-hour customer-service window and approved templates, send vs reply vs react, check/read/search, media attachments, contacts/accounts/status basics, the notification transient-hook vs persistent-context split, and external-delivery side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.
version	1.2.0
last_changed_at	2026-07-19T00:00:00Z
related_files	["src/lingtai/mcp_servers/whatsapp/manager.py","src/lingtai/mcp_servers/whatsapp/server.py","src/lingtai/mcp_servers/whatsapp/client.py"]
maintenance	Tracks the MCP server's manager/config behavior; update when the server's setup or API surface changes.

WhatsApp MCP — usage manual (progressive disclosure)

This client uses the official Meta WhatsApp Cloud API only (no WhatsApp Web bridge).

24-HOUR WINDOW / TEMPLATES

WhatsApp Cloud API allows free-form business replies only inside the 24-hour customer-service window (24h since the user's last message). Outside that window you must send an approved message template, not free text.
templates: list approved message templates. Use a template's name + language.code to send outside the window.

RECIPIENTS

Messages target a recipient by to (or wa_id) — the WhatsApp wa_id. Use ids returned by check/read/contacts.

SEND / REPLY / REACT

send (to/wa_id, plus text, media, or template) starts a message. media is an object with type (image/document/audio/video) and the media fields; template is an object requiring name and language.code.
reply threads to a specific message (message_id, then text/media/ template). message_id is the compound account:wa_id:wamid id.
react adds an emoji reaction to a message (message_id, emoji).
For text sends, preview_url=true enables link previews.

READING: check / read / search

check: list recent conversations.
read: read messages from one conversation (wa_id, or a message_id to resolve it; optional limit). mark_read defaults to true — read marks the conversation read on WhatsApp unless you pass mark_read=false.
search: regex search over message text (query).

CONTACTS / ACCOUNTS / STATUS

contacts: list saved contacts. add_contact/remove_contact manage aliases.
accounts: list configured WhatsApp accounts (redacted).
status: connection/health status for an account.

NOTIFICATIONS: TRANSIENT HOOK vs PERSISTENT CONTEXT

Inbound WhatsApp messages surface to the agent in two _meta lanes:
- _meta.agent_meta.notifications.attention.mcp.whatsapp is a compact high-attention hook only — data.message_ids (compound account:wa_id:wamid ids) and dismiss guidance, never message text or routing context.
- _meta.agent_meta.notifications.persistent.mcp.whatsapp carries the durable context: recent conversation messages (bounded text, both directions), sender/chat routing hooks, and per-message comments for the agent's own outgoing messages, truncated text, and non-text/media messages.
The whatsapp tool remains the source of truth. Neither lane marks anything read; use read/check for exact producer state, especially when a persistent message is truncated or is a media placeholder.
Reply on WhatsApp when the message arrived through WhatsApp (reply with the compound message id, or send), respecting the 24-hour window rule above.
After handling, dismiss the transient hook via notification.dismiss_channel("mcp.whatsapp"); the persistent block is context history, not unread state — do not treat its presence as a pending event.

SIDE EFFECTS & ERROR SURFACING

send, reply, and react deliver to real users — external side effects. Confirm recipient and content before sending unsolicited messages, and respect the 24-hour window rule above.
Actions return {'status': 'ok', ...} on success or {'status': 'error', 'error': <message>, 'error_type': ...} on failure (e.g. missing to, invalid template, outside-window free text). Check the status and surface or act on errors rather than assuming delivery.

More from this repository

same repository

lingtai-doctor

Lingtai-AI/lingtai-kernel

Read-only health diagnostics for LingTai agents and bots. Use when an agent appears offline or unreachable, when a machine migration may have left stale MCP/addon command paths, when heartbeat/status/process/notification/log surfaces disagree, or before deciding whether to mail, refresh, CPR, or edit persistent configuration. Includes a bundled doctor.py script for layered local checks without exposing secrets.

2026-07-199

environment-variables

Lingtai-AI/lingtai-kernel

Complete catalogue of environment variables consumed by the LingTai kernel, wrapper, bundled MCPs, adapters, tests, and daemon composition surfaces.

2026-07-199

system-manual

Lingtai-AI/lingtai-kernel

Second-layer router for LingTai's progressive-disclosure operating manuals. Read this when resident substrate/procedures are too compact and you need the right lower reference. Route here for the expanded substrate/runtime model, lifecycle and `system` tool actions, the init.json composition and preset runtime model route, action/procedure discipline and skill routing, tool-result summarization, SQLite/`log.sqlite` trace inspection and trajectory mining, runtime/kernel update checks and nudges, environment variables, goal notifications, molt/memory questions, MCP/addon ownership, collaboration topology, and resident prompt design. The nested catalog below names each reference and its exact trigger.

2026-07-199

lingtai-kernel-dev

Lingtai-AI/lingtai-kernel

Mandatory repository-local development guide for LingTai's Python kernel and runtime. Use this before changing code, architecture documents, tests, packaging, capabilities, adapters, or developer documentation in lingtai-kernel. Routes each task through the exact baseline, the distributed ANATOMY/CONTRACT systems, focused validation, and pull-request safety gates.

2026-07-199

file-manual

Lingtai-AI/lingtai-kernel

Operational guide for LingTai's built-in file tools: read, write, edit, glob, and grep. Use when working with local text files, deciding whether to use file tools versus bash, handling large files, avoiding binary/image misuse, or reading non-UTF-8 text via explicit bash/Python/iconv instead of complicating the core read tool. Covers UTF-8 policy, safe write/edit discipline, search workflows, and examples for GBK/Shift-JIS/Latin-1 conversion.

2026-07-199

lingtai-kernel-anatomy

Lingtai-AI/lingtai-kernel

Router for LingTai's distributed code navigation system. Use this before navigating, creating, or maintaining kernel ANATOMY.md files. The normative anatomy-of-anatomy now lives at the repository-root ANATOMY.md; this skill explains how an agent enters and descends that graph, how it pairs with the distributed CONTRACT.md interface-definition graph, and what to do when code and navigation disagree.

2026-07-199

name	whatsapp-mcp-manual
description	Progressive-disclosure usage manual for the WhatsApp Cloud API MCP tool. Read this when you need detail beyond the one-line action descriptions: the 24-hour customer-service window and approved templates, send vs reply vs react, check/read/search, media attachments, contacts/accounts/status basics, the notification transient-hook vs persistent-context split, and external-delivery side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.
version	1.2.0
last_changed_at	2026-07-19T00:00:00Z
related_files	["src/lingtai/mcp_servers/whatsapp/manager.py","src/lingtai/mcp_servers/whatsapp/server.py","src/lingtai/mcp_servers/whatsapp/client.py"]
maintenance	Tracks the MCP server's manager/config behavior; update when the server's setup or API surface changes.

WhatsApp MCP — usage manual (progressive disclosure)

This client uses the official Meta WhatsApp Cloud API only (no WhatsApp Web bridge).

24-HOUR WINDOW / TEMPLATES

WhatsApp Cloud API allows free-form business replies only inside the 24-hour customer-service window (24h since the user's last message). Outside that window you must send an approved message template, not free text.
templates: list approved message templates. Use a template's name + language.code to send outside the window.

RECIPIENTS

Messages target a recipient by to (or wa_id) — the WhatsApp wa_id. Use ids returned by check/read/contacts.

SEND / REPLY / REACT

send (to/wa_id, plus text, media, or template) starts a message. media is an object with type (image/document/audio/video) and the media fields; template is an object requiring name and language.code.
reply threads to a specific message (message_id, then text/media/ template). message_id is the compound account:wa_id:wamid id.
react adds an emoji reaction to a message (message_id, emoji).
For text sends, preview_url=true enables link previews.

READING: check / read / search

check: list recent conversations.
read: read messages from one conversation (wa_id, or a message_id to resolve it; optional limit). mark_read defaults to true — read marks the conversation read on WhatsApp unless you pass mark_read=false.
search: regex search over message text (query).

CONTACTS / ACCOUNTS / STATUS

contacts: list saved contacts. add_contact/remove_contact manage aliases.
accounts: list configured WhatsApp accounts (redacted).
status: connection/health status for an account.

NOTIFICATIONS: TRANSIENT HOOK vs PERSISTENT CONTEXT

Inbound WhatsApp messages surface to the agent in two _meta lanes:
- _meta.agent_meta.notifications.attention.mcp.whatsapp is a compact high-attention hook only — data.message_ids (compound account:wa_id:wamid ids) and dismiss guidance, never message text or routing context.
- _meta.agent_meta.notifications.persistent.mcp.whatsapp carries the durable context: recent conversation messages (bounded text, both directions), sender/chat routing hooks, and per-message comments for the agent's own outgoing messages, truncated text, and non-text/media messages.
The whatsapp tool remains the source of truth. Neither lane marks anything read; use read/check for exact producer state, especially when a persistent message is truncated or is a media placeholder.
Reply on WhatsApp when the message arrived through WhatsApp (reply with the compound message id, or send), respecting the 24-hour window rule above.
After handling, dismiss the transient hook via notification.dismiss_channel("mcp.whatsapp"); the persistent block is context history, not unread state — do not treat its presence as a pending event.

SIDE EFFECTS & ERROR SURFACING

send, reply, and react deliver to real users — external side effects. Confirm recipient and content before sending unsolicited messages, and respect the 24-hour window rule above.
Actions return {'status': 'ok', ...} on success or {'status': 'error', 'error': <message>, 'error_type': ...} on failure (e.g. missing to, invalid template, outside-window free text). Check the status and surface or act on errors rather than assuming delivery.