MeshAgent WhatsApp

WhatsApp Cloud API channel support for MeshAgent process agents.

This package exports WhatsAppChannel and create_channel(...) for use with a MeshAgent process channel shim.

The channel turns validated WhatsApp webhook queue messages into trusted MeshAgent user turns and sends completed agent responses through the WhatsApp Cloud API. Incoming webhooks extract text messages, inbound media messages, and interactive button/list replies, while status updates are exposed to an overridable channel hook.

Inbound WhatsApp media is downloaded by media ID, written to room storage under .threads/whatsapp-media by default, and passed to the agent turn as room:///... file content next to the text/caption. Downloads are capped by MESHAGENT_WHATSAPP_INBOUND_MEDIA_MAX_BYTES, which defaults to 25000000; oversized media is skipped and represented as text in the agent turn.

Set MESHAGENT_WHATSAPP_ALLOWED_FROM_NUMBERS to a comma-separated phone number allowlist to process inbound messages and send outbound messages only for those WhatsApp numbers. Numbers are matched by digits, so formatted and unformatted versions of the same number are equivalent.

Text responses are sent as WhatsApp text messages. File attachments emitted by the agent with attach_file are sent as WhatsApp media messages when they are HTTP(S) URLs, or when room:///... storage URLs can be resolved through room.storage.download_url(path=...). Agent-generated image events are uploaded to WhatsApp Cloud API as binary media and sent by media ID. Base64/data URL room files are decoded before upload.

The package also exports Cloud API helpers for read receipts with typing indicators, interactive reply buttons, interactive list messages, generic templates, image-header templates, limited-time-offer templates, media-card carousel templates, media ID messages, and media upload/download/delete.