Client Reference

WhatsApp.send_image(to, image, caption=None, footer=None, buttons=None, *, reply_to_message_id=None, mime_type=None, tracker=None, identity_key_hash=None, sender=None)#

Image messages are messages that display a single image and an optional caption.

See Image messages.
See Supported image formats.
Images must be 8-bit, RGB or RGBA.

Example

>>> wa = WhatsApp()
>>> wa.send_image(
...     to="1234567890",
...     image="https://example.com/image.png",
...     caption="This is an image!",
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
image (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The image to send (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
caption (str | None) –
The caption of the image (required when buttons are provided, markdown allowed).
footer (str | None) –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | FlowButton | None) – The buttons to send with the image (optional).
reply_to_message_id (str | None) – The message ID to quote (optional).
mime_type (str | None) – The mime type of the image (optional, required when sending an image as bytes, or file path that does not have an extension).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent image message.

Return type:

WhatsApp.send_video(to, video, caption=None, footer=None, buttons=None, *, mime_type=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Video messages display a thumbnail preview of a video image with an optional caption. When the WhatsApp user taps the preview, it loads the video and displays it to the user.

Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only.
See Video messages.
See Supported video formats.

Example

>>> wa = WhatsApp()
>>> wa.send_video(
...     to="1234567890",
...     video="https://example.com/video.mp4",
...     caption="This is a video",
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
video (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The video to send (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
caption (str | None) –
The caption of the video (required when sending a video with buttons, markdown allowed).
footer (str | None) –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | FlowButton | None) – The buttons to send with the video (optional).
reply_to_message_id (str | None) – The message ID to quote (optional).
mime_type (str | None) – The mime type of the video (optional, required when sending a video as bytes or file path that does not have an extension).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent video message.

Return type:

WhatsApp.send_audio(to, audio, *, is_voice=None, mime_type=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Basic audio messages display a download icon and a music icon. When the WhatsApp user taps the play icon, the user must manually download the audio message for the WhatsApp client to load and then play the audio file.

See Audio messages.
See Supported audio formats.

Example

>>> wa = WhatsApp()
>>> wa.send_audio(
...     to='1234567890',
...     audio='https://example.com/audio.mp3',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
audio (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The audio file to send (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
is_voice (bool | None) – Set to True if sending a voice message (use send_voice() instead for better type support).
mime_type (str | None) – The mime type of the audio file (optional, required when sending an audio as bytes or file path that does not have an extension).
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent audio message.

Return type:

WhatsApp.send_voice(to, voice, *, mime_type=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

A voice message (sometimes referred to as a voice note, voice memo, or audio) is a recording of one or more persons speaking, and can include background sounds like music. Voice messages include features like automatic download, profile picture, and voice icon, not available with a basic audio message. If the user has set voice message transcripts to Automatic, a text transcription of the message will also be included.

See Voice messages.
Voice messages require .ogg files encoded with the OPUS codec. If you send a different file type or a file encoded with a different codec, voice message transcription will fail.
The play icon will only appear if the file is 512KB or smaller, otherwise it will be replaced with a download icon (a downward facing arrow).
Your business’s profile image is used as the profile image, accompanied by a microphone icon.
The text transcription appears if the user has enabled Automatic voice message transcripts. If the user has set this to Manual, the text “Transcribe” will appear instead, which will display the transcribed text once tapped. If the user has set voice message transcripts to Never, no text will appear.

Example

>>> wa = WhatsApp()
>>> wa.send_voice(
...     to='1234567890',
...     voice='https://example.com/voice.ogg',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
voice (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The voice file to send (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
mime_type (str | None) – The mime type of the voice file (optional, required when sending an audio as bytes or file path that does not have an extension).
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent voice message.

Return type:

SentVoiceMessage

WhatsApp.send_document(to, document, filename=<object object>, caption=None, footer=None, buttons=None, *, mime_type=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Document messages are messages that display a document icon, linked to a document, that a WhatsApp user can tap to download.

See Document messages.
See Supported document types.

Example

>>> wa = WhatsApp()
>>> wa.send_document(
...     to="1234567890",
...     document="https://example.com/example_123.pdf",
...     filename="example.pdf",
...     caption="Example PDF"
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
document (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The document to send (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
filename (str | None) – Document filename, with extension. The WhatsApp client will use an appropriate file type icon based on the extension (Optional, if not provided, if possible, the filename will be extracted from the media. pass None to skip this behavior).
caption (str | None) –
The caption of the document (required when sending a document with buttons, markdown allowed).
footer (str | None) –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | FlowButton | None) – The buttons to send with the document (optional).
reply_to_message_id (str | None) – The message ID to quote (optional).
mime_type (str | None) – The mime type of the document (optional, required when sending a document as bytes or file path that does not have an extension).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent document message.

Return type:

WhatsApp.send_location(to, latitude, longitude, name=None, address=None, *, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Location messages allow you to send a location’s latitude and longitude coordinates to a WhatsApp user.

Read more about Location messages.

Example

>>> wa = WhatsApp()
>>> wa.send_location(
...     to='1234567890',
...     latitude=37.4847483695049,
...     longitude=--122.1473373086664,
...     name='WhatsApp HQ',
...     address='Menlo Park, 1601 Willow Rd, United States',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
latitude (float) – The latitude of the location.
longitude (float) – The longitude of the location.
name (str | None) – The name of the location (optional).
address (str | None) – The address of the location (optional).
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent location message.

Return type:

WhatsApp.request_location(to, text, *, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Location request messages display body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can then use to share their location.

Once the user shares their location, a Message update is triggered, containing the user’s location details.
Read more about Location request messages.

Example

>>> wa = WhatsApp()
>>> wa.request_location(
...     to='1234567890',
...     text='Please share your location with us.',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
text (str) – The text to send with the button.
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent location request message.

Return type:

SentLocationRequest

WhatsApp.send_contact(to, contact, *, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses. When a WhatsApp user taps the message’s profile arrow, it displays the contact’s information in a profile view:

Each message can include information for up to 257 contacts, although it is recommended to send fewer for usability and negative feedback reasons.
See Contacts messages.

Example

>>> from pywa.types import Contact
>>> wa = WhatsApp()
>>> wa.send_contact(
...     to='1234567890',
...     contact=Contact(
...         name=Contact.Name(formatted_name='David Lev', first_name='David'),
...         phones=[Contact.Phone(phone='1234567890', wa_id='1234567890', type='MOBILE')],
...         emails=[Contact.Email(email='test@test.com', type='WORK')],
...         urls=[Contact.Url(url='https://exmaple.com', type='HOME')],
...      )
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
contact (Contact | Iterable[Contact]) – The contact/s to send.
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent contact/s message.

Return type:

WhatsApp.send_sticker(to, sticker, *, mime_type=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Sticker messages display animated or static sticker images in a WhatsApp message.

A static sticker needs to be 512x512 pixels and cannot exceed 100 KB.
An animated sticker must be 512x512 pixels and cannot exceed 500 KB.
See Sticker messages.
See Supported sticker formats.

Example

>>> wa = WhatsApp()
>>> wa.send_sticker(
...     to='1234567890',
...     sticker='https://example.com/sticker.webp',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
sticker (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The sticker to send (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
mime_type (str | None) – The mime type of the sticker (optional, required when sending a sticker as bytes or file path that does not have an extension).
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent sticker message.

Return type:

WhatsApp.send_catalog(to, body, footer=None, *, thumbnail_product_sku=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Catalog messages are messages that allow you to showcase your product catalog entirely within WhatsApp.

Catalog messages display a product thumbnail header image of your choice, custom body text, a fixed text header, a fixed text sub-header, and a View catalog button.

When a customer taps the View catalog button, your product catalog appears within WhatsApp.
You must have inventory uploaded to Meta in an ecommerce catalog connected to your WhatsApp Business Account.
Read more about Catalog messages.

Example

>>> wa = WhatsApp()
>>> wa.send_catalog(
...     to='1234567890',
...     body='Check out our catalog!',
...     footer='Powered by PyWa',
...     thumbnail_product_sku='SKU123',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
body (str) – Text to appear in the message body (up to 1024 characters).
footer (str | None) – Text to appear in the footer of the message (optional, up to 60 characters).
thumbnail_product_sku (str | None) – Item SKU number. Labeled as Content ID in the Commerce Manager. The thumbnail of this item will be used as the message’s header image. If omitted, the product image of the first item in your catalog will be used.
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent catalog message.

Return type:

WhatsApp.send_template(to, name=None, language=None, params=None, *, template=None, use_mm_lite_api=False, message_activity_sharing=None, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Send a template to a WhatsApp user.

To create a template, use create_template().
Read more about Template Messages.

Example:

from pywa.types.templates import *

wa = WhatsApp(...)
wa.send_template(
    to='1234567890',
    name='seasonal_promotion',
    language=TemplateLanguage.ENGLISH_US,
    params=[
        BodyText.params(season='Summer'),
        CopyCodeButton.params(coupon_code="25OFF", index=0)
    ],
)

from pywa.types.templates import *

t = Template(
    name='seasonal_promotion',
    category=TemplateCategory.MARKETING,
    language=TemplateLanguage.ENGLISH_US,
    parameter_format=ParamFormat.NAMED,
    components=[
        header := HeaderText(text='Our {{sale_name}} is on!', sale_name='Summer Sale'),
        body := BodyText(
            text='Shop now through {{end_date}} and use code {{discount_code}} to get {{discount_amount}} off of all merchandise.',
            end_date='the end of August', discount_code='25OFF', discount_amount='25%'
        ),
        FooterText(text='Use the buttons below to manage your marketing subscriptions'),
        Buttons(
            buttons=[
                uns_from_promos := QuickReplyButton(text='Unsubscribe from Promos'),
                uns_from_all := QuickReplyButton(text='Unsubscribe from All'),
            ]
        ),
    ],
)

wa.create_template(template=t)

wa.send_template(
    to='1234567890',
    template=t, # provide the template object to validate parameters against
    params=[
        header.params(sale_name='Summer Sale'),
        body.params(
            end_date='the end of August',
            discount_code='25OFF',
            discount_amount='25%',
        ),
        uns_from_promos.params(callback_data='uns_from_promos'),
        uns_from_all.params(callback_data='uns_from_all'),
    ],
)

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
name (str | None) – The name of the template to send (optional when template is provided).
language (TemplateLanguage | None) – The language of the template to send (optional when template is provided).
template (Template | None) – The template object to validate the parameters against (optional, if not provided, name and language must be provided).
params (list[BaseParams | dict] | None) – The parameters to fill in the template.
use_mm_lite_api (bool) – Whether to use Marketing Messages Lite API (optional, default: False).
message_activity_sharing (bool | None) – Whether to share message activities (e.g. message read) for that specific marketing message to Meta to help optimize marketing messages (optional, only if use_mm_lite_api is True).
reply_to_message_id (str | None) – The ID of the message to reply to (optional).
tracker (str | CallbackData | None) – A callback data to track the message (optional, can be a string or a CallbackData object).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the template from (optional, if not provided, the client’s phone ID will be used).

Return type:

SentTemplate

WhatsApp.send_product(to, catalog_id, sku, body=None, footer=None, *, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Send a product from a business catalog to a WhatsApp user.

To send multiple products, use send_products().
See Product messages.

Example

>>> wa = WhatsApp()
>>> wa.send_product(
...     to='1234567890',
...     catalog_id='1234567890',
...     sku='SKU123',
...     body='Check out this product!',
...     footer='Powered by PyWa',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
catalog_id (str) – The ID of the catalog to send the product from. (To get the catalog ID use get_commerce_settings() or in the Commerce Manager).
sku (str) – The product SKU to send.
body (str | None) – Text to appear in the message body (up to 1024 characters).
footer (str | None) – Text to appear in the footer of the message (optional, up to 60 characters).
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent product message.

Return type:

WhatsApp.send_products(to, catalog_id, product_sections, title, body, footer=None, *, reply_to_message_id=None, tracker=None, identity_key_hash=None, sender=None)#

Send products from a business catalog to a WhatsApp user.

To send a single product, use send_product().
See Product messages.

Example

>>> from pywa.types import ProductsSection
>>> wa = WhatsApp()
>>> wa.send_products(
...     to='1234567890',
...     catalog_id='1234567890',
...     title='Tech Products',
...     body='Check out our products!',
...     product_sections=[
...         ProductsSection(
...             title='Smartphones',
...             skus=['IPHONE12', 'GALAXYS21'],
...         ),
...         ProductsSection(
...             title='Laptops',
...             skus=['MACBOOKPRO', 'SURFACEPRO'],
...         ),
...     ],
...     footer='Powered by PyWa',
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
catalog_id (str) –
The ID of the catalog to send the product from (To get the catalog ID use get_commerce_settings() or in the Commerce Manager).
product_sections (Iterable[ProductsSection]) – The product sections to send (up to 30 products across all sections).
title (str) – The title of the product list (up to 60 characters).
body (str) – Text to appear in the message body (up to 1024 characters).
footer (str | None) – Text to appear in the footer of the message (optional, up to 60 characters).
reply_to_message_id (str | None) – The message ID to quote (optional).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent products message.

Return type:

WhatsApp.send_reaction(to, emoji, message_id, *, tracker=None, identity_key_hash=None, sender=None)#

Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received.

When sending a reaction message, only a MessageStatus update (type set to SENT) will be triggered; DELIVERED and READ updates will not be triggered.
You can react to incoming messages by using the react() method on every update.
See Reaction messages.

>>> wa = WhatsApp()
>>> @wa.on_message
... def message_handler(_: WhatsApp, msg: Message):
...     msg.react('👍')

Example

>>> wa = WhatsApp()
>>> wa.send_reaction(
...     to='1234567890',
...     emoji='👍',
...     message_id='wamid.XXX='
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
emoji (str) – The emoji to react with.
message_id (str) – The message ID to react to.
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent reaction message (You can’t use this message id to remove the reaction or perform any other action on it. instead, use the message ID of the message you reacted to).

Return type:

SentReaction

WhatsApp.remove_reaction(to, message_id, *, tracker=None, identity_key_hash=None, sender=None)#

Remove reaction from a message.

You can remove reactions from incoming messages by using the unreact() method on every update.
See Reaction messages.

>>> wa = WhatsApp()
>>> @wa.on_message
... def message_handler(_: WhatsApp, msg: Message):
...     msg.react('👍')
...     msg.unreact()

Example

>>> wa = WhatsApp()
>>> wa.remove_reaction(
...     to='1234567890',
...     message_id='wamid.XXX='
... )

Parameters:

to (str | int) – The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
message_id (str) – The message ID to remove the reaction from.
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data you can use CallbackData).
identity_key_hash (str | None) –
The message would only be delivered if the hash value matches the customer’s current hash (Optional, See Identity Change Check).
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent (un)reaction message (You can’t use this message id to re-react or perform any other action on it. instead, use the message ID of the message you unreacted to).

Return type:

SentReaction

WhatsApp.mark_message_as_read(message_id, *, sender=None)#

When you get a Message, you can use the msg.id value to mark the message as read.

You can mark incoming messages as read by using the mark_as_read() method or indicate typing by using the indicate_typing() method on every update.
It’s good practice to mark an incoming messages as read within 30 days of receipt. Marking a message as read will also mark earlier messages in the thread as read.
Read more about Mark messages as read.

Example

>>> wa = WhatsApp()
>>> wa.mark_message_as_read(message_id='wamid.XXX=')

Parameters:

message_id (str) – The message ID to mark as read.
sender (str | int | None) – The phone ID (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the message was marked as read.

Return type:

WhatsApp.indicate_typing(message_id, *, sender=None)#

When you get a Message, you can use the msg.id value to mark the message as read and display a typing indicator so the WhatsApp user knows you are preparing a response. This is good practice if it will take you a few seconds to respond.

You can indicate typing by using the indicate_typing() method on every update.
The typing indicator will be dismissed once you respond, or after 25 seconds, whichever comes first. To prevent a poor user experience, only display a typing indicator if you are going to respond.
Read more about Typing indicators.

Example

>>> wa = WhatsApp()
>>> wa.indicate_typing(message_id='wamid.XXX=')

Parameters:

message_id (str) – The message ID to mark as read and display a typing indicator.
sender (str | int | None) – The phone ID (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the message was marked as read and the typing indicator was displayed.

Return type:

WhatsApp.listen(to, *, filters=None, cancelers=None, timeout=None)#

Listen to an update.

You can use one of the shortcuts to listen to a specific update type:
- wait_for_reply()
- wait_for_click()
- wait_for_selection()
- wait_for_completion()
- wait_until_read()
- wait_until_delivered()
- wait_until_approved()

Example

try:
    wa.send_message(
        to="123456",
        text="Send me a message",
        buttons=[Button(title="Cancel", callback_data="cancel")]
    )
    update: Message = wa.listen(
        to=UserUpdateListenerIdentifier(sender="123456", recipient="654321"),
        filters=filters.message & filters.text,
        cancelers=filters.callback_button & filters.matches("cancel"),
        timeout=10
    )
    print(update)
except ListenerTimeout:
    print("Listener timed out")
except ListenerCanceled:
    print("Listener was canceled")
except ListenerStopped:
    print("Listener was stopped")

Parameters:

to (BaseListenerIdentifier) – The identifier of the update to listen to.
filters (Filter) – The filters to apply to the update, return the update if the filters pass.
cancelers (Filter) – The filters to cancel the listening, raise ListenerCanceled if the update matches.
timeout (float | None) – The time to wait for the update, raise ListenerTimeout if the time passes

Returns:

The update that passed the filters

Raises:

ListenerTimeout – If the listener timed out
ListenerCanceled – If the listener was canceled by a filter
ListenerStopped – If the listener was stopped manually

Return type:

BaseUpdate

WhatsApp.stop_listening(to, *, reason=None)#

Stop listening to updates for a specific listener

Raising ListenerStopped to the listener

Parameters:

to (BaseListenerIdentifier) – The identifier of the listener to stop
reason (str | None) – The reason to stop listening

Raises:

ValueError – If the listener does not exist

WhatsApp.upload_media(media, mime_type=None, filename=None, dl_session=None, *, ttl=None, download_chunk_size=65536, media_type=None, phone_id=None)#

Upload media to WhatsApp servers.

All media files sent through this endpoint are encrypted and persist for 30 days, unless they are deleted earlier.
You can get media URL with get_media_url() and download it with download_media() or delete it with delete_media().
See Upload media.
See Supported media types.

Example

>>> wa = WhatsApp()
>>> wa.upload_media(media='https://example.com/image.jpg')

>>> wa.upload_media(media=pathlib.Path('image.jpg'))
>>> wa.upload_media(media="/path/to/image.jpg")

>>> wa.upload_media(
...     media=b'...binary data...',
...     mime_type='image/jpeg',
...     filename='image.jpg',
... )

>>> with wa.upload_media("https://my-cdn.com/sensitive-image.png") as media: # will be deleted after use
...     wa.send_image(to=..., image=media)

Parameters:

media (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The media to upload (can be a URL, file path, bytes, bytes generator, file-like object, base64 or a Media instance).
mime_type (str | None) – The MIME type of the media.
filename (str | None) – The file name of the media.
ttl (timedelta | int | None) – Override the default 1-hour TTL for No Storage-enabled business phone numbers. This value is in minutes from 1 hour (60) to 30 days (43200).
dl_session (Client | None) – A httpx client to use when downloading the media from a URL (optional, for custom settings like proxies, headers, etc. If not provided, a new client will be created for the download).
download_chunk_size (int) – The size (in bytes) of each chunk to download when downloading media from a URL (default: 64KB). Defines the size of data read into memory at a time.
media_type (Literal['image', 'video', 'audio', 'document', 'sticker'] | None) – The type of the media (optional, for default mimetype and filename).
phone_id (str | int | None) – The phone ID to upload the media to (optional, if not provided, the client’s phone ID will be used).

Returns:

The uploaded media.

Return type:

Media

WhatsApp.download_media(*, url, path=None, filename=None, chunk_size=65536, **httpx_kwargs)#

Download a media file from WhatsApp servers.

Use get_media_url() to get the media URL from a media ID.
Use download_media() to download media directly from a message.
Use get_media_bytes() to get the media as bytes.
Use stream_media() to stream the media as bytes.
See Download media.

Example

>>> wa = WhatsApp()
>>> wa.download_media(
...     url='https://mmg-fna.whatsapp.net/d/f/Amc.../v2/1234567890',
...     path=pathlib.Path('/path/to/save'),
...     filename='image.jpg',
... )

Parameters:

url (str) – The URL of the media file.
path (str | Path | None) – The path where to save the file (if not provided, the current working directory will be used).
filename (str | None) – The name of the file to save (if not provided, it will be extracted from the Content-Disposition header or a SHA256 hash of the URL will be used).
chunk_size (int) – The size (in bytes) of each chunk to read when downloading the media (default: 64KB).
**httpx_kwargs (Any) – Additional arguments to pass to httpx.get().

Returns:

The path of the saved file.

Return type:

Path

WhatsApp.stream_media(url, *, chunk_size=65536, **httpx_kwargs)#

Stream media file as bytes from WhatsApp servers.

Use get_media_url() to get the media URL from a media ID.
Use stream_media() to stream the media directly from a message.
Use download_media() to download the media to a file.
Use get_media_bytes() to get the media as bytes.
See Download media.

Example

>>> wa = WhatsApp()
>>> with httpx.Client() as client:
>>>    client.post("https://my-server.com/upload", content=wa.stream_media()) # streaming upload

Parameters:

url (str) – The URL of the media file.
chunk_size (int) – The size (in bytes) of each chunk to read (default: 64KB).
**httpx_kwargs (Any) – Additional arguments to pass to httpx.get().

Return type:

Generator[bytes]

WhatsApp.get_media_bytes(url, **httpx_kwargs)#

Get media file as bytes from WhatsApp servers.

Use get_media_url() to get the media URL from a media ID.
Use get_media_bytes() to get the media directly from a message.
Use download_media() to download the media to a file.
Use stream_media() to stream the media as bytes.
See Download media.

Example

>>> wa = WhatsApp()
>>> media_bytes = wa.get_media_bytes(
...     url='https://mmg-fna.whatsapp.net/d/f/Amc.../v2/1234567890',
... )

Parameters:

url (str) – The URL of the media file.
**httpx_kwargs (Any) – Additional arguments to pass to :py:func:`httpx.get

Returns:

The media file as bytes.

Return type:

bytes

WhatsApp.get_media_url(media_id)#

Get a media URL for a media ID.

Note that clicking this URL (i.e. performing a generic GET) will not return the media; you must include an access token. Use the download_media() method to download the media.
The media can be downloaded directly from the message using the download_media() method.
The URL is valid for 5 minutes.
See Retrieve Media URL.

Example

>>> wa = WhatsApp()
>>> wa.get_media_url(media_id='wamid.XXX=')

Parameters:: media_id (str | int) – The media ID.
Returns:: A MediaURL object with the media URL.
Return type:: MediaURL

WhatsApp.delete_media(media_id, *, phone_id=<object object>)#

Delete a media file from WhatsApp servers.

See Delete media.

Example

>>> wa = WhatsApp()
>>> wa.delete_media(media_id='wamid.XXX=')

Parameters:

media_id (str) – The media ID to delete.
phone_id (str | int | None) – The phone ID to delete the media from (optional, If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on. pass None to use the client’s phone ID).

Returns:

Whether the media was deleted successfully.

Return type:

Result[BusinessPhoneNumber]

WhatsApp.get_business_account(*, waba_id=None)#

Get the WhatsApp Business Account (WABA) information.

Parameters:: waba_id (str | int | None) – The WABA ID to get the information from (optional, if not provided, the client’s WABA ID will be used).
Returns:: The WhatsApp Business Account object.
Return type:: WhatsAppBusinessAccount

WhatsApp.update_business_account_settings(*, disable_marketing_messages_on_cloud_api=None, degrees_of_freedom_spec=None, waba_id=None)#

Update the WhatsApp Business Account (WABA) settings.

Example

>>> wa = WhatsApp()
>>> wa.update_business_account_settings(disable_marketing_messages_on_cloud_api=True)

Parameters:

disable_marketing_messages_on_cloud_api (bool | None) – Whether to block Marketing category templates on the Cloud API /messages endpoint (in pywa it means that when you send_template() a MARKETING template you must set use_mm_lite_api to True).
degrees_of_freedom_spec (DegreesOfFreedomSpec | None) – Configure automatic creative optimizations for message templates. Read more at developers.facebook.com.
waba_id (str | int | None) – The WABA ID to update the settings for (optional, if not provided, the client’s WABA ID will be used).

WhatsApp.get_business_profile(*, phone_id=None)#

Get the business profile of the phone number.

Example

>>> wa = WhatsApp()
>>> wa.get_business_profile()

Parameters:: phone_id (str | int | None) – The phone ID to get the business profile from (optional, if not provided, the client’s phone ID will be used).
Returns:: The business profile.
Return type:: BusinessProfile

WhatsApp.get_business_phone_numbers(*, waba_id=None, pagination=None)#

Get the phone numbers of the WhatsApp Business account.

Example

>>> wa = WhatsApp()
>>> for phone_number in wa.get_business_phone_numbers():
...     print(phone_number)

Parameters:

waba_id (str | int | None) – The WABA ID to get the phone numbers from (optional, if not provided, the client’s WABA ID will be used).
pagination (Pagination | None) – Pagination object to paginate through the results (optional).

Returns:

A Result object containing BusinessPhoneNumber objects.

Return type:

WhatsApp.get_business_phone_number(*, phone_id=None)#

Get the phone number details.

Example

>>> wa = WhatsApp()
>>> wa.get_business_phone_number()

Parameters:: phone_id (str | int | None) – The phone ID to get the phone number from (optional, if not provided, the client’s phone ID will be used).
Returns:: The phone number object.
Return type:: BusinessPhoneNumber

WhatsApp.get_business_phone_number_settings(*, include_sip_credentials=None, phone_id=None)#

Get the settings of the WhatsApp Business phone number.

Example

>>> wa = WhatsApp()
>>> wa.get_business_phone_number_settings()

Parameters:

include_sip_credentials (bool | None) – Whether to include SIP credentials in the response (optional, default: False).
phone_id (str | int | None) – The phone ID to get the settings from (optional, if not provided, the client’s phone ID will be used).

Returns:

The business phone number settings.

Return type:

BusinessPhoneNumberSettings

WhatsApp.update_business_phone_number_settings(*, calling=None, storage_configuration=None, user_identity_change=None, phone_id=None)#

Update the settings of the WhatsApp Business phone number.

Example

>>> from pywa.types.calls import CallingSettingsStatus
>>> wa = WhatsApp()
>>> s = wa.get_business_phone_number_settings()
>>> s.calling.status = CallingSettingsStatus.ENABLED
>>> wa.update_business_phone_number_settings(calling=s.calling)

Parameters:

calling (CallingSettings | None) – The calling settings to update (optional).
storage_configuration (StorageConfiguration | None) – The storage configuration to update (optional).
user_identity_change (UserIdentityChangeSettings | None) – The user identity change settings to update (optional).
phone_id (str | int | None) – The phone ID to update the settings for (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the settings were updated successfully.

Return type:

WhatsApp.update_business_profile(*, about=<object object>, address=<object object>, description=<object object>, email=<object object>, profile_picture=<object object>, industry=<object object>, websites=<object object>, phone_id=None, app_id=None)#

Update the business profile of the phone number.

Example

>>> from pywa.types import Industry
>>> wa = WhatsApp()
>>> wa.update_business_profile(
...     about='This is a test business',
...     address='Menlo Park, 1601 Willow Rd, United States',
...     description='This is a test business',
...     email='test@test.com',
...     profile_picture='path/to/profile.jpg',
...     industry=Industry.NOT_A_BIZ,
...     websites=['https://example.com', 'https://google.com'],
... )

Parameters:

about (str | None) –
The business’s About text. This text appears in the business’s profile, beneath its profile image, phone number, and contact buttons. (cannot be empty. must be between 1 and 139 characters. markdown is not supported. Hyperlinks can be included but will not render as clickable links.)
address (str | None) – Address of the business. Character limit 256.
description (str | None) – Description of the business. Character limit 512.
email (str | None) – The contact email address (in valid email format) of the business. Character limit 128.
profile_picture (str | int | Media | Path | bytes | BinaryIO | Iterator[bytes]) – The profile picture to set for the business (can be a media ID, URL, file path, bytes, bytes generator, or file-like object).
industry (Industry | None) – Industry of the business.
websites (Iterable[str] | None) – The URLs associated with the business. For instance, a website, Facebook Page, or Instagram. (You must include the http:// or https:// portion of the URL. There is a maximum of 2 websites with a maximum of 256 characters each.)
phone_id (str | int | None) – The phone ID to update the business profile for (optional, if not provided, the client’s phone ID will be used).
app_id (str | int | None) – The App ID to upload the profile picture to (optional, if not provided, the client’s app ID will be used).

Returns:

Whether the business profile was updated.

Return type:

WhatsApp.update_display_name(new_display_name, *, phone_id=None)#

Update the display name of the WhatsApp Business phone number.

The display name is the name that appears in the WhatsApp app for your business.
The display name will undergo verification by WhatsApp, and you will receive a webhook notification when the verification is complete.
Read more about Display Name Verification.

Example

>>> wa = WhatsApp()
>>> wa.update_display_name(new_display_name="Pizza Bot")

Parameters:

new_display_name (str) – The new display name.
phone_id (str | int | None) – The phone ID to update the display name for (optional, if not provided, the client’s phone ID will be used).

Return type:

WhatsApp.update_conversational_automation(ice_breakers=None, commands=None, *, phone_id=None)#

Update the conversational automation settings of the WhatsApp Business phone number.

You can receive the current conversational automation settings using get_business_phone_number() and accessing the conversational_automation attribute.

Read more about Conversational Automation.

>>> from pywa.types import Command
>>> wa = WhatsApp()
>>> wa.update_conversational_automation(
...     ice_breakers=['Plan a trip', 'Create a workout plan'],
...     commands=[
...         Command(
...             command='start',
...             description='Start a new conversation',
...         ),
...         Command(
...             command='help',
...             description='Get help with the bot',
...         ),
...     ],
... )

Parameters:

ice_breakers (Iterable[str] | None) – Ice Breakers are customizable, tappable text strings that appear in a message thread the first time you chat with a user. For example, Plan a trip or Create a workout plan.
commands (Iterable[Command] | None) – Commands are text strings that WhatsApp users can see by typing a forward slash in a message thread with your business.
phone_id (str | int | None) – The phone ID to update the conversational automation settings for (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the conversational automation settings were updated.

Return type:

WhatsApp.set_business_public_key(public_key, *, phone_id=None)#

Set the business public key of the phone number (required for end-to-end encryption in flows)

Parameters:

public_key (str) – An public 2048-bit RSA Key in PEM format.
phone_id (str | int | None) – The phone ID to set the business public key for (optional, if not provided, the client’s phone ID will be used).

Return type:

Example

>>> wa = WhatsApp()
>>> wa.set_business_public_key(
...     public_key="""-----BEGIN PUBLIC KEY-----..."""
... )

Returns:: Whether the business public key was set.
Return type:: SuccessResult

WhatsApp.get_commerce_settings(*, phone_id=None)#

Get the commerce settings of the WhatsApp Business phone number.

Example

>>> wa = WhatsApp()
>>> wa.get_commerce_settings()

Parameters:: phone_id (str | int | None) – The phone ID to get the commerce settings from (optional, if not provided, the client’s phone ID will be used).
Returns:: The commerce settings.
Return type:: CommerceSettings

WhatsApp.update_commerce_settings(is_catalog_visible=None, is_cart_enabled=None, *, phone_id=None)#

Update the commerce settings of the WhatsApp Business phone number.

Example

>>> wa = WhatsApp()
>>> wa.update_commerce_settings(
...     is_catalog_visible=True,
...     is_cart_enabled=True,
... )

Parameters:

is_catalog_visible (bool) – Whether the catalog is visible (optional).
is_cart_enabled (bool) – Whether the cart is enabled (optional).
phone_id (str | int | None) – The phone ID to update the commerce settings for (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the commerce settings were updated.

Raises:

ValueError – If no arguments are provided.

Return type:

WhatsApp.create_template(template, *, waba_id=None, app_id=None)#

Create a template for the WhatsApp Business account.

WhatsApp Business Accounts can only create 100 message templates per hour.
Read more about Create and Manage Templates.

Example:

from pywa.types import template as t

wa = WhatsApp(..., waba_id='1234567890')

created = wa.create_template(
    template=t.Template(
        name='seasonal_promotion',
        category=t.TemplateCategory.MARKETING,
        language=t.TemplateLanguage.ENGLISH_US,
        parameter_format=t.ParamFormat.NAMED,
        components=[
            t.HeaderText(text='Our {{sale_name}} is on!', sale_name='Summer Sale'),
            t.BodyText(
                text='Shop now through {{end_date}} and use code {{discount_code}} to get {{discount_amount}} off of all merchandise.',
                end_date='the end of August', discount_code='25OFF', discount_amount='25%'
            ),
            t.FooterText(text='Use the buttons below to manage your marketing subscriptions'),
            t.Buttons(
                buttons=[
                    t.QuickReplyButton(text='Unsubscribe from Promos'),
                    t.QuickReplyButton(text='Unsubscribe from All'),
                ]
            ),
        ],
    ),

    print('Template created:', created.id, created.status)

Parameters:

template (Template | LibraryTemplate) – The template to create.
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID, optional).
app_id (str | int | None) – The App ID to upload the template header example media to (optional, if not provided, the client’s app ID will be used).

Returns:

The created template.

Return type:

CreatedTemplate

WhatsApp.upsert_authentication_template(*, name, languages, otp_button, add_security_recommendation=None, code_expiration_minutes=None, message_send_ttl_seconds=None, waba_id=None)#

Bulk update or create authentication templates in multiple languages that include or exclude the optional security and expiration warnings.

If a template already exists with a matching name and language, the template will be updated with the contents of the request, otherwise, a new template will be created.
You can’t provide the text or autofill_text properties for the OTP Buttons. It will be automatically set to a pre-set value localized to the template’s language. For example, Copy Code for English (US) and Autofill for English (US).
Read more at developers.facebook.com.
Read more about Authentication Templates.

Example

>>> from pywa.types.templates import *
>>> wa = WhatsApp()
>>> templates = wa.upsert_authentication_template(
...     name='one_tap_authentication',
...     languages=[TemplateLanguage.ENGLISH_US, TemplateLanguage.FRENCH, TemplateLanguage.SPANISH],
...     otp_button=OneTapOTPButton(supported_apps=...),
...     add_security_recommendation=True,
...     code_expiration_minutes=5,
... )
... for template in templates:
...     print(f'Template {template.id} created with status {template.status}')

Parameters:

name (str) – The name of the template (should be unique, maximum 512 characters).
languages (Iterable[TemplateLanguage]) – A list of languages and locale codes to create or update the template in (See Supported Languages).
otp_button (BaseOTPButton) – A OneTapOTPButton, ZeroTapOTPButton, or CopyCodeOTPButton button.
add_security_recommendation (bool | None) – Boolean value to add information to the template about not sharing authentication codes with anyone.
code_expiration_minutes (int | None) – Integer value to add information to the template on when the code will expire.
message_send_ttl_seconds (int | None) – The time-to-live (TTL) for the template message in seconds. (See Time-to-live (TTL)).
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID, optional).

Returns:

A CreatedTemplates object containing the created or updated templates.

Return type:

CreatedTemplates

WhatsApp.update_template(template_id, *, new_category=None, new_components=None, new_message_send_ttl_seconds=None, new_parameter_format=None, app_id=None)#

Update an existing template.

Only templates with an APPROVED, REJECTED, or PAUSED status can be edited.
You cannot edit the category of an approved template.
Approved templates can be edited up to 10 times in a 30 day window, or 1 time in a 24 hour window. Rejected or paused templates can be edited an unlimited number of times.
After editing an approved or paused template, it will automatically be approved unless it fails template review.
Read more at developers.facebook.com.

Example

>>> from pywa.types.templates import *
>>> wa = WhatsApp()
>>> updated_template = wa.update_template(
...     template_id='1234567890',
...     new_category=TemplateCategory.MARKETING,
...     new_components=[...],
...     new_message_send_ttl_seconds=3600
... )

Parameters:

template_id (int | str) – The ID of the template to update.
new_category (TemplateCategory | None) – The new category of the template (optional, cannot be changed for approved templates).
new_components (list[TemplateBaseComponent] | None) – The new components of the template (optional, if not provided, the existing components will be used).
new_message_send_ttl_seconds (int | None) – The new message send TTL in seconds (optional, if not provided, the existing TTL will be used).
new_parameter_format (ParamFormat | None) – The new parameter format (optional, if not provided, the existing format will be used).
app_id (str | int | None) – The App ID to upload the template header example media to (optional, if not provided, the client’s app ID will be used).

Returns:

Whether the template was updated successfully.

Return type:

UpdatedTemplate

WhatsApp.get_template(template_id)#

Get the details of a specific template.

Example

>>> wa = WhatsApp()
>>> template_details = wa.get_template(template_id='1234567890')

Parameters:: template_id (int | str) – The ID of the template to retrieve.
Returns:: A TemplateDetails object containing the template details.
Return type:: TemplateDetails

WhatsApp.get_templates(*, statuses=None, categories=None, languages=None, name=None, content=None, name_or_content=None, quality_scores=None, pagination=None, waba_id=None)#

Get templates of the WhatsApp Business account.

Example

>>> wa = WhatsApp()
>>> templates = wa.get_templates(
...     statuses=[TemplateStatus.APPROVED],
...     categories=[TemplateCategory.MARKETING],
...     languages=[TemplateLanguage.ENGLISH_US],
...     pagination=Pagination(limit=10)
... )
>>> for template in templates:
...     print(f'Template {template.id} - {template.name}: {template}')

Parameters:

statuses (Iterable[TemplateStatus] | None) – The statuses of the templates to filter by (optional).
categories (Iterable[TemplateCategory] | None) – The categories of the templates to filter by (optional).
languages (Iterable[TemplateLanguage] | None) – The languages of the templates to filter by (optional).
name (str | None) – The name (or part of it) of the template to filter by (optional).
content (str | None) – The content of the template to filter by (optional).
name_or_content (str | None) – The name or content of the template to filter by (optional).
quality_scores (Iterable[QualityScoreType] | None) – The quality scores of the templates to filter by (optional).
pagination (Pagination | None) – Pagination parameters (optional).
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID, optional).

Returns:

A Result object containing the templates

Return type:

TemplatesResult

WhatsApp.delete_template(template_name, *, template_id=None, waba_id=None)#

Delete a template.

If you delete a template that has been sent in a template message but has yet to be delivered (e.g. because the customer’s phone is turned off), the template’s status will be set to PENDING_DELETION and we will attempt to deliver the message for 30 days. After this time you will receive a “Structure Unavailable” error and the customer will not receive the message.
Names of an approved template that has been deleted cannot be used again for 30 days.
Deleting a template by name deletes all templates that match that name (meaning templates with the same name but different languages will also be deleted).
To delete a template by ID, include the template’s ID along with its name in your request; only the template with the matching template ID will be deleted.
Read more at developers.facebook.com.

Example

>>> wa = WhatsApp()
>>> wa.delete_template(template_name='seasonal_promotion') # Deletes all templates with that name
>>> wa.delete_template(template_name='seasonal_promotion', template_id='1234567890') # Deletes only the template with that ID

Parameters:

template_name (str) – The name of the template to delete.
template_id (int | str | None) – The ID of the template to delete (optional, if provided, only the template with the matching ID will be deleted).
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID, optional).

Returns:

Whether the template was deleted successfully.

Return type:

WhatsApp.unpause_template(template_id)#

Unpause a template that has been paused due to pacing.

You must wait 5 minutes after a template has been paused as a result of pacing before calling this method.
Read more at developers.facebook.com.

Parameters:: template_id (int | str) – The ID of the template to unpause.
Returns:: A TemplateUnpauseResult object containing the result of the unpause operation.
Return type:: TemplateUnpauseResult

WhatsApp.compare_templates(template_id, *template_ids, start, end)#

You can compare two templates by examining how often each one is sent, which one has the lower ratio of blocks to sends, and each template’s top reason for being blocked.

Only two templates can be compared at a time.
Both templates must be in the same WhatsApp Business Account.
Templates must have been sent at least 1,000 times in the queries specified timeframe.
Timeframes are limited to 7, 30, 60 and 90 day lookbacks from the time of the request.
Read more at developers.facebook.com.

Example

>>> wa = WhatsApp()
>>> now = datetime.datetime.now()
>>> result = wa.compare_templates(
...     '1234567890', '0987654321',
...     start=now - datetime.timedelta(days=30), end=now # Compare templates sent in the last 30 days
... )

Parameters:

template_id (int | str) – The ID of the template to compare against others.
template_ids (int | str) – The IDs of the templates to compare with the given template.
start (datetime | int) – The start date of the comparison period.
end (datetime | int) – The end date of the comparison period.

Returns:

A TemplatesCompareResult object containing the comparison results.

Return type:

TemplatesCompareResult

WhatsApp.migrate_templates(source_waba_id, page_number=None, *, destination_waba_id=None)#

Migrate templates from one WhatsApp Business account to another.

Templates can only be migrated between WABAs owned by the same Meta business.
Only templates with a status of APPROVED and a quality_score of either GREEN or UNKNOWN are eligible for migration.
Read more at developers.facebook.com.

Parameters:

source_waba_id (str | int) – The WhatsApp Business account ID to migrate templates from.
page_number (int | None) – Indicates amount of templates to migrate as sets of 500. Zero-indexed. For example, to migrate 1000 templates, send one request with this value set to 0 and another request with this value set to 1, in parallel.
destination_waba_id (str | int | None) – The WhatsApp Business account ID to migrate templates to (optional, overrides the client’s business account ID).

Returns:

A MigrateTemplatesResult object containing the migration results.

Return type:

MigrateTemplatesResult

WhatsApp.create_flow(name, categories, *, clone_flow_id=None, endpoint_uri=None, flow_json=None, publish=None, waba_id=None)#

Create a flow.

This method requires the WhatsApp Business account ID to be provided when initializing the client.
New Flows are created in FlowStatus.DRAFT status unless flow_json is provided and publish is True.
To update the flow json, use update_flow().
To send a flow, use send_flow().

Parameters:

name (str) – The name of the flow (must be unique, can be used later to update and send the flow).
categories (Iterable[FlowCategory | str]) – The categories of the flow.
flow_json (FlowJSON | dict | str | Path | bytes | BinaryIO | None) – The JSON of the flow (optional, if provided, the flow will be created with the provided JSON).
publish (bool | None) – Whether to publish the flow after creating it, only works if flow_json is provided.
clone_flow_id (str | None) – The flow ID to clone (optional).
endpoint_uri (str | None) – The URL of the FlowJSON Endpoint. Starting from Flow 3.0 this property should be specified only gere. Do not provide this field if you are cloning a Flow with version below 3.0.
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID).

Return type:

CreatedFlow

Example

>>> from pywa.types.flows import *
>>> wa = WhatsApp()
>>> wa.create_flow(
...     name='Feedback',
...     categories=[FlowCategory.SURVEY, FlowCategory.OTHER],
...     flow_json=FlowJSON(...),
...     publish=True,
... )

Returns:: The created flow.
Raises:: FlowBlockedByIntegrity – If you can’t create a flow because of integrity issues.
Return type:: CreatedFlow

WhatsApp.update_flow_metadata(flow_id, *, name=None, categories=None, endpoint_uri=None, application_id=None)#

Update the metadata of a flow.

Parameters:

flow_id (str | int) – The flow ID.
name (str | None) – The name of the flow (optional).
categories (Iterable[FlowCategory | str] | None) – The new categories of the flow (optional).
endpoint_uri (str | None) – The URL of the FlowJSON Endpoint. Starting from FlowJSON 3.0 this property should be specified only gere. Do not provide this field if you are cloning a FlowJSON with version below 3.0.
application_id (int | None) – The ID of the Meta application which will be connected to the Flow. All the flows with endpoints need to have an Application connected to them.

Return type:

Example

>>> from pywa.types.flows import FlowCategory
>>> wa = WhatsApp()
>>> wa.update_flow_metadata(
...     flow_id='1234567890',
...     name='Feedback',
...     categories=[FlowCategory.SURVEY, FlowCategory.OTHER],
...     endpoint_uri='https://my-api-server/feedback_flow',
...     application_id=1234567890,
... )

Returns:: Whether the flow was updated.
Raises:: ValueError – If neither of the arguments is provided.
Return type:: SuccessResult

WhatsApp.update_flow_json(flow_id, flow_json)#

Update the json of a flow.

Parameters:

flow_id (str | int) – The flow ID.
flow_json (FlowJSON | dict | str | Path | bytes | BinaryIO) – The new json of the flow. Can be a FlowJSON object, dict, json string, json file path or json bytes.

Return type:

FlowJSONUpdateResult

Examples

>>> wa = WhatsApp()

Using a Flow object:

>>> from pywa.types.flows import *
>>> wa.update_flow_json(
...     flow_id='1234567890',
...     flow_json=FlowJSON(version='7.1', screens=[Screen(...)])
... )

From a json file path:

>>> wa.update_flow_json(
...     flow_id='1234567890',
...     flow_json="/home/david/feedback_flow.json"
... )

From a json string:

>>> wa.update_flow_json(
...     flow_id='1234567890',
...     flow_json="""{"version": "2.1", "screens": [...]}"""
... )

Returns:: A tuple of (success, validation_errors).
Raises:: FlowUpdatingError – If the flow json is invalid or the flow is already published.
Return type:: FlowJSONUpdateResult

WhatsApp.publish_flow(flow_id)#

This request updates the status of the Flow to “PUBLISHED”.

This action is not reversible.
The Flow and its assets become immutable once published.
To update the Flow after that, you must create a new Flow. You specify the existing Flow ID as the clone_flow_id parameter while creating to copy the existing flow.
You can publish your Flow once you have ensured that:
- All validation errors and publishing checks have been resolved.
- The Flow meets the design principles of WhatsApp Flows
- The Flow complies with WhatsApp Terms of Service, the WhatsApp Business Messaging Policy and, if applicable, the WhatsApp Commerce Policy

Parameters:: flow_id (str | int) – The flow ID.
Returns:: Whether the flow was published.
Raises:: FlowPublishingError – If the flow has validation errors or not all publishing checks have been resolved.
Return type:: SuccessResult

WhatsApp.delete_flow(flow_id)#

While a Flow is in DRAFT status, it can be deleted.

Parameters:: flow_id (str | int) – The flow ID.
Returns:: Whether the flow was deleted.
Raises:: FlowDeletingError – If the flow is already published.
Return type:: SuccessResult

WhatsApp.deprecate_flow(flow_id)#

Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated.

Parameters:: flow_id (str | int) – The flow ID.
Returns:: Whether the flow was deprecated.
Raises:: FlowDeprecatingError – If the flow is not published or already deprecated.
Return type:: SuccessResult

WhatsApp.get_flow(flow_id, *, invalidate_preview=True, phone_number_id=None)#

Get the details of a flow.

Parameters:

flow_id (str | int) – The flow ID.
invalidate_preview (bool) – Whether to invalidate the preview (optional, default: True).
phone_number_id (str | int | None) – To check that a flow can be used with a specific phone number (optional).

Returns:

The details of the flow.

Return type:

FlowDetails

WhatsApp.get_flows(*, invalidate_preview=True, phone_number_id=None, pagination=None, waba_id=None)#

Get the flows associated with the WhatsApp Business account.

This method requires the WhatsApp Business account ID to be provided when initializing the client.

Example

>>> wa = WhatsApp()
>>> flows = wa.get_flows(
...     invalidate_preview=True,
...     phone_number_id='1234567890',
...     pagination=Pagination(limit=10)
... )
... for flow in flows:
...     print(f'Flow {flow.id} - {flow.name}: {flow}')

Parameters:

invalidate_preview (bool) – Whether to invalidate the preview (optional, default: True).
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID).
phone_number_id (str | int | None) – To check that the flows can be used with a specific phone number (optional).
pagination (Pagination | None) – The pagination parameters (optional).

Returns:

Result object containing the flows.

Return type:

Result[FlowDetails]

WhatsApp.get_flow_metrics(flow_id, metric_name, granularity, *, since=None, until=None)#

Get the metrics of a flow.

Read more at developers.facebook.com.

Parameters:

flow_id (str | int) – The flow ID.
metric_name (FlowMetricName) – See Available Metrics.
granularity (FlowMetricGranularity) – Time granularity.
since (date | str | None) – Start of the time period. If not specified, the oldest allowed date will be used. Oldest allowed date depends on the specified time granularity: DAY - 90 days, HOUR - 30 days.
until (date | str | None) – End of the time period. If not specified, the current date will be used.

Return type:

dict

Returns:

WhatsApp.get_flow_assets(flow_id, *, pagination=None)#

Get assets attached to a specified Flow.

Parameters:

flow_id (str | int) – The flow ID.
pagination (Pagination | None) – The pagination parameters (optional).

Returns:

Result object containing the assets of the flow.

Return type:

Result[FlowAsset]

WhatsApp.migrate_flows(source_waba_id, source_flow_names, *, destination_waba_id=None)#

Migrate flows from one WhatsApp Business Account to another.

Parameters:

source_waba_id (str | int) – The source WhatsApp Business Account ID.
source_flow_names (Iterable[str]) – The names of the flows to migrate.
destination_waba_id (str | int | None) – The destination WhatsApp Business Account ID (optional, if not provided, the client’s business account ID will be used).

Returns:

The response of the migration request.

Return type:

MigrateFlowsResponse

WhatsApp.block_users(users, *, phone_id=None)#

Block users from sending messages to the WhatsApp Business account.

Read more at developers.facebook.com.
You can block users with the block() or block_sender() shortcuts.

When you block a WhatsApp user, the following happens:

The user cannot contact your business or see that you are online.
Your business cannot message the user. If you do, you will encounter an error.
You can only block users that have messaged your business in the last 24 hours.
64k blocklist limit

Example

>>> wa = WhatsApp()
>>> res = wa.block_users(users=['1234567890', '0987654321'])
>>> if res.errors: print(res.failed_users)

Parameters:

users (Iterable[str | int]) – The phone numbers/wa IDs of the users to block.
phone_id (str | int | None) – The phone ID to block the users from (optional, if not provided, the client’s phone ID will be used).

Returns:

A UsersBlockedResult object with the status of the block operation.

Return type:

UsersBlockedResult

WhatsApp.unblock_users(users, *, phone_id=None)#

Unblock users that were previously blocked from sending messages to the WhatsApp Business account.

Read more at developers.facebook.com.

Example

>>> wa = WhatsApp()
>>> res = wa.unblock_users(users=['1234567890', '0987654321'])
>>> print(res.removed_users)

Parameters:

users (Iterable[str | int]) – The phone numbers/wa IDs of the users to unblock.
phone_id (str | int | None) – The phone ID to unblock the users from (optional, if not provided, the client’s phone ID will be used).

Returns:

A UsersUnblockedResult object with the status of the unblock operation.

Return type:

UsersUnblockedResult

WhatsApp.get_blocked_users(*, pagination=None, phone_id=None)#

Get blocked users.

Example

>>> wa = WhatsApp()
>>> for user in wa.get_blocked_users(): print(user)

Parameters:

pagination (Pagination | None) – The pagination parameters (optional).
phone_id (str | int | None) – The phone ID to get the list of blocked users from (optional, if not provided, the client’s phone ID will be used).

Returns:

A Result object with the list of blocked users. You can iterate over the result to get the users.

Return type:

Result[BlockedUser]

WhatsApp.register_phone_number(pin, *, data_localization_region=None, phone_id=None)#

Read more at developers.facebook.com

Example

>>> wa = WhatsApp()
>>> wa.register_phone_number(password='111111', data_localization_region='US')

Parameters:

pin (int | str) – If your verified business phone number already has two-step verification enabled, set this value to your number’s 6-digit two-step verification PIN. If you cannot recall your PIN, you can uptdate it.
data_localization_region (str | None) – If included, enables local storage on the business phone number. Value must be a 2-letter ISO 3166 country code (e.g. IN) indicating the country where you want data-at-rest to be stored.
phone_id (str | int | None) – The phone ID to register (optional, if not provided, the client’s phone ID will be used).

Returns:

The success of the registration.

Return type:

WhatsApp.deregister_phone_number(*, phone_id=None)#

Deregister a Business Phone Number.

Read more at developers.facebook.com

Parameters:: phone_id (str | int | None) – The phone ID to deregister (optional, if not provided, the client’s phone ID will be used).
Returns:: The success of the deregistration.
Return type:: SuccessResult

WhatsApp.create_phone_number(*, country_calling_code, phone_number, verified_name, waba_id=None)#

Create a phone number on a WhatsApp Business Account.

Read more at developers.facebook.com.

Parameters:

country_calling_code (str | int) – The phone number’s country calling code (e.g. “1”).
phone_number (str | int) – The phone number, with or without the country calling code.
verified_name (str) – The phone number’s display name.
waba_id (str | int | None) – The WhatsApp Business account ID to create the phone number on (optional, if not provided, the client’s business account ID will be used).

Returns:

The created phone number.

Return type:

CreatedBusinessPhoneNumber

WhatsApp.request_verification_code(*, code_method, language_code, phone_id=None)#

Request a verification code for a phone number.

Read more at developers.facebook.com.

Parameters:

code_method (Literal['SMS', 'VOICE']) – Chosen method for verification. Supported options are “SMS”/”VOICE”
language_code (str) – The language’s two-character language code. For example: “en”.
phone_id (str | int | None) – The phone ID to create the verification code for (optional, if not provided, the client’s phone ID will be used).

Returns:

The success of the request.

Return type:

WhatsApp.verify_phone_number(code, phone_id=None)#

Verify a phone number with the code received by the user.

Read more at developers.facebook.com.

Parameters:

code (str) – The verification code received by the user.
phone_id (str | int | None) – The phone ID to verify the code for (optional, if not provided, the client’s phone ID will be used).

Returns:

The success of the request.

Return type:

WhatsApp.create_qr_code(prefilled_message, image_type=QRCodeImageType.PNG, *, phone_id=None)#

Create a QR code for a prefilled message.

Read more at developers.facebook.com

Parameters:

prefilled_message (str) – The prefilled message.
image_type (QRCodeImageType | Literal['PNG', 'SVG']) – The type of the image (PNG or SVG. Default: PNG).
phone_id (str | int | None) – The phone ID to create the QR code for (optional, if not provided, the client’s phone ID will be used).

Returns:

The QR code.

Return type:

QRCode

WhatsApp.get_qr_code(code, *, image_type=None, phone_id=None)#

Get a QR code.

Parameters:

code (str) – The QR code.
image_type (QRCodeImageType | Literal['PNG', 'SVG'] | None) – The type of the image. if not provided, the image URL will not be returned (faster response).
phone_id (str | int | None) – The phone ID to get the QR code for (optional, if not provided, the client’s phone ID will be used).

Returns:

The QR code if found, otherwise None.

Return type:

QRCode | None

WhatsApp.get_qr_codes(*, image_type=None, phone_id=None, pagination=None)#

Get QR codes associated with the WhatsApp Phone Number.

Parameters:

image_type (QRCodeImageType | Literal['PNG', 'SVG'] | None) – The type of the image. If not provided, the image URL will not be returned (faster response).
phone_id (str | int | None) – The phone ID to get the QR codes for (optional, if not provided, the client’s phone ID will be used).
pagination (Pagination | None) – The pagination parameters (optional).

Returns:

Result object containing the QR codes.

Return type:

Result[QRCode]

WhatsApp.update_qr_code(code, prefilled_message, *, phone_id=None)#

Update a QR code.

Parameters:

code (str) – The QR code.
prefilled_message (str) – The prefilled message.
phone_id (str | int | None) – The phone ID to update the QR code for (optional, if not provided, the client’s phone ID will be used).

Returns:

The updated QR code.

Return type:

QRCode

WhatsApp.delete_qr_code(code, *, phone_id=None)#

Delete a QR code.

Parameters:

code (str) – The QR code.
phone_id (str | int | None) – The phone ID to delete the QR code for (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the QR code was deleted.

Return type:

WhatsApp.set_username(username, *, phone_id=None)#

Set a business username.

Read more at developers.facebook.com.

Parameters:

username (str) – The business username to set.
phone_id (str | int | None) – The phone ID to set the username for (optional, if not provided, the client’s phone ID will be used).

Returns:

A UsernameStatus object containing the new username and its status.

Return type:

UsernameStatus

WhatsApp.get_current_username(*, phone_id=None)#

Get the status of the business username associated with the business phone number, or information about the username.

Read more at developers.facebook.com.

Parameters:: phone_id (str | int | None) – The phone ID to get the username for (optional, if not provided, the client’s phone ID will be used).
Returns:: A UsernameStatus object containing the current username and its status.
Return type:: UsernameStatus

WhatsApp.get_reserved_usernames(*, phone_id=None)#

Get a list of usernames that have been reserved for your business portfolio.

Read more at developers.facebook.com.

Parameters:: phone_id (str | int | None) – The phone ID to get the reserved usernames for (optional, if not provided, the client’s phone ID will be used).
Returns:: A tuple of reserved usernames. These usernames have a higher chance of approval.
Return type:: tuple[str]

WhatsApp.delete_username(*, phone_id=None)#

Delete the business username associated with the business phone number.

Read more at developers.facebook.com.

Parameters:: phone_id (str | int | None) – The phone ID to delete the username for (optional, if not provided, the client’s phone ID will be used).
Returns:: Whether the username was deleted.
Return type:: SuccessResult

WhatsApp.delete_qr_code(code, *, phone_id=None)#

Delete a QR code.

Parameters:

code (str) – The QR code.
phone_id (str | int | None) – The phone ID to delete the QR code for (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the QR code was deleted.

Return type:

WhatsApp.get_call_permissions(from_user, *, phone_id=None)#

Get the call permissions for the WhatsApp Business account.

Read more at developers.facebook.com.

Parameters:

from_user (str | int) – The WhatsApp ID of the user to get the call permissions for.
phone_id (str | int | None) – The phone ID to get the call permissions from (optional, if not provided, the client’s phone ID will be used).

Returns:

The call permissions for the user.

Return type:

CallPermissions

WhatsApp.pre_accept_call(call_id, sdp, *, phone_id=None)#

Pre-accept a call.

Read more at developers.facebook.com.

In essence, when you pre-accept an inbound call, you are allowing the calling media connection to be established before attempting to send call media through the connection.

When you then call the accept call endpoint, media begins flowing immediately since the connection has already been established

Pre-accepting calls is recommended because it facilitates faster connection times and avoids audio clipping issues.

There is about 30 to 60 seconds after the Call Connect webhook is sent for the business to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you.

Parameters:

call_id (str) – The ID of the call to pre-accept.
sdp (SessionDescription) – Contains the session description protocol (SDP) type and description language.
phone_id (str | int | None) – The phone ID to pre-accept the call from (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the call was pre-accepted.

Return type:

WhatsApp.accept_call(call_id, sdp, *, tracker=None, phone_id=None)#

Connect to a call by providing a call agent’s SDP.

Read more at developers.facebook.com.

You have about 30 to 60 seconds after the Call Connect Webhook is sent to accept the phone call. If your business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you.

Parameters:

call_id (str) – The ID of the call to accept.
sdp (SessionDescription) – Contains the session description protocol (SDP) type and description language.
tracker (str | CallbackData | None) – The data to track the call with (optional, up to 512 characters, for complex data You can use CallbackData).
phone_id (str | int | None) – The phone ID to accept the call from (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the call was accepted.

Return type:

WhatsApp.reject_call(call_id, *, phone_id=None)#

Reject a call.

Read more at developers.facebook.com.

You have about 30 to 60 seconds after the Call Connect webhook is sent to accept the phone call. If the business does not respond the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you.

Parameters:

call_id (str) – The ID of the call to reject.
phone_id (str | int | None) – The phone ID to reject the call from (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the call was rejected.

Return type:

WhatsApp.terminate_call(call_id, *, phone_id=None)#

Terminate an active call.

Read more at developers.facebook.com.

This must be done even if there is an RTCP BYE packet in the media path. Ending the call this way also ensures pricing is more accurate. When the WhatsApp user terminates the call, you do not have to call this endpoint. Once the call is successfully terminated, a Call Terminate Webhook will be sent to you.

Parameters:

call_id (str) – The ID of the call to terminate.
phone_id (str | int | None) – The phone ID to terminate the call from (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the call was terminated.

Return type:

WhatsApp.create_group(*, subject, description=None, join_approval_mode=None, phone_id=None)#

Create a new group.

Read more at developers.facebook.com.

Parameters:

subject (str) – Group subject, Maximum 128 characters. Whitespace is trimmed.
description (str | None) – Group description. Maximum 2048 characters.
join_approval_mode (GroupJoinApprovalMode | None) – Indicates if WhatsApp users who click the invitation link can join the group with or without being approved first. Default is AUTO_APPROVE.
phone_id (str | int | None) – The phone ID to create the group for (optional, if not provided, the client’s phone ID will be used).

Returns:

The response of the group creation request, containing the request ID to track the status of the group creation.

Return type:

WhatsApp.get_group(group_id)#

Get details about a group.

Read more at developers.facebook.com.

Parameters:: group_id (str) – The ID of the group.
Returns:: The group details.
Return type:: GroupDetails

WhatsApp.get_groups(*, phone_id=None, pagination=None)#

Get groups associated with the WhatsApp Business account.

Example

>>> wa = WhatsApp()
>>> groups = wa.get_groups(pagination=Pagination(limit=10))
... for group in groups:
...     print(f'Group {group.id}: {group}')

Parameters:

phone_id (str | int | None) – The phone ID to get the groups for (optional, if not provided, the client’s phone ID will be used).
pagination (Pagination | None) – The pagination parameters (optional).

Returns:

Result object containing the groups.

Return type:

Result[GroupDetails]

WhatsApp.delete_group(group_id)#

Delete a group.

Read more at developers.facebook.com.

Parameters:: group_id (str) – The ID of the group to delete.
Returns:: The response of the group deletion request, containing the request ID to track the status of the group deletion.
Return type:: GroupOperation

WhatsApp.approve_group_join_requests(group_id, request_ids)#

Approve join requests for a group.

Read more at developers.facebook.com.

Parameters:

group_id (str) – The ID of the group.
request_ids (Iterable[str]) – The IDs of the join requests to approve.

Returns:

The response of the join request approval, containing the request ID to track the status of the approval.

Return type:

WhatsApp.reject_group_join_requests(group_id, request_ids)#

Reject join requests for a group.

Read more at developers.facebook.com.

Parameters:

group_id (str) – The ID of the group.
request_ids (Iterable[str]) – The IDs of the join requests to reject.

Returns:

The response of the join request rejection, containing the request ID to track the status of the rejection.

Return type:

WhatsApp.get_group_invite_link(group_id)#

Get the invite link for a group.

Read more at developers.facebook.com.

Parameters:: group_id (str) – The ID of the group.
Returns:: The group invite link.
Return type:: GroupInviteLink

WhatsApp.reset_group_invite_link(group_id)#

Reset the invite link for a group.

Read more at developers.facebook.com.

Parameters:: group_id (str) – The ID of the group.
Returns:: The new group invite link.
Return type:: GroupInviteLink

WhatsApp.remove_group_participants(group_id, participants)#

Remove participants from a group.

Read more at developers.facebook.com.

Parameters:

group_id (str) – The ID of the group.
participants (Iterable[str]) – The WhatsApp IDs of the participants to remove.

Returns:

The response of the remove participants request, containing the request ID to track the status of the removal.

Return type:

WhatsApp.update_group_settings(group_id, *, subject=None, description=None, profile_picture)#

Update group settings.

Read more at developers.facebook.com.

Parameters:

group_id (str) – The ID of the group.
subject (str | None) – Group subject, Maximum 128 characters.
description (str | None) – Group description. Maximum 2048 characters.
profile_picture (bytes | str | Path | BinaryIO | Iterator[bytes]) – The new group profile picture. Can be a bytes object, a file path, a file-like object, or an iterator that yields bytes.

Returns:

The response of the update group settings request, containing the request ID to track the status of the update.

Return type:

WhatsApp.pin_message(chat_id, message_id, *, expiration_days, sender=None)#

Pin a message in a chat.

Note that currently only group chats support pinning messages.
Read more at developers.facebook.com.

Parameters:

chat_id (str | int) – The ID of the chat to pin the message in.
message_id (str) – The ID of the message to pin.
expiration_days (timedelta | int) – The number of days until the pinned message expires. Must be between 1 and 30 days.
sender (str | int | None) – The phone ID to pin the message from (optional, if not provided, the client’s phone ID will be used).

Returns:

The pinned message.

Return type:

WhatsApp.unpin_message(chat_id, message_id, *, sender=None)#

Unpin a message in a chat.

Note that currently only group chats support pinning messages.
Read more at developers.facebook.com.

Parameters:

chat_id (str | int) – The ID of the chat to unpin the message in.
message_id (str) – The ID of the message to unpin.
sender (str | int | None) – The phone ID to unpin the message from (optional, if not provided, the client’s phone ID will be used).

Returns:

The unpinned message.

Return type:

WhatsApp.get_app_access_token(app_id, app_secret)#

Get an access token for an app.

Read more at developers.facebook.com.

Parameters:

app_id (int) – The ID of the app in the App Basic Settings
app_secret (str) – The app secret.

Returns:

The access token.

Return type:

str

WhatsApp.set_app_callback_url(app_id, app_access_token, callback_url, verify_token, fields)#

Set the callback URL for the webhook.

Read more at developers.facebook.com.

Parameters:

app_id (int) –
The ID of the app in the App Basic Settings
app_access_token (str) – The app access token from get_app_access_token().
callback_url (str) – The URL to receive the webhook.
verify_token (str) – The token to verify the webhook.
fields (Iterable[str]) – The fields to subscribe to. See Available Fields.

Returns:

Whether the callback URL was set.

Return type:

WhatsApp.override_waba_callback_url(callback_url, verify_token, *, waba_id=None)#

Override the callback URL for the WhatsApp Business account.

Read more at developers.facebook.com.

Parameters:

callback_url (str) – The URL to receive the webhook.
verify_token (str) – The token to verify the webhook.
waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID).

Returns:

Whether the callback URL was overridden.

Return type:

WhatsApp.delete_waba_callback_url(*, waba_id=None)#

Delete the callback URL for the WhatsApp Business account.

Read more at developers.facebook.com.

Parameters:: waba_id (str | int | None) – The WhatsApp Business account ID (Overrides the client’s business account ID).
Returns:: Whether the callback URL was deleted.
Return type:: SuccessResult

WhatsApp.override_phone_callback_url(callback_url, verify_token, *, phone_id=None)#

Override the callback URL for the phone.

Read more at developers.facebook.com.
To access to the current webhook configuration use get_business_phone_number() and access the webhook_configuration attribute.

Parameters:

callback_url (str) – The URL to receive the webhook.
verify_token (str) – The token to verify the webhook.
phone_id (str | int | None) – The phone ID to override the callback URL for (optional, if not provided, the client’s phone ID will be used).

Returns:

Whether the callback URL was overridden.

Return type: