# WaAPI Documentation > Documentation for WaAPI ## API Reference: WaAPI - [Introduction](https://waapi.readme.io/reference/waapi-api-documentation.md) - [Get Started 🚀️️](https://waapi.readme.io/reference/get-started.md) - [API Token](https://waapi.readme.io/reference/api-token.md): Get and use your API Token - [Webhooks 🪝](https://waapi.readme.io/reference/webhooks.md) - [Message Event](https://waapi.readme.io/reference/message-event.md) - [QR Event](https://waapi.readme.io/reference/qr-event.md) - [Ready Event](https://waapi.readme.io/reference/ready-event.md) - [Loading Event](https://waapi.readme.io/reference/loading-event.md) - [Authenticated Event](https://waapi.readme.io/reference/authenticated-event.md) - [Auth Failure Event](https://waapi.readme.io/reference/auth-failure-event.md) - [Disconnected Event](https://waapi.readme.io/reference/disconnected-event.md) - [Message Create Event](https://waapi.readme.io/reference/message-create-event.md) - [Message Edit Event](https://waapi.readme.io/reference/message-edit-event.md) - [Message Acknowlegded Event](https://waapi.readme.io/reference/message-ack-event.md) - [Message Revoke Everyone Event](https://waapi.readme.io/reference/message-revoke-everyone-event.md) - [Message Revoke Me Event](https://waapi.readme.io/reference/message-revoke-me-event.md) - [Message Reaction Event](https://waapi.readme.io/reference/message-reaction-event.md) - [Group Update Event](https://waapi.readme.io/reference/group-update-event.md) - [Group Join Event](https://waapi.readme.io/reference/group-join-event.md) - [Group Leave Event](https://waapi.readme.io/reference/group-leave-event.md) - [Vote Update Event](https://waapi.readme.io/reference/vote-update-event.md) - [Libraries and Packages 📦](https://waapi.readme.io/reference/libraries-and-packages.md) ## API Reference: WaAPI API - instances - [list instances](https://waapi.readme.io/reference/list-instances.md): Retrieve a list of your instances. - [create instance](https://waapi.readme.io/reference/create-instance.md): Create a new instance. Optionally set a name and webhook configuration. - [retrieve instance](https://waapi.readme.io/reference/retrieve-instance.md): Retrieve a single instance by its ID - [update instance](https://waapi.readme.io/reference/update-instance.md): Update the instance. - [delete instance](https://waapi.readme.io/reference/delete-instance.md): delete an instance by ID - [get async request status](https://waapi.readme.io/reference/get-request-status.md): Retrieve the status or result of an async request by its reference UUID. Results are cached for up to 5 minutes after processing. An asynchronous send refused by the send protection is attempted up… - client - [client status of instance](https://waapi.readme.io/reference/client-status-of-instance.md): retrieve the status of your running client - [retrieve QR Code](https://waapi.readme.io/reference/retrieve-qr-code.md): Retrieves a base64 encoded QR code image that can be used to authenticate and connect a account to this instance. - [retrieve basic client information](https://waapi.readme.io/reference/retrieve-basic-client-information.md): Retrieve general information of the user connected to your instance. - [logout](https://waapi.readme.io/reference/logout.md): Logs out the client, closing the current session - [reboot instance](https://waapi.readme.io/reference/reboot.md): Reboots your instance. This will close the current session and restart the client. The instance will need to be re-authenticated if it was previously logged in. - [send presence available](https://waapi.readme.io/reference/send-presence-available.md): Sets the client's presence status to 'available'/'online' - [set status](https://waapi.readme.io/reference/set-status.md): Sets the status text for the connected account - [set display name](https://waapi.readme.io/reference/set-display-name.md): Sets the display name for the account - [request pairing code](https://waapi.readme.io/reference/request-pairing-code.md): Request a pairing code for phone number registration. To prevent abuse and ensure system stability, pairing code requests are limited to 2 per minute. Multiple rapid requests may indicate automated… - [send presence unavailable](https://waapi.readme.io/reference/send-presence-unavailable.md): Sets the client's presence status to 'unavailable'/'offline' - [[BETA] subscribe to and fetch current presence of a chat](https://waapi.readme.io/reference/get-chat-presence.md): Subscribes to presence updates for the given chat and returns the current state. Subsequent changes emit presence_update webhook events (if enabled in webhook settings). **Important — subscription… - [[BETA] read cached presence for a chat without subscribing](https://waapi.readme.io/reference/get-chat-presence-snapshot.md): Returns the locally cached presence for a chat without triggering a new subscription. Returns null if the chat has never been subscribed (via get-chat-presence) during the current session. Use… - [set device name](https://waapi.readme.io/reference/set-device-name.md): Sets the device name and/or browser name displayed for the Web session. - [send event response](https://waapi.readme.io/reference/send-event-response.md): Sends a response (RSVP) to a calendar event message. - [revoke status message](https://waapi.readme.io/reference/revoke-status-message.md): Revokes (deletes) a previously sent status message. - [[BETA] get privacy settings](https://waapi.readme.io/reference/get-privacy-settings.md): Retrieve the authenticated account's privacy settings. Note: This endpoint is currently in beta and may change without notice. - [[BETA] set privacy setting](https://waapi.readme.io/reference/set-privacy-setting.md): Update a single privacy category. Allowed values depend on the category. Note: This endpoint is currently in beta and may change without notice. - call - [create call link](https://waapi.readme.io/reference/create-call-link.md): Creates a call link for a scheduled call. - [[BETA] accept call](https://waapi.readme.io/reference/accept-call.md): Accepts the ringing incoming call. Media starts after the call connected; audioUrl plays once, imageUrl is shown, videoUrl loops as the camera. hangupAfterSeconds, if given, ends the call that many… - [[BETA] reject call](https://waapi.readme.io/reference/reject-call.md): Rejects the ringing incoming call (or the call with callId). Without a matching call the answer is `data.status: error` with `message: failed to reject call` and an `explanation`. Note: This endpoint… - [[BETA] end call](https://waapi.readme.io/reference/end-call.md): Ends the active call (or the call with callId), whether it is still ringing or already connected. Without a matching call the answer is `data.status: error` with `message: failed to end call` and an… - [[BETA] play call audio](https://waapi.readme.io/reference/play-call-audio.md): Plays wav/mp3/ogg (max 25 MB) into the connected call; resolves after playback. The call has to be connected — one that is still ringing has no media channel and answers `data.status: error` with… - [[BETA] start call](https://waapi.readme.io/reference/start-call.md): Places a voice or video call. Limited to 10 per minute and 100 per hour per instance; the slot is taken before the media URLs are fetched, so a bad audioUrl or videoUrl still spends one. With… - [[BETA] play call video](https://waapi.readme.io/reference/play-call-video.md): Plays an mp4 (H.264) as the outgoing camera of the connected call; loop=false resolves when the clip ended. The call has to be connected — one that is still ringing has no media channel and answers… - [[BETA] show call image](https://waapi.readme.io/reference/show-call-image.md): Shows a jpeg/png as the outgoing camera of the connected video call. The call has to be connected — one that is still ringing has no media channel and answers `data.status: error` with `message:… - business - [[BETA] get business profile](https://waapi.readme.io/reference/get-business-profile.md): Retrieve a business profile. Defaults to the authenticated account. Only WhatsApp Business accounts expose a profile. Note: This endpoint is currently in beta and may change without notice. - [[BETA] get business categories](https://waapi.readme.io/reference/get-business-categories.md): List available business categories. Pass parentId to drill down; omit for top level. Note: This endpoint is currently in beta and may change without notice. - [[BETA] set business profile](https://waapi.readme.io/reference/set-business-profile.md): Update the authenticated business account's profile. Only provided fields are changed. Profile picture is managed separately. Note: This endpoint is currently in beta and may change without notice. - [[BETA] get quick replies](https://waapi.readme.io/reference/get-quick-replies.md): List all quick replies configured on the business account. Note: This endpoint is currently in beta and may change without notice. - [[BETA] create quick reply](https://waapi.readme.io/reference/create-quick-reply.md): Create a new quick reply. Returns the created quick reply with its generated id. Note: This endpoint is currently in beta and may change without notice. - [[BETA] update quick reply](https://waapi.readme.io/reference/update-quick-reply.md): Update an existing quick reply by id. Only provided fields are changed. Note: This endpoint is currently in beta and may change without notice. - [[BETA] delete quick reply](https://waapi.readme.io/reference/delete-quick-reply.md): Delete a quick reply by id. Note: This endpoint is currently in beta and may change without notice. - message - [send a text message to a chat](https://waapi.readme.io/reference/send-text-message-to-chat.md): Send a text message to a chat. The chatId format varies depending on the chat type: - Individual chat: {phone_number}@c.us (e.g. 50664083362@c.us) - Group chat: {group_id}@g.us (e.g.… - [send a media message (image, video, audio, document)](https://waapi.readme.io/reference/send-media-message.md): Send a media file to a chat. Provide either `mediaUrl` (a publicly accessible URL) or `mediaBase64` (base64-encoded file content with `mediaName`), but not both. The chatId format varies depending… - [send vCard](https://waapi.readme.io/reference/send-vcard.md): Send a vCard to a contact or group. - [send location](https://waapi.readme.io/reference/send-location.md): Send a location message to a contact or group chat. The location can include additional details like name, address and URL. - [fetch messages from a chat](https://waapi.readme.io/reference/fetch-messages.md): Retrieve messages from a specific chat with optional filtering and media inclusion - [get message by ID](https://waapi.readme.io/reference/get-message-by-id.md): Retrieve a specific message using its unique identifier. Optionally includes the media content if requested. - [get message info by id](https://waapi.readme.io/reference/get-message-info-by-id.md): get a message info by id - [download media from message](https://waapi.readme.io/reference/download-media.md): Downloads the media content from a message and returns a temporary download URL valid for 15 minutes. Use this instead of get-message-by-id with includeMedia when you only need the media file. A… - [delete message by id](https://waapi.readme.io/reference/delete-message-by-id.md): delete a message by id - [search messages](https://waapi.readme.io/reference/search-messages.md): Search for messages across all chats or within a specific chat. Returns paginated results with message details. - [edit a message](https://waapi.readme.io/reference/edit-message.md): Edit a previously sent message. - [create poll message](https://waapi.readme.io/reference/create-poll.md): Creates and sends an interactive poll message to a specified chat. The poll can have between 2-12 options and optionally allow multiple selections. - [forward a message](https://waapi.readme.io/reference/forward-message.md): Forward a message to another chat. - [get message reactions](https://waapi.readme.io/reference/get-reactions.md): Get reactions for a specific message - [react to message](https://waapi.readme.io/reference/react-to-message.md): Add or remove a reaction emoji to/from a message - [get message mentions](https://waapi.readme.io/reference/get-message-mentions.md): Get mentions from a message - [get poll votes](https://waapi.readme.io/reference/get-poll-votes.md): Retrieves the vote information for a specific poll message, including who voted for which options and the original poll message details. - [pin message](https://waapi.readme.io/reference/pin-message.md): Pin a message in a chat - [unpin message](https://waapi.readme.io/reference/unpin-message.md): Unpin a message in a chat - [star message](https://waapi.readme.io/reference/star-message.md): Star a message by its ID - [unstar message](https://waapi.readme.io/reference/unstar-message.md): Remove star from a message - [send event message](https://waapi.readme.io/reference/send-event.md): Creates and sends a calendar event message to a specified chat. - [vote on poll](https://waapi.readme.io/reference/vote-on-poll.md): Submits a vote on an existing poll message with the specified options. - [edit scheduled event](https://waapi.readme.io/reference/edit-scheduled-event.md): Edits an existing scheduled event message with updated details. - [get pinned messages](https://waapi.readme.io/reference/get-pinned-messages.md): Retrieves all pinned messages from a specified chat. - chat - [mark chat messages as seen (blue ticks)](https://waapi.readme.io/reference/send-seen.md): Mark all messages in a chat as seen (read). This will show blue ticks (double check marks) to the sender only if both parties have read receipts enabled in their privacy settings. If read receipts… - [get all chats](https://waapi.readme.io/reference/get-chats.md): Retrieves a list of all chats with their latest messages and metadata. Supports pagination. - [mark chat as unread](https://waapi.readme.io/reference/mark-chat-unread.md): Marks a specified chat conversation as unread. This is useful for flagging important conversations for later attention. - [mute chat](https://waapi.readme.io/reference/mute-chat.md): Mute notifications for a specific chat either indefinitely or until a specified date - [unmute chat](https://waapi.readme.io/reference/unmute-chat.md): Removes mute settings from a specified chat, allowing notifications to be received again. - [pin chat](https://waapi.readme.io/reference/pin-chat.md): Pins a chat to the top of the chat list. The operation may fail if the maximum number of pinned chats (3) has been reached. - [unpin chat](https://waapi.readme.io/reference/unpin-chat.md): Removes a chat from pinned status. This endpoint allows you to unpin a previously pinned chat conversation. - [get chat by id](https://waapi.readme.io/reference/get-chat-by-id.md): Get chat by ID - [delete chat by id](https://waapi.readme.io/reference/delete-chat-by-id.md): Delete chat by ID - [archive chat](https://waapi.readme.io/reference/archive-chat.md): archive chat - [unarchive chat](https://waapi.readme.io/reference/unarchive-chat.md): unarchive chat - [get chat labels](https://waapi.readme.io/reference/get-chat-labels.md): Get chat labels by chat ID - [get chats by labelId](https://waapi.readme.io/reference/get-chats-by-label-id.md): Get chats by label ID - [send typing state](https://waapi.readme.io/reference/send-typing.md): Sends typing state indicator to a chat - [clear chat messages](https://waapi.readme.io/reference/clear-chat-messages.md): Clears all messages from a specific chat - [sync chat history](https://waapi.readme.io/reference/sync-chat-history.md): Synchronizes the chat history for a specific chat - [stop typing indicator](https://waapi.readme.io/reference/send-stop-typing.md): Stops the typing indicator for a chat - [add customer note](https://waapi.readme.io/reference/add-customer-note.md): Adds a note to a customer chat for internal reference. - [get customer note](https://waapi.readme.io/reference/get-customer-note.md): Retrieves the note associated with a customer chat. - [[BETA] get disappearing messages](https://waapi.readme.io/reference/get-disappearing-messages.md): Return the current disappearing-messages timer for a chat. Note: This endpoint is currently in beta and may change without notice. - [[BETA] set disappearing messages](https://waapi.readme.io/reference/set-disappearing-messages.md): Set the disappearing-messages timer on a chat. 0 disables; 86400 = 24h, 604800 = 7d, 7776000 = 90d. Groups require admin. Note: This endpoint is currently in beta and may change without notice. - [[BETA] get disappearing durations](https://waapi.readme.io/reference/get-disappearing-durations.md): Return the allowed disappearing-messages durations (in seconds). Server-controlled, may vary by account/region. Note: This endpoint is currently in beta and may change without notice. - contact - [get all contacts](https://waapi.readme.io/reference/get-contacts.md): Retrieves a list of all contacts from the account, including saved contacts and users who have messaged you. - [get formatted number](https://waapi.readme.io/reference/get-formatted-number.md): Format a phone number into standardized format - [is registered user](https://waapi.readme.io/reference/is-registered-user.md): Check if a given contactId is registered. - [get profile picture URL](https://waapi.readme.io/reference/get-profile-pic-url.md): Retrieves the profile picture URL for a contact, chat, group, or newsletter. Access is subject to privacy settings. Use appropriate suffixes: @c.us for contacts/chats, @g.us for groups, @newsletter… - [get contact details by ID](https://waapi.readme.io/reference/get-contact-by-id.md): Retrieves detailed contact information for a specific contact using their ID. Returns contact details including name, number, business status, and various contact flags. - [[BETA] add and update contact](https://waapi.readme.io/reference/upsert-contact.md): Creates a new contact or updates an existing one in the address book. The contact will be synchronized to the device's address book if syncToAddressbook is true. Note: This endpoint is currently in… - [get contact LID and phone](https://waapi.readme.io/reference/get-lid.md): Resolves the mapping between a contact's Linked ID (LID) and phone number. Works in both directions: pass phone-number IDs (number@c.us) to get their LID, or pass Linked IDs (number@lid) to get the… - [delete contact](https://waapi.readme.io/reference/delete-contact.md): Deletes a contact from the address book. - [block a contact](https://waapi.readme.io/reference/block-contact.md): Blocks a contact, preventing them from sending messages to the authenticated user. The contact will not be able to see the user's last seen, online status, or status updates. - [unblock a contact](https://waapi.readme.io/reference/unblock-contact.md): Removes a contact from the blocked contacts list, allowing them to send messages and see your information again according to your privacy settings. - [get blocked contacts](https://waapi.readme.io/reference/get-blocked-contacts.md): Retrieves a list of all blocked contacts - [get common groups with contact](https://waapi.readme.io/reference/get-common-groups.md): Get list of groups that are in common between you and the specified contact - [get contact about info](https://waapi.readme.io/reference/get-contact-about-info.md): Retrieves the about/status info for a specific contact - [get broadcast](https://waapi.readme.io/reference/get-broadcast.md): Retrieves broadcast list details for a specified contact. - number - [get chat ID from phone number](https://waapi.readme.io/reference/get-number-id.md): Converts a phone number into the proper chat ID format. This is especially useful for countries that don't follow the standard chat ID format (like Brazil, Mexico and Argentina). The endpoint ensures… - [get country code](https://waapi.readme.io/reference/get-country-code.md): Get the country code for a given phone number - group - [create group](https://waapi.readme.io/reference/create-group.md): Creates a new group with specified name and participants - [get group participants](https://waapi.readme.io/reference/get-group-participants.md): Get group participants - [get group info](https://waapi.readme.io/reference/get-group-info.md): Get group info - [update group info](https://waapi.readme.io/reference/update-group-info.md): Update Group Information - [update group settings](https://waapi.readme.io/reference/update-group-settings.md): Update Group Settings - [add group participant](https://waapi.readme.io/reference/add-group-participant.md): Add a participant to a group - [remove group participant](https://waapi.readme.io/reference/remove-group-participant.md): Remove a participant from a group - [promote group participant](https://waapi.readme.io/reference/promote-group-participant.md): Promote a participant to admin - [demote group participant](https://waapi.readme.io/reference/demote-group-participant.md): Demote a participant from admin to normal participant - [approve group membership requests](https://waapi.readme.io/reference/accept-group-member-requests.md): Approve pending group membership requests - [deny group membership requests](https://waapi.readme.io/reference/deny-group-member-requests.md): Deny pending group membership requests - [get group membership requests](https://waapi.readme.io/reference/get-group-member-requests.md): Get pending group membership requests - [accept group invite](https://waapi.readme.io/reference/accept-invite.md): Accept a group invite using an invite code - [get group invite info](https://waapi.readme.io/reference/get-invite-info.md): Get information about a group invite code - [accept group invite](https://waapi.readme.io/reference/accept-group-invite.md): Accept a group invitation. Pass either inviteCode (the invite code or the full invite link) — identical to accept-invite — or inviteData, the invite object carried by a group invite message. - channel - [create a channel](https://waapi.readme.io/reference/create-channel.md): Create a channel - [get channels](https://waapi.readme.io/reference/get-channels.md): get your channels - [get channel by id](https://waapi.readme.io/reference/get-channel-by-id.md): get channel by id - [subscribe to channel](https://waapi.readme.io/reference/subscribe-to-channel.md): subscribe to channel - [unsubscribe from channel](https://waapi.readme.io/reference/unsubscribe-from-channel.md): unsubscribe from channel - [search channels](https://waapi.readme.io/reference/search-channels.md): Search for channels - community - [[BETA] create a community](https://waapi.readme.io/reference/create-community.md): Create a new Community (parent group containing subgroups). When createGeneralChat is true (default), the service also provisions a default 'General' announcement subgroup. Note: This endpoint is… - [[BETA] get communities](https://waapi.readme.io/reference/get-communities.md): Retrieve all Communities the instance is a member of. Note: This endpoint is currently in beta and may change without notice. - [[BETA] get community by id](https://waapi.readme.io/reference/get-community-by-id.md): Retrieve a specific Community by its ID. Note: This endpoint is currently in beta and may change without notice. - [[BETA] get community subgroups](https://waapi.readme.io/reference/get-community-subgroups.md): Retrieve all joined subgroups of a Community as full chat instances. Avoids N+1 roundtrips when walking a community. Note: This endpoint is currently in beta and may change without notice. - [[BETA] send community announcement](https://waapi.readme.io/reference/send-community-announcement.md): Post an announcement to a Community. Supports text (message), URL-based media (mediaUrl), and broadcast targeting. target='general' (default) posts only to the default announcement subgroup which… - [[BETA] link community subgroup](https://waapi.readme.io/reference/link-community-subgroup.md): Link one or more existing standalone groups to a Community as subgroups. Note: This endpoint is currently in beta and may change without notice. - [[BETA] unlink community subgroup](https://waapi.readme.io/reference/unlink-community-subgroup.md): Unlink one or more subgroups from a Community. They become standalone groups again. Note: This endpoint is currently in beta and may change without notice. - [[BETA] leave community](https://waapi.readme.io/reference/leave-community.md): Leave a Community as the current user. Note: This endpoint is currently in beta and may change without notice. - label - [get all labels](https://waapi.readme.io/reference/get-labels.md): Retrieve all labels. - [get label by id](https://waapi.readme.io/reference/get-label-by-id.md): Get label by ID - [change chat labels](https://waapi.readme.io/reference/change-chat-labels.md): Add or remove labels on a chat. - story - [[BETA] get stories](https://waapi.readme.io/reference/get-stories.md): Retrieves all available stories/status updates that are visible to the authenticated user. This includes both viewed and unviewed stories from contacts. Note: This endpoint is currently in beta and… - [[BETA] post a text or media status/story](https://waapi.readme.io/reference/post-status.md): Publishes a status update visible to contacts per the user's privacy settings. Provide `content` for a text status (with optional `backgroundColor` ARGB integer and `fontStyle` 0-7) or `mediaUrl`… - [revoke status](https://waapi.readme.io/reference/revoke-status.md): Revokes (deletes) a previously posted status/story update. - [[BETA] set the Status privacy](https://waapi.readme.io/reference/set-status-privacy.md): Configure who can see Status posts from this instance. Set `type` to "all" for all contacts, "allow" to restrict visibility to a specific list of contacts, or "deny" to exclude specific contacts. ⚠️… - [[BETA] get the current Status privacy](https://waapi.readme.io/reference/get-status-privacy.md): Retrieve the current Status privacy setting for the instance. Returns the audience type ("contact" for all contacts, "allow-list" for an allowlist, "deny-list" for a denylist) and the configured… - webhooks - [create webhook subscription](https://waapi.readme.io/reference/create-webhook-subscription.md): Subscribe a URL to receive instance events. Up to 25 active subscriptions are allowed per instance. Subscribing an already-registered URL again returns the existing subscription with a 200 status… - [list webhook subscriptions](https://waapi.readme.io/reference/list-webhook-subscriptions.md): Retrieve the webhook subscriptions registered on an instance. - [delete webhook subscription](https://waapi.readme.io/reference/delete-webhook-subscription.md): Remove a webhook subscription from an instance. A subscription id that does not belong to this instance is reported as not found, not forbidden. - otp - [create otp request](https://waapi.readme.io/reference/create-otp-request.md): Start a verification. Returns a keyword and a link that opens a pre-filled message to the instance's number; the end user sends it and receives the code. Without `identity` the request registers a… - [get otp request](https://waapi.readme.io/reference/get-otp-request.md): Read the status of a verification request. The keyword, message text and link are not repeated here. Needs the `read` ability. - [verify otp code](https://waapi.readme.io/reference/verify-otp-code.md): Check the code the end user typed. A correct code verifies the request once; a second try with the same code answers `already_used`. A wrong code counts as an attempt (5 per request, 10 per identity…