🚀 Services & Messaging Reference

This guide is the complete, 100% technical reference for all services provided by the WhatsApp integration.

---

🏗️ Core Communication

whatsapp.send_message

Sends a plain text message.

Field	Type	Description
target	string	(Required) Recipient phone or Group ID.
message	string	(Required) Text content (supports formatting).
quote	string	Message ID to reply to.
expiration	number	Disappearing message timer (secs).

whatsapp.edit_message / revoke_message

• edit_message: Change the text of a sent message (target, message_id, message).
• revoke_message: “Delete for everyone” (target, message_id).

---

🖼️ Media & Files

All media services require a target and a url.

Service	Unique Fields	Description
send_image	caption	JPEG, PNG, WebP (Max 16MB).
send_video	message (caption)	MP4, MOV (Max 16-64MB).
send_audio	ptt (boolean)	true sends as a Voice Note.
send_document	file_name, message	Any file type (Max 100MB).

---

📊 Interactive & Advanced

whatsapp.send_poll

• question: The voting topic.
• options: List of strings (Max 12).
• allow_multiple_responses: Optional boolean. Set to true to create a multi-choice poll.

whatsapp.send_buttons

• message: Body text.
• buttons: List of id and displayText (Max 3).
• footer: Optional small text.

whatsapp.send_list

• title, text, button_text.
• sections: Nested rows with id, title, and description.

whatsapp.send_event

Sends a WhatsApp Event invitation.

• name: (Required) Event title.
• description: Optional event details.
• date: Start time (ISO timestamp or Unix timestamp).
• location: Optional location name string or location object.
• join_link: Optional video/meeting link.
• is_canceled: Optional boolean flag if canceling event.

whatsapp.send_location

• latitude, longitude: (Required) coordinates.
• name, address: Optional labels for the map pin.

whatsapp.send_contact

• name: Display name.
• contact_number: Phone number for the vCard.

---

⚙️ Administration

whatsapp.update_presence

Updates your status. Options: available, unavailable, composing (typing), recording, paused.

whatsapp.search_groups

Finds Group IDs. Results appear in HA Notifications (🔔).

whatsapp.mark_as_read

Mark specific message_id or whole target chat as read.

whatsapp.get_contacts

Retrieves the list of cached contacts from your paired phone. Supports returning response data (contacts list).

Note on fields & Sync:

• Contact Sync: Baileys syncs contacts asynchronously on startup (contacts.set/contacts.upsert). If a contact hasn’t synced yet, in_contacts or name might be null initially.
• name: Contact name from your phone’s address book.
• notify: WhatsApp push name set by the contact (automatically populated when they send a message).
• verified_name: Only populated for official WhatsApp Business accounts (otherwise null).
• img_url: Profile picture URL (defaults to null to avoid rate limits).

whatsapp.check_number

Checks if a phone number (number) is registered on WhatsApp and whether it exists in your paired phone’s contacts list. Returns response data (exists, in_contacts, name, notify, jid).

Tips for Number Formatting:

• Supports international format with or without leading + / 00 (e.g. 491761234567, +491761234567, 00491761234567).
• Matching logic automatically strips country prefixes and leading zeros to perform a suffix match (minimum 7 digits), ensuring reliable matching regardless of local vs international format in your address book.

whatsapp.configure_webhook

url, enabled, and optional security token.

---

🌍 Global Service Parameters

These are available for almost every sending service:

• target: Recipient destination.
• account: Instance selector (if multiple).
• quote: Reply-to ID (also accepts alias reply_to).
• expiration: Auto-delete timer.