Others

class pywa.types.sent_message.SentMessage

Represents a message that was sent to WhatsApp user.

Variables:

• id (str) – The ID of the message.

• to_user (User) – The user the message was sent to.

• from_phone_id (str) – The WhatsApp ID of the sender who sent the message.

class pywa.types.sent_message.SentTemplate

Bases: SentMessage

Represents a template message that was sent to WhatsApp user.

Variables:

• id – The ID of the message.

• to_user – The user the message was sent to.

• from_phone_id – The WhatsApp ID of the sender who sent the message.

• status (SentTemplateStatus) – The status of the sent template.

class pywa.types.sent_message.SentTemplateStatus

Represents the status of a sent template.

• Read more about template pacing on developers.facebook.com.

Variables:

• ACCEPTED – The template was accepted.

• HELD_FOR_QUALITY_ASSESSMENT – The template was held for quality assessment.

class pywa.types.others.Result

This class is used to handle paginated results from the WhatsApp API. You can iterate over the results, and also access the next and previous pages of results.

• When using the next() or previous() methods, the results are returned as a new instance of the Result class.

• You can access the cursors using the before and after properties and use them later in the Pagination object.

Example

>>> from pywa import WhatsApp, types
>>> wa = WhatsApp(...)
>>> all_blocked_users = []
>>> res = wa.get_blocked_users(pagination=types.Pagination(limit=100))
>>> while True:
...     all_blocked_users.extend(res)
...     if not res.has_next:
...         break
...     res = res.next()
>>> all_blocked_users
[User(...), User(...), User(...), ...]

property has_next: bool

Check if there is a next page of results.

property has_previous: bool

Check if there is a previous page of results.

property before: str | None

Cursor that points to the start of the page of data that has been returned.

property after: str | None

Cursor that points to the end of the page of data that has been returned.

next() → Result[_T] | None

Get the next page of results.

previous() → Result[_T] | None

Get the previous page of results.

class pywa.types.others.Pagination

Represents pagination parameters for fetching data.

• See Paginated Results.

Cursor-based Pagination

Cursor-based pagination is the most efficient method of paging and should always be used when possible. A cursor refers to a random string of characters which marks a specific item in a list of data. The cursor will always point to the item, however it will be invalidated if the item is deleted or removed. Therefore, your app shouldn’t store cursors or assume that they will be valid in the future.

• Don’t store cursors. Cursors can quickly become invalid if items are added or deleted.

Time-based Pagination

Time pagination is used to navigate through results data using Unix timestamps which point to specific times in a list of data.

• For consistent results, specify both since and until parameters. Also, it is recommended that the time difference is a maximum of 6 months.

Offset-based Pagination

Offset pagination can be used when you do not care about chronology and just want a specific number of objects returned. Only use this if the edge does not support cursor or time-based pagination. Note that if new objects are added to the list of items being paged, the contents of each offset-based page will change.

• Offset based pagination is not supported for all API calls. To get consistent results, we recommend you to paginate using the previous/next links we return in the response.

Variables:

• before (str | None) – This is the cursor that points to the start of the page of data that has been returned.

• after (str | None) – This is the cursor that points to the end of the page of data that has been returned.

• limit (int | None) – This is the maximum number of objects that may be returned. A query may return fewer than the value of limit due to filtering. Do not depend on the number of results being fewer than the limit value to indicate that your query reached the end of the list of data, use the has_next instead as described below. For example, if you set limit to 10 and 9 results are returned, there may be more data available, but one item was removed due to privacy filtering. Some edges may also have a maximum on the limit value for performance reasons.

• offset (int | None) – This offsets the start of each page by the number specified.

• until (int | datetime.datetime | None) – A Unix timestamp or datetime obj value that points to the end of the range of time-based data.

• since (int | datetime.datetime | None) – A Unix timestamp or datetime obj value that points to the start of the range of time-based data.

class pywa.types.others.BusinessProfile

Represents a business profile.

Variables:

• about (str) – This text appears in the business’s profile, beneath its profile image, phone number, and contact buttons.

• 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.

• industry (pywa.types.others.Industry) – The industry of the business.

• profile_picture_url (str | None) – URL of the profile picture that was uploaded to Meta.

• websites (tuple[str, ...] | None) – The URLs associated with the business. For instance, a website, Facebook Page, or Instagram. There is a maximum of 2 websites with a maximum of 256 characters each.

class pywa.types.others.BusinessPhoneNumber

Represents a WhatsApp Business Phone Number.

See WhatsApp Business Phone Number.

