Others

Others#

class pywa.types.sent_update.SentMessage#

Represents a 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.

  • input (str) – The input (phone number) of the recipient.

class pywa.types.sent_update.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 | None) – The status of the sent template.

  • input – The input (phone number) of the recipient.

class pywa.types.sent_update.SentTemplateStatus#

Represents the status of a sent template.

Variables:

  • ACCEPTED – The template was accepted.

  • HELD_FOR_QUALITY_ASSESSMENT – The template was held for quality assessment.

class pywa.types.others.SuccessResult#

Represents a simple success result.

  • This is used for operations that do not return any data, but only indicate success or failure.

You can use this class to check if an operation was successful or not:

>>> wa = WhatsApp(...)
>>> if wa.update_template(...): # update_template returns SuccessResult so we can check it directly
...     print("Template updated successfully")
Variables:

success (bool) – Whether the operation was successful.

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(...)
>>> res = wa.get_blocked_users(pagination=types.Pagination(limit=100))
>>> for user in res:
...     print(user.name, user.wa_id)
...
>>> if res.has_next:
...     next_res = res.next()
...
>>> print(res.all())
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.

property empty: Result[_T]#

Returns an empty Result instance.

next()#

Get the next page of results. if there is no next page, it returns empty Result.

  • Check if there is a next page using the has_next property before calling this method.

Return type:

Result[_T]

previous()#

Get the previous page of results. if there is no previous page, it returns empty Result.

  • Check if there is a previous page using the has_previous property before calling this method.

Return type:

Result[_T]

all(*, sleep=0.0)#

Get all results from the current page, previous pages, and next pages.

  • Make sure to provide higher limit in the Pagination parameter to avoid hitting rate limits.

  • Also consider using the sleep parameter to avoid hitting rate limits.

Parameters:

sleep (float) – The number of seconds to sleep between requests to avoid hitting rate limits. Default is 0.0 (no sleep).

Returns:

A list of all results from the current page, previous pages, and next pages.

Return type:

list[_T]

class pywa.types.others.Pagination#

Represents pagination parameters for fetching data.

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.BusinessVerificationStatus#

Represents the business verification status.

Variables:

  • EXPIRED – The business verification has expired.

  • FAILED – The business verification has failed.

  • INELIGIBLE – The business is not eligible for verification.

  • NOT_VERIFIED – The business is not verified.

  • PENDING – The business verification is pending.

  • PENDING_NEED_MORE_INFO – The business verification is pending and needs more information.

  • PENDING_SUBMISSION – The business verification is pending submission.

  • REJECTED – The business verification has been rejected.

  • REVOKED – The business verification has been revoked.

  • VERIFIED – The business is verified.

class pywa.types.others.MarketingMessagesLiteAPIStatus#

Represents the WhatsApp Business Account’s status for onboarding onto Marketing Messages Lite.

Variables:

  • INELIGIBLE – The WABA has not met all eligibility requirements.

  • ELIGIBLE – The WABA has met all eligibility requirements.

  • ONBOARDED – The WABA is eligible to use MM Lite API and has signed MM Lite Terms of Service, has a valid payment method attached, and is linked to an Ad account.

  • UNKNOWN – An unknown status. Please contact support for assistance.

class pywa.types.others.MarketingMessagesOnboardingStatus#

Represents the WhatsApp Business Account’s status for onboarding onto Marketing Messages Lite API.

Variables:

  • INELIGIBLE_ON_BEHALF_OF_WABA – The WhatsApp Business Account (“WABA”) uses the “OBO” model which is not supported. You must either first transfer ownership of the WABA to the customer or onboard using the Intent API.

  • INELIGIBLE_INACTIVE_OR_RESTRICTED – The WhatsApp Business Account is inactive or is restricted from messaging due to a policy enforcement issue.

  • INELIGIBLE_COUNTRY_NOT_SUPPORTED – The WhatsApp Business Account is in a region that does not support the MM Lite API.

  • INELIGIBLE_USING_WHATSAPP_BUSINESS_APP – The WhatsApp Business phone number is being used within the WhatsApp Business app.

  • ELIGIBLE – WhatsApp Business Account is eligible to onboard and use the MM Lite API.

  • PENDING_VALID_PAYMENT_METHOD – The WhatsApp Business Account requires setting up a valid payment method.

  • PENDING_INTERNAL_SETUP – WhatsApp Business Account is in the configuration process of using the MM Lite API and requires no further action from the business customer or partner.

  • ONBOARDED – The WhatsApp Business Account has successfully onboarded and is ready to use the MM Lite API.

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_on_biz_app (bool) – Indicates if the customer’s business phone number is registered for WhatsApp Business app.

  • 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 | 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.calls.BusinessPhoneNumberSettings#

Represents the settings of a WhatsApp Business Phone Number.

Variables:
class pywa.types.others.StorageConfiguration#

Local storage offers an additional layer of data management control, by giving you the option to specify where your message data is stored at rest. If your company is in a regulated industry such as finance, government, or healthcare, you may prefer to have your message data stored in a specific country when at rest because of regulatory or company policies.

Local storage is controlled by a setting enabled or disabled at a WhatsApp business phone number level. Both Cloud API and MM Lite API support local storage, and the setting will apply to any messages sent via either API if enabled.

How local storage works

When Local storage is enabled, the following constraints are applied to message content for a business phone number:

  • Data-in-use: When message content is sent or received by Cloud API or MM Lite API, message content may be stored on Meta data centers internationally while being processed.

  • Data-at-rest: After the data-in-use period, message content is deleted from Meta data centers outside of the specified local storage region, and persisted only in data centers within the local storage region selected. Note that the data-in-use period differs between Cloud API and MM Lite API as specified below:

    • When using local storage for Cloud API, the data-in-use period is up to 60 minutes.

    • When using local storage for MM Lite API, the data-in-use period is up to 90 minutes.

The local storage feature supplements other WhatsApp Business Platform privacy and security controls, and allows customers to ensure a higher level of compliance with local data protection regulations.

Data in scope

Local storage applies to message content (text and media) sent and/or received via Cloud API and MM Lite API. The following message content are in scope of the local storage feature:

  • Text messages: text payload (message body)

  • Media messages: media payload (audio, document, image or video)

  • Template messages (static template + parameters passed at message send time): components with text / media payload

In addition, a limited set of metadata attributes is included with the locally stored message content, in order to correctly associate the encrypted message payload with the originally processed message, and to audit the fact of localization. The stored metadata is protected with tokenization and encryption.

Available Regions

To see what regions are supported by local storage, see the data_localization_region parameter in the documentation on phone number registration.

class pywa.types.others.ConversationalAutomation#

Represents a conversational automation.

See Conversational Automation.

Variables:
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.

  • status (str | None) – The status of the WhatsApp Business Account (e.g. ACTIVE).

  • message_template_namespace (str) – Namespace string for the message templates that belong to the WhatsApp Business Account

  • name (str) – User-friendly name to differentiate WhatsApp Business Accounts.

  • timezone_id (str) – The timezone of the WhatsApp Business Account (See Timezone IDs).

  • business_verification_status (pywa.types.others.BusinessVerificationStatus | None) – Current status of business verification of Meta Business Account which owns this WhatsApp Business Account

  • is_enabled_for_insights (bool | None) – If true, indicates the WhatsApp Business Account enabled template analytics. See Analytics.

  • marketing_messages_lite_api_status (pywa.types.others.MarketingMessagesLiteAPIStatus | None) – WhatsApp Business Account’s status for onboarding onto Marketing Messages Lite.

  • marketing_messages_onboarding_status (pywa.types.others.MarketingMessagesOnboardingStatus | None) – Onboarding status of the WhatsApp Business account into Marketing Messages Lite API.

  • ownership_type (str | None) – Ownership type of the WhatsApp Business Account.

  • currency (str | None) – The currency in which the payment transactions for the WhatsApp Business Account will be processed

  • country (str | None) – country of the WhatsApp Business Account’s owning Meta Business 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:
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.utils.CallbackURLScope#

Enum for the callback URL scopes.

Variables:
Contents