Ctrl+K

Template

Template#

class pywa.types.template.NewTemplate#

Represents a new template. ‘Create Templates’ on developers.facebook.com.

Variables:

Example

>>> from pywa.types import NewTemplate as NewTemp
>>> NewTemp(
...     name='buy_new_iphone_x',
...     category=NewTemp.Category.MARKETING,
...     language=NewTemp.Language.ENGLISH_US,
...     header=NewTemp.Text('The New iPhone {15} is here!'),
...     body=NewTemp.Body('Hello {John}! Buy now and use the code {WA_IPHONE_15} to get {15%} off!'),
...     footer=NewTemp.Footer('Powered by PyWa'),
...     buttons=[
...         NewTemp.UrlButton(title='Buy Now', url='https://example.com/shop/{iphone15}'),
...         NewTemp.PhoneNumberButton(title='Call Us', phone_number='1234567890'),
...         NewTemp.QuickReplyButton('Unsubscribe from marketing messages'),
...         NewTemp.QuickReplyButton('Unsubscribe from all messages'),
...     ],
... )

Example for Authentication template:

>>> from pywa.types import NewTemplate as NewTemp
>>> NewTemp(
...     name='auth_with_otp',
...     category=NewTemp.Category.AUTHENTICATION,
...     language=NewTemp.Language.ENGLISH_US,
...     body=NewTemp.AuthBody(
...         code_expiration_minutes=5,
...         add_security_recommendation=True
...     ),
...     buttons=NewTemp.OTPButton(
...         otp_type=NewTemp.OTPButton.OtpType.ONE_TAP,
...         title='Copy Code',
...         autofill_text='Autofill',
...         package_name='com.example.app',
...         signature_hash='1234567890ABCDEF1234567890ABCDEF12345678'
...     )
... )

Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. If grouped incorrectly, error will be raised when submitting the template.

When you send a template that has multiple quick reply buttons, the order in which the buttons appear in the template is the order in which they will appear in the delivered message

class Category(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Template category.

‘Template Categorization’ on developers.facebook.com

Variables:

  • AUTHENTICATION – Authentication templates are used to send one-time passwords (OTPs) or codes to app users.

  • MARKETING – Marketing templates are used to send promotional messages to app users.

  • UTILITY – Utility templates are used to send non-promotional messages to app users.

class Text(text: str)#

Represents a text header.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.Text(text='Hello, {John}!')
Variables:

text (str) – Text to send with the header (Up to 60 characters. Supports 1 placeholder).

class Body(text: str)#

Represents a template body.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.Body(
...     text='Shop now through {the end of August} and '
...         'use code {25OF} to get {25%} off of all merchandise',
... )
Variables:

text (str) – Text to send with the body (Up to 1024 characters. Supports multiple placeholders).

class AuthBody(code_expiration_minutes: int | None = None, add_security_recommendation: bool = False)#

Represents the configuration for an authentication template.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.AuthBody(
...     code_expiration_minutes=5,
...     add_security_recommendation=True
... )
Variables:

  • code_expiration_minutes (int | None) – Indicates number of minutes the password or code is valid. If omitted, the code expiration warning will not be displayed in the delivered message. (Minimum 1, maximum 90).

  • add_security_recommendation (bool) – Set to True if you want the template to include the string, "For your security, do not share this code". Set to False to exclude the string. Defaults to False.

class Footer(text: str)#

Represents a template footer.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.Footer(text='⚡ Powered by PyWa')
Variables:

text (str) – Text to send with the footer (Up to 60 characters, no placeholders allowed).

class PhoneNumberButton(title: str, phone_number: int | str)#

Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button.

  • It seems that no need to provide the phone button when sending the template, it will be added automatically

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.PhoneNumberButton(title='Call Us', phone_number='12125552368')
Variables:

  • title (str) – Button text (Up to 25 characters, no placeholders allowed).

  • phone_number (int | str) – Alphanumeric string. Business phone number to be (display phone number) called when the user taps the button (Up to 20 characters, no placeholders allowed).

class UrlButton(title: str, url: str)#

URL buttons load the specified URL in the device’s default web browser when tapped by the app user. Templates are limited to two URL buttons.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.UrlButton(
...     title='Log In',
...     url='https://x.com/login?email={john@example}'
... )
Variables:

  • title (str) – Button text (Up to 25 characters, supports 1 variable).

  • url (str) – URL to be loaded when the user taps the button (Up to 2000 characters, supports 1 placeholder, which be appended to the end of the URL).

class QuickReplyButton(text: str)#

Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. A common use case-case is a button that allows your customer to easily opt-out of any marketing messages.

  • You will provide the callback data when you send the template.

Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. If grouped incorrectly, the API will return an error indicating an invalid combination.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.QuickReplyButton(text='Unsubscribe from Promos')
>>> NewTemplate.QuickReplyButton(text='Unsubscribe from All')
Variables:

text (str) – The text to send when the user taps the button (Up to 25 characters, no placeholders allowed).

class OTPButton(otp_type: OtpType, title: str | None = None, autofill_text: str | None = None, package_name: str | None = None, signature_hash: str | None = None, zero_tap_terms_accepted: bool = True)#

Represents a button that can be used to send an OTP.

Example for ONE_TAP:

>>> from pywa.types import NewTemplate
>>> NewTemplate.OTPButton(
...     otp_type=NewTemplate.OTPButton.OtpType.ONE_TAP,
...     title='Copy Code',
...     autofill_text='Autofill',
...     package_name='com.example.app',
...     signature_hash='1234567890ABCDEF1234567890ABCDEF12345678'
... )

Example for COPY_CODE:

>>> from pywa.types import NewTemplate
>>> NewTemplate.OTPButton(
...     otp_type=NewTemplate.OTPButton.OtpType.COPY_CODE,
...     title='Copy Code'
... )
Variables:

  • otp_type (OtpType) – Type of OTP to send. A copy code button copies the one-time password or code to the user’s clipboard. The user can then manually switch to your app and paste the password or code into your app’s interface. A one-tap autofill button automatically loads and passes your app the one-time password or code.

  • title (str | None) – Copy code button text. If omitted, the text will default to a pre-set value localized to the template’s language. For example, Copy Code for English (US).

  • autofill_text (str | None) – One-tap autofill button text. If omitted, the text will default to a pre-set value localized to the template’s language. For example, Autofill for English (US).

  • package_name (str | None) – Android package name of your app. Required if otp_type is OtpType.ONE_TAP or OtpType.ZERO_TAP.

  • signature_hash (str | None) – Your app signing key hash. See App Signing Key Hash for more information. Required if otp_type is OtpType.ONE_TAP or OtpType.ZERO_TAP.

  • zero_tap_terms_accepted (bool) – Acceptance of the WhatsApp Business API Terms of Service. Required if otp_type is OtpType.ZERO_TAP. Defaults to True.

class OtpType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

The type of the button

Variables:

  • COPY_CODE – Copy code button copies the one-time password or code to the user’s clipboard.

  • ONE_TAP – One-tap autofill button automatically loads and passes your app the one-time password or code.

  • ZERO_TAP – Zero-tap autofill button automatically loads and passes your app the one-time password or code

class MPMButton#
Represents a button that can be used to send multi-product message (MPM)

  • This button required providing header to the new template!

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.MPMButton()
class CatalogButton#

Represent a button that can be used to display a catalog.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.CatalogButton()
class CopyCodeButton(example: str)#
Represents a button that can be used to copy coupon codes to the user’s clipboard.

  • Only one copy code button is allowed per template.

  • Do not use this button to send one-time passwords (OTPs), Use NewTemplate.OTPButton instead.

Example

>>> from pywa.types import NewTemplate
>>> NewTemplate.CopyCodeButton(example='250FF')
Variables:

example (str) – An example of the coupon code (Up to 15 characters).

class pywa.types.template.Template#

The template to send.

The template message is basically a message that contains the values of the template placeholders.

If in the template created with body that contains 3 variables, then the message must contain 3 values for the placeholders.

>>> from pywa.types import Template as Temp
>>> Temp(
...     name='buy_new_iphone_x',
...     language=Temp.Language.ENGLISH_US,
...     header=TextValue(value='15'),
...     body=[
...         Temp.TextValue(value='John Doe'),
...         Temp.TextValue(value='WA_IPHONE_15'),
...         Temp.TextValue(value='15%'),
...     ],
...     buttons=[
...         Temp.UrlButtonValue(value='iphone15'),
...         Temp.QuickReplyButtonData(data='unsubscribe_from_marketing_messages'),
...         Temp.QuickReplyButtonData(data='unsubscribe_from_all_messages'),
...     ],
... )

Example for Authentication template:

>>> from pywa.types import Template as Temp
>>> Temp(
...     name='auth_with_otp',
...     language=Temp.Language.ENGLISH_US,
...     buttons=Temp.OTPButtonCode(code='123456'),
... )
Variables:
class TextValue(value: str)#

Represents a value to assign to a placeholder in a template.

Example

>>> from pywa.types import Template
>>> Template.TextValue(var='John Doe')  # The template was created with 'Hello, {John}!'
Variables:

value (str) – The value to assign to the placeholder.

class Currency(fallback_value: str, code: str, amount_1000: int)#

Represents a currency variable.

Variables:

  • fallback_value (str) – Default text if localization fails.

  • code (str) – ISO 4217 currency code (e.g. USD, EUR, etc.).

  • amount_1000 (int) – Amount multiplied by 1000.

class DateTime(fallback_value: str)#

Represents a date time variable.

Variables:

fallback_value (str) – Default text if localization fails.

class QuickReplyButtonData(data: CallbackDataT)#

Represents a quick reply button.

Variables:

data (pywa.types.callback.CallbackDataT) – The data to send when the user taps the button (you can listen for this data with @on_callback_button decorator).

class UrlButtonValue(value: str)#

Represents a URL button variable.

Example

>>> from pywa.types import Template
>>> Template.UrlButtonValue(value='COUPON123')  # The template was created with 'https://example.com/shop/{COUPON12}'
Variables:

value (str) – The value to assign to the variable in the template (appended to the end of the URL).

class OTPButtonCode(code: str)#

Represents an OTP button variable.

Example

>>> from pywa.types import Template
>>> Template.OTPButtonCode(value='123456')
Variables:

code (str) – The code to copy or autofill when the user taps the button.

class MPMButton(thumbnail_product_sku: str, product_sections: Iterable[ProductsSection])#

Represent a multi-product message (MPM) button

Example

>>> from pywa.types import Template
>>> Template.MPMButton(
...     thumbnail_product_sku='IPHONE_15',
...     product_sections=[
...         ProductsSection(
...             title='Smartphones',
...             skus=['IPHONE_15', 'GALAXY_S23'],
...         ),
...         ProductsSection(
...             title='Laptops',
...             skus=['MACBOOKPRO', 'SURFACEPRO'],
...         ),
...     ],
... )
Variables:

  • thumbnail_product_sku (str) – The thumbnail of this item will be used as the template message’s header image.

  • product_sections (Iterable[pywa.types.others.ProductsSection]) – The product sections to send with the template.

class CatalogButton(thumbnail_product_sku: str | None = None)#

Represent a catalog button

Example

>>> from pywa.types import Template
>>> Template.CatalogButton(thumbnail_product_sku='IPHONE_15')
Variables:

thumbnail_product_sku (str | None) – The thumbnail of this item will be used as the message’s header image. if not provided, the product image of the first item in your catalog will be used.

class CopyCodeButton(code: str)#

Represents a copy code button variable (copies the code to the user’s clipboard).

Example

>>> from pywa.types import Template
>>> Template.CopyCodeButton(code='COUPON123')
Variables:

code (str) – The code to copy when the user taps the button.

class pywa.types.template.Language#
Template language and locale code.
>>> from pywa.types import NewTemplate
>>> NewTemplate.Language.ENGLISH_US

>>> from pywa.types import Template
>>> Template.Language.ENGLISH_US

‘Template language and locale code’ on developers.facebook.com

class pywa.types.template.TemplateResponse#
Variables:
Contents