Variables:

• id (str) – The ID of the phone number.

• verified_name (str | None) – The name that appears in WhatsApp Manager and WhatsApp client chat thread headers, chat lists, and profile, if display criteria is met.

• display_phone_number (str | None) – International format representation of the phone number.

• conversational_automation (pywa.types.others.ConversationalAutomation | None) – Conversational Automation feature config for this phone number.

• status (str | None) – The operating status of the phone number (eg. connected, rate limited, warned).

• quality_rating (str | None) – The quality rating of the phone number.

• quality_score (dict[str, str] | None) – Quality score of the phone.

• webhook_configuration (dict[str, str] | None) – The webhook configuration of the phone number.

• name_status (str | None) – The status of the name review.

• new_name_status (str | None) – The status of the review of the new name requested.

• code_verification_status (str | None) – Indicates the phone number’s one-time password (OTP) verification status. Values can be NOT_VERIFIED, VERIFIED, or EXPIRED. Only phone numbers with a VERIFIED status can be registered. See Manage Phone Numbers and Certificates.

• account_mode (str | None) – The account mode of the phone number. See Filtering Phone Numbers.

• is_official_business_account (bool) – Indicates if phone number is associated with an Official Business Account.

• is_pin_enabled (bool) – Returns True if a pin for two-step verification is enabled.

• is_preverified_number (bool) – Returns true if the phone number was pre-verified

• messaging_limit_tier (str | None) – Current messaging limit tier.

• search_visibility (str | None) – The availability of the phone_number in the WhatsApp Business search.

• platform_type (str | None) – Platform the business phone number is registered with. Values can be CLOUD_API, ON_PREMISE, or NOT_APPLICABLE. If NOT_APPLICABLE, the number is not registered with Cloud API or On-Premises API.

• throughput (dict[str, str] | None) – The business phone number’s Cloud API throughput level. See Phone Number Throughput.

• eligibility_for_api_business_global_search (str | None) – Status of eligibility in the API Business Global Search.

• health_status (dict[str, str] | None) – health_status

• certificate (str | None) – Certificate of the phone number

• new_certificate (str | None) – Certificate of the new name that was requested

• last_onboarded_time (str | None) – Indicates when the user added the business phone number to their WhatsApp Business Account (when the user completed the Embedded Signup flow).

class pywa.types.others.ConversationalAutomation

Represents a conversational automation.

See Conversational Automation.

Variables:

• id (str) – The ID of the WhatsApp Business Phone Number.

• chat_opened_enabled (bool) – Whether the welcome message is enabled (if so, you can listen to the ChatOpened event).

• ice_breakers (tuple[str] | None) – See Ice Breakers.

• commands (tuple[pywa.types.others.Command, ...] | None) – The commands.

class pywa.types.others.QRCode

Customers can scan a QR code from their phone to quickly begin a conversation with your business. The WhatsApp Business Management API allows you to create and access these QR codes and associated short links.

Variables:

• code (str) – The code of the QR code.

• prefilled_message (str) – The message that will be prefilled when the user starts a conversation with the business using the QR code.

• deep_link_url (str) – The deep link URL of the QR code.

• qr_image_url (str | None) – The URL of the QR code image (return only when creating a QR code).

class pywa.types.others.Command

Represents a command in a conversational automation.

See Conversational Automation.

Variables:

• name (str) – The name of the command (without the slash).

• description (str) – The description of the command.

class pywa.types.others.CommerceSettings

Represents the WhatsApp commerce settings.

Variables:

• catalog_id (str) – The ID of the catalog associated with the business.

• is_catalog_visible (bool) – Whether the catalog is visible to customers.

• is_cart_enabled (bool) – Whether the cart is enabled.

class pywa.types.others.Industry

Represents the industry of a business.

Variables:

• UNDEFINED – Undefined.

• OTHER – Other.

• AUTO – Automotive.

• BEAUTY – Beauty.

• APPAREL – Apparel.

• EDU – Education.

• ENTERTAIN – Entertainment.

• EVENT_PLAN – Event planning.

• FINANCE – Finance.

• GROCERY – Grocery store.

• GOVT – Government.

• HOTEL – Hotel.

• HEALTH – Health.

• NONPROFIT – Nonprofit.

• PROF_SERVICES – Professional services.

• RETAIL – Retail.

• TRAVEL – Travel.

• RESTAURANT – Restaurant.

• NOT_A_BIZ – Not a business.

class pywa.types.others.WhatsAppBusinessAccount

Represents a WhatsApp Business Account.

Variables:

• id (str) – The ID of the account.

• message_template_namespace (str) – The namespace of the message templates.

• name (str) – The name of the account.

• timezone_id (str) – The timezone ID of the account.

class pywa.types.others.FacebookApplication

Represents a Facebook Application.

Variables:

• id (str) – The ID of the application.

• name (str) – The name of the application.

• link (str) – The link to the application.

class pywa.types.others.UsersBlockedResult

Represents the result of blocking users operation.

Variables:

• added_users (tuple[pywa.types.others.User, ...]) – The users that were successfully blocked.

• failed_users (tuple[pywa.types.others.BlockUserFailure, ...]) – The users that failed to be blocked. You can access the .errors attribute in each failure to get the error details.

• errors (pywa.errors.WhatsAppError | None) – The errors that occurred during the operation (if any).

class pywa.types.others.UsersUnblockedResult

Represents the result of unblocking users operation.

Variables:

removed_users (tuple[pywa.types.others.User, ...]) – The users that were successfully unblocked.

class pywa.types.others.BlockUserFailure

Represents a failure to block a user.

Variables:

• input (str) – The phone number/wa_id input that failed to be blocked.

• errors (tuple[pywa.errors.WhatsAppError, ...]) – The errors that occurred during the operation.

class pywa.Version

Enum for the latest and minimum versions of the Graph API and WhatsApp Flows.

• Use the constant to get the latest version. Example: WhatsApp(..., api_version=Version.GRAPH_API)

• Using the latest version can break your code if the API changes. Use constants for stability.

• Use the min attribute to get the minimum version. Example: Version.GRAPH_API.min

Variables:

• GRAPH_API – (MIN_VERSION: str, LATEST_VERSION: str)

• FLOW_JSON – (MIN_VERSION: str, LATEST_VERSION: str)

• FLOW_DATA_API – (MIN_VERSION: str, LATEST_VERSION: str)

• FLOW_MSG – (MIN_VERSION: str, LATEST_VERSION: str)

class pywa.types.StopHandling

Raise this exception to stop handling an update.

You can call .stop_handling() on every update object to raise this exception.

Example

>>> from pywa import WhatsApp
>>> from pywa.types import Message
>>> wa = WhatsApp(...)

>>> @wa.on_message()
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_text("Hello from PyWa!")
...     msg.stop_handling()  # or raise StopHandling

>>> @wa.on_message()
... def not_called(_: WhatsApp, msg: Message):
...     msg.reply_text("This message will not be sent")

class pywa.types.ContinueHandling

Raise this exception to continue handling an update.

You can call .continue_handling() on every update object to raise this exception.

Example

>>> from pywa import WhatsApp
>>> from pywa.types import Message
>>> wa = WhatsApp(...)

>>> @wa.on_message()
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_text("Hello from PyWa!")
...     msg.continue_handling()  # or raise ContinueHandling

>>> @wa.on_message()
... def not_called(_: WhatsApp, msg: Message):
...     msg.reply_text("This message will be sent")

class pywa.types.ListenerTimeout

The listener timed out

Example

try:
    wa.listen(to="123456", timeout=10)
except ListenerTimeout as e:
    wa.send_message("123456", "Timeout")

Variables:

timeout – The timeout that was set for the listener

class pywa.types.ListenerCanceled

The listener was canceled by a filter

Example

try:
    wa.listen(
        to="123456",
        filters=filters.message & filters.text,
        cancelers=filters.callback_button & filters.matches("cancel")
    )
except ListenerCanceled as e:
    print(e.update) # print the update that caused the listener to be canceled
    wa.send_message("123456", "You cancelled the listener by clicking the cancel button")

Variables:

update – The update that caused the listener to be canceled

class pywa.types.ListenerStopped

The listener was stopped manually by wa.stop_listening(…)

Example

try:
    wa.listen("123456")
except ListenerStopped as e:
    print(e.reason) # print the reason the listener was stopped
    wa.send_message("123456", "The listener was stopped")

Variables:

reason – The reason the listener was stopped (set by wa.stop_listening(reason=”…”))

class pywa.utils.CallbackURLScope

Enum for the callback URL scopes.

Variables:

• APP – https://developers.facebook.com/docs/graph-api/reference/app/subscriptions

• WABA – https://developers.facebook.com/docs/whatsapp/embedded-signup/webhooks/override#set-waba-alternate-callback

• PHONE – https://developers.facebook.com/docs/whatsapp/embedded-signup/webhooks/override#set-phone-number-alternate-callback