WhatsApp Messaging API

Start logging in to your WhatsApp account and obtain the sessionId used by every other endpoint. There are two login modes — pick one and send its JSON body below, then poll Get Session Status until status reads CONNECTED. QR login (recommended). Body: {"mode":"qr","deviceName":"My Bot"}. The status response carries a scannable qrImage (base64 data-URI) and a qrPageUrl you can open to watch login live. On your phone: WhatsApp → Settings → Linked Devices → Link a device, then scan the QR. Pairing-code login. Body: {"mode":"pairing","phoneNumber":"8613800138000","deviceName":"My Bot"}. phoneNumber is your full international number, digits only, no + and no spaces. The status response then returns an 8-character pairingCode. On your phone: WhatsApp → Settings → Linked Devices → Link a device → Link with phone number instead, and type the code. After connecting, the sessionId becomes a stable ID derived from the device, reusable across restarts. deviceName sets the label shown under WhatsApp's Linked Devices.

Return the current state of a session: its status (CREATED, WAITING_FOR_SCAN, CONNECTING, CONNECTED, DISCONNECTED, LOGGED_OUT, or FAILED), the login mode, the linked phone number, and — while waiting for login — the qrImage (base64 data-URI) or pairingCode plus a qrPageUrl. If the account has saved credentials but is offline, this call lazily reloads it and triggers a reconnect. Poll it after Create Session until status is CONNECTED.

Explicitly reconnect a session that has saved credentials but is currently offline, and return its latest status. Use it to recover a dropped connection on demand instead of waiting for the lazy reconnect that other endpoints trigger automatically. No request body is required.

Disconnect and remove a session. By default it only drops the live connection while keeping the saved credentials, so the account can be restored later. Pass logout=true to fully log out of WhatsApp, delete the local credentials, and unbind the proxy — after which the account must scan or pair again to reconnect.

Send a WhatsApp text message from a connected session to any recipient. Send a JSON body with the recipient's full international number (digits only, no +) as to and the message as text; optionally pass quoteMessageId (a message id from the inbox or chat history) to send it as a quoted reply. to must be a JSON number, not a string. Returns the upstream message id and timestamp. The session must have completed login.

Send a media message from a connected session. Send a JSON body with the recipient number as to, the media type as type (image, video, audio, voice, document, or sticker — voice means a PTT voice note), and the base64-encoded file content as data. document requires a fileName; caption adds a caption; mimeType overrides the inferred type; seconds sets audio/video duration. to must be a JSON number. Returns the upstream message id.

Return messages received in real time while the session was connected, in reverse chronological order (newest first). Each item includes the message id, chatJid, sender, type, text, and timestamp. The inbox is an in-memory cache holding the most recent 500 messages per session and is cleared on restart. Use limit to cap how many are returned. Ideal for polling new inbound messages to power auto-replies.

Add an emoji reaction to a message. Send a JSON body with the chatJid and the messageId of the target message, plus the emoji to apply. Send an empty-string emoji to remove your reaction. For group messages you may pass senderJid to identify the original sender; it is inferred from the in-memory cache when omitted. Returns the upstream result.

Edit the text of a message you previously sent. Send a JSON body with the chatJid, the messageId of your sent message, and the new text. For group messages you may pass senderJid; it is inferred from the in-memory cache when omitted. Only your own messages can be edited. Returns the upstream result.

Recall a message so it is deleted for all participants. Send a JSON body with the chatJid and messageId. Without senderJid it recalls a message you sent; with senderJid it can recall another group member's message (requires admin permission in that group). Returns the upstream result.

Send read receipts for one or more messages in a chat. Send a JSON body with the chatJid and either a single messageId or a messageIds array for batch marking; include senderJid when required for group messages. Marking as read shows the sender the blue double-check. Returns the upstream result.

Create a WhatsApp poll in a direct chat or group. Send a JSON body with the question and an options array (at least two entries). Address it either by to (a full international number, as a JSON number) or by chatJid (takes precedence and allows posting to a group). Set maxSelections to 1 for a single-choice poll or higher for multiple choice. Returns the upstream message id.

Return a summary of every chat known to the session, populated from the login history sync and real-time messages. Use it to build a conversation list and to discover the chatJids needed to read per-chat message history, send typing indicators, or set disappearing messages.

Return the most recent cached messages of one chat, in reverse chronological order. Provide the sessionId and the chatJid (e.g. 8613800138000@s.whatsapp.net for a direct chat or 120363...@g.us for a group). Messages come from the in-memory cache (login history sync plus real-time traffic). Use limit to control how many are returned.

Download and decrypt the media (image, video, audio, or document) attached to a message and return it base64-encoded. Provide the sessionId, chatJid, and messageId (from chat history or the inbox). The referenced message must be present in the in-memory cache and contain media, otherwise the request fails.

Show a 'typing…' or 'recording audio…' indicator in a chat. Send a JSON body with state (composing to start or paused to stop) and optional media (text for typing or audio for recording). Use it to make a bot feel more human by signalling activity before a reply arrives.

Enable or change the disappearing-messages timer for a chat. Send a JSON body with durationSeconds: 0 turns it off, 86400 for 24 hours, 604800 for 7 days, or 7776000 for 90 days. Only these four values are accepted. Applies to new messages in the chat going forward.

Return the contacts currently held in the session's local store, synced after login. Each contact includes its identifiers and name. Use it to enumerate known contacts for enrichment, recipient pickers, or audience building.

Check whether a given phone number has an active WhatsApp account, using a connected session. Pass the full international number (digits only, no +) in the path. Returns whether the number exists along with its JID. Use it to validate recipients before sending to improve deliverability and reduce wasted sends.

Return a contact's public About (status) text, or an empty result if it is hidden by privacy or not set. Pass the full international number (digits only, no +) in the path. Uses a connected session to query the value in real time.

Return the URL of a contact's profile picture, with exists=false when it is hidden by privacy or not set. Pass the full international number (digits only, no +) in the path. Uses a connected session to resolve the current picture URL in real time.

Return the WhatsApp Business profile for a number: isBusiness plus, for business accounts, details such as address, email, category, and description. Pass the full international number (digits only, no +) in the path. Personal numbers return isBusiness=false. Uses a connected session for a live lookup.

Return information about the account logged in on this session: its JID, phone number, LID, and nickname. Use it to confirm exactly which account a session is connected as and to display your own identity before sending.

Update the connected account's public profile. Send a JSON body with name to set a new nickname and/or about to set a new status text; provide at least one. Changes are reflected on your WhatsApp profile visible to others. Returns the upstream result.

Return the connected account's wa.me contact QR link (https://wa.me/qr/...), which others can scan or open to start a chat with you. Pass revoke=true to invalidate the old link and generate a fresh one. Useful for sharing a support or sales entry point.

Create a WhatsApp group with a name and an initial set of participants. Send a JSON body with name (string) and participants (an array of full international numbers as JSON numbers, digits only), for example {"name":"Support Group","participants":[8613800138000,4915256515060]}. Returns the new group's JID and metadata for immediate follow-up operations.

Return every group the connected account is a member of. Use it to enumerate communities, discover groupJids for management operations, or sync the account's group roster into your own systems.

Join a WhatsApp group using an invite link or code. Send a JSON body with code, which can be a full link (https://chat.whatsapp.com/xxx) or just the final code segment. Returns the joined group's JID. Useful for programmatically entering communities you administer or monitor.

Return a group's details: its name (subject), announcement/description, owner, and member list. Provide the sessionId and the groupJid (ending with @g.us). Use it to inspect membership and settings before broadcasting or moderation.

Update a group's settings. Send a JSON body with any combination of: name (group name), topic (announcement/description), announce (only admins can post), locked (only admins can edit group info), and joinApproval (joining requires approval). Provide at least one field; only supplied fields change. Requires admin permission in the group.

Add one or more members to a group. Send a JSON body that is an array of full international numbers (JSON numbers, digits only), for example [8613800138000,4915256515060]. The response contains per-member results where a non-zero error marks the numbers that failed. Requires admin permission in the group.

Remove one or more members from a group. Send a JSON body that is an array of full international numbers (JSON numbers, digits only), for example [8613800138000]. The response contains per-member results where a non-zero error marks the numbers that failed. Requires admin permission in the group.

Promote members to admin or demote existing admins. Send a JSON body with phones (an array of full international numbers as JSON numbers) and action (promote or demote), for example {"phones":[8613800138000],"action":"promote"}. The response contains per-member results. Requires admin permission in the group.

Return a group's invite link (https://chat.whatsapp.com/...). Pass reset=true to invalidate the old link and generate a new one — useful when a link has leaked. Provide the sessionId and groupJid. Requires admin permission in the group.

Set a group's profile picture. Send a JSON body with data containing the base64-encoded JPEG image. Returns the new picture id. Requires admin permission in the group. Ideal for branding community or support groups programmatically.

Remove the connected account from a group. Provide the sessionId and groupJid; no request body is required. Returns the JID of the group that was left. Use it to programmatically exit communities the account no longer needs to be in.

Set the connected account's global presence. Send a JSON body with state set to available (online) or unavailable (offline). This controls whether others see the account as online. Use it to keep a bot appearing online during working hours or offline when idle.

Subscribe to presence (online/offline) updates for a contact. Send a JSON body with phone set to the full international number (JSON number, digits only). After subscribing, the account receives that contact's presence updates subject to their privacy settings.

Return the connected account's blocklist: the list of blocked JIDs and a total count. Use it to audit who is blocked, sync the blocklist into your own moderation system, or confirm a number was successfully blocked.

Block or unblock a phone number. Send a JSON body with phone (the full international number, JSON number, digits only) and action (block or unblock). Returns the updated blocklist. Use it to automatically shut out spam or reinstate a contact.

Return the connected account's current privacy settings: who can see your last seen, profile photo, About, and status, plus read receipts, who can add you to groups, online visibility, and call permissions. Use it to audit the account's privacy posture before changing any setting.

Update one of the account's privacy settings. Send a JSON body with setting (groupadd, last, status, profile, readreceipts, online, or calladd) and value (all, contacts, contact_blacklist, none, match_last_seen, or known). Each setting supports a different range of values, validated by the WhatsApp server. Returns the full updated settings.