Messenger class

Messenger class#

class pynani.Messenger.Messenger(access_token: str, page_id: str = 'me')#

Bases: object

Initializes the Messenger class with the provided access token and page ID.

Parameters:

  • access_token (str) – The access token for authenticating API requests.

  • page_id (str, optional) – The page ID for the Facebook page. Defaults to ‘me’.

download_attachment(attachment_url: str, path_dest: str) → None#

Downloads an attachment from the given URL and saves it to the specified destination path.

Parameters:

  • attachment_url (str) – The URL of the attachment to be downloaded.

  • path_dest (str) – The local file path where the attachment will be saved.

Returns:

None

Example

>>> download_attachment("https://example.com/image.png", "path/to/image.png")
get_attachment_type(data: Dict) → str | None#

Extracts the type of an attachment from the provided data.

Parameters:

data (Dict) – The data containing the attachment information.

Returns:

The type of the attachment if found, otherwise None.

Return type:

Optional[str]

Example with a Webhook made with Flask, will be used as follows:
>>> get_attachment_type(request.get_json())
"image"
get_message_text(data: Dict) → str | None#

Extracts the text message from the provided data.

Parameters:

data (Dict) – The data received from the webhook event.

Returns:

The text message if found, otherwise None.

Return type:

Optional[str]

Example with a Webhook made with Flask, will be used as follows:
>>> get_message_text(request.get_json())
"Hello 👋🏽"
get_message_type(data: Dict) → str | None#

Determines the type of message received from the webhook event.

Parameters:

data (Dict) – The data received from the webhook event.

Returns:

The type of message if found, otherwise None.

Return type:

Optional[str]

Example with a Webhook made with Flask, will be used as follows:
>>> get_message_type(request.get_json())
"text"
get_sender_id(data: dict) → str | None#

Extracts the sender ID from the provided data.

Parameters:

data (dict) – The data received from the webhook event.

Returns:

The sender ID if found, otherwise None.

Return type:

Optional[str]

Example with a Webhook made with Flask, will be used as follows:
>>> get_sender_id(request.get_json())
"1234567897654321"
get_url_attachment(data: Dict) → str | None#

Extracts the URL of an attachment from the provided data.

Parameters:

data (Dict) – The data containing the attachment information.

Returns:

The URL of the attachment if found, otherwise None.

Return type:

Optional[str]

Example with a Webhook made with Flask, will be used as follows:
>>> get_url_attachment(request.get_json())
"https://example.com/image.png"
send_attachment(sender_id: str, attachment_type: str, attachment_url: str) → Dict | None#

Sends an attachment to a user.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • attachment_type (str) – The type of the attachment (e.g., ‘image’, ‘video’, ‘audio’, ‘file’).

  • attachment_url (str) – The URL of the attachment to be sent.

Returns:

The response from the server if the request is successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_attachment(sender_id, "image", "https://example.com/image.png")
send_button_template(sender_id: str, message: str, buttons: List[Dict]) → Dict | None#

Sends a button template message to the specified sender.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • message (str) – The message to be sent.

  • buttons (list) – A list of button options. The list should contain less than 3 items.

Returns:

The response from the server if the request was successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_button_template(sender_id, "Select an option", [{'type': 'postback', 'title': 'Hello', 'payload': 'DEVELOPER_DEFINED_PAYLOAD', 'url': ''}])
Using the basic_buttons() function from pynani:
>>> send_button_template(sender_id, "Select an option", basic_buttons(["Hello", "World", "🤑"]))
Using the exit_buttons() function from pynani:
>>> send_button_template(sender_id, "Select an option", exit_buttons([{"title": "Exit", "url": "https://google.com"}, {"title": "Call me", "call_number": "+525555555555"}]))
send_generic_template(sender_id: str, title: str, image_url: str | None = None, default_url: str | None = None, subtitle: str | None = None, buttons: List | None = None) → Dict | None#

Sends a generic template message to the specified sender.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • title (str) – The title of the template.

  • image_url (Optional[str], optional) – The URL of the image to be displayed. Defaults to None.

  • default_url (Optional[str], optional) – The URL for the default action. Defaults to None.

  • subtitle (Optional[str], optional) – The subtitle of the template. Defaults to None.

  • buttons (Optional[List], optional) – A list of button options. Defaults to None.

Returns:

The response from the server if the request was successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_generic_template(sender_id, "Hello", "https://example.com/hello.png", "https://example.com", "World", [{'type': 'web_url', 'title': 'Hello', 'payload': '', 'url': 'https://example.com/hello.png'}])
Using the basic_buttons() or exit_buttons() functions from pynani:
>>> send_generic_template(sender_id, "Hello", "https://example.com/hello.png", "https://example.com", "World", basic_buttons(["Hello", "World", "👽"]))
send_local_attachment(sender_id: str, attachment_type: str, attachment_path: str) → Dict | None#

Sends a local attachment to a user.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • attachment_type (str) – The type of the attachment (e.g., ‘image’, ‘video’, ‘audio’, ‘file’).

  • attachment_path (str) – The local path to the attachment to be sent.

Returns:

The response from the server if the request is successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_local_attachment(sender_id, "image", "path/to/image.png")
send_media_template(sender_id: str, media_type: str, attachment_id: str, buttons: List[Dict]) → Dict | None#

Sends a media template message to the specified sender.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • media_type (str) – The type of media to be sent (e.g., ‘image’, ‘video’, ‘audio’, ‘file’).

  • attachment_id (str) – The ID of the attachment to be sent.

  • buttons (list) – A list of button options. The list should contain less than 3 items.

Returns:

The response from the server if the request was successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_media_template(sender_id, "image", "1234567897654321", [{'type': 'web_url', 'title': 'Hello', 'payload': '', 'url': 'https://example.com/hello.png'}])
Using the basic_buttons() or exit_buttons() functions from pynani:
>>> send_media_template(sender_id, "image", "1234567897654321", basic_buttons(["Hello", "World", "👻"]))
send_quick_reply(sender_id: str, message: str | int, quick_replies: List[Dict]) → Dict | None#

Sends a quick reply message to the specified sender.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • message (Union[str, int]) – The message to be sent.

  • quick_replies (list) – A list of quick reply options. The list should contain less than 13 items.

Returns:

The response from the server if the request was successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_quick_reply(sender_id, "Select an option", [{'content_type': 'text', 'title': 'Hello', 'payload': '<POSTBACK_PAYLOAD>', 'image_url': None}])
Using the quick_buttons() function from pynani:
>>> send_quick_reply(sender_id, "Select an option", quick_buttons(["Hello", "World", "💩"]))
Usiing the quick_buttons_image() function from pynani:
>>> send_quick_reply(sender_id, "Select an option", quick_buttons_image(["Hello", "World", "💩"], ["https://example.com/hello.png", "https://example.com/world.png", "https://example.com/poop.png"]))
send_receipt_template(sender_id: str, order_number: str, payment_method: str, summary: Dict, currency: str = 'USD', order_url: str | None = None, timestamp: str | None = None, address: Dict | None = None, adjustments: List | None = None, elements: List | None = None) → Dict | None#

Sends a receipt template message to the specified sender.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • order_number (str) – The order number of the transaction.

  • payment_method (str) – The payment method used.

  • summary (Dict) – A dictionary containing the summary of the transaction.

  • currency (str, optional) – The currency used in the transaction. Defaults to ‘USD’.

  • order_url (Optional[str], optional) – The URL of the order. Defaults to None.

  • timestamp (Optional[str], optional) – The timestamp of the transaction. Defaults to None.

  • address (Optional[Dict], optional) – The address of the recipient. Defaults to None.

  • adjustments (Optional[List], optional) – A list of adjustments made to the order. Defaults to None.

  • elements (Optional[List], optional) – A list of elements in the order. Defaults to None.

Returns:

The response from the server if the request was successful, otherwise None.

Return type:

Optional[Dict]

Example

>>> send_receipt_template(sender_id, "123456789", "Credit Card",
               {"subtotal": 75.00,
                "shipping_cost": 4.95,
                "total_tax": 6.19,
                "total_cost": 56.14},
               "USD", "https://example.com/order/123456789", "123456789",
               {"street_1": "1 Hacker Way",
                "city": "Menlo Park",
                "postal_code": "94025",
                "state": "CA",
                "country": "US"},
               [{"name": "New Customer Discount", "amount": 20}],
               [{"title": "Classic White T-Shirt",
                 "subtitle": "100% Soft and Luxurious Cotton",
                 "quantity": 2, "price": 50,
                 "currency": "USD",
                 "image_url": "https://example.com/classic-white-t-shirt"}])
Using the get_address(), get_summary(), get_adjustments(), and get_elements() functions from pynani:
>>> address = get_address("123 Main St", "Springfield", "12345", "IL", "US")
>>> adjustments = get_adjustments("New Customer Discount", 20, "Black Friday", 34)
>>> summary = get_summary(56.14)
>>> elements = get_elements("T-Shirt", 20.0)
>>> send_receipt_template(sender_id, "123456789", "Credit Card",
               summary=summary,
               currency="USD",
               order_url="https://example.com/order/123456789",
               timestamp="123456789",
               address=address,
               adjustments=adjustments,
               elements=elements)
send_text_message(sender_id: str, message: str | int) → Dict | None#

Sends a text message to the specified sender.

Parameters:

  • sender_id (str) – The ID of the recipient.

  • message (Union[str, int]) – The message to be sent.

Returns:

The response from the server if the request was successful, otherwise None.

Return type:

Optional[Dict]

Example with a Webhook made with Flask, will be used as follows:
>>> send_text_message(sender_id, "Hello, how can I help you?")
upload_attachment(attachment_type: str, attachment_path: str) → str#

Uploads an attachment to the server and returns the attachment ID.

Parameters:

  • attachment_type (str) – The type of the attachment (e.g., ‘image’, ‘video’, ‘audio’, ‘file’).

  • attachment_path (str) – The local file path to the attachment.

Returns:

The ID of the uploaded attachment if successful, otherwise None.

Return type:

str

Example with a Webhook made with Flask, will be used as follows:
>>> upload_attachment("image", "path/to/image.png")
"1234567897654321"
verify_token(params: Dict, token: str) → Tuple#

Verifies the provided token against the expected token.

Parameters:

  • params (Dict) – The parameters received in the verification request.

  • token (str) – The expected verification token.

Returns:

A tuple containing the JSON response, the status code, and the headers.

Return type:

Tuple

Example

>>> verify_token({"hub.mode": "subscribe", "hub.challenge": "1950414725", "hub.verify_token": "1234", }, "1234")
Whit a Webhook made with Flask, the function verify_token() will be used as follows:
>>> @app.get("/")
>>> def meta_verify():
>>>     return mess.verify_token(request.args, TOKEN)
pynani.Messenger.get_long_lived_token(app_id: str, app_secret: str, short_lived_token: str, save_env: bool | None = False) → str | None#

Obtains a long-lived access token using the provided short-lived token.

Parameters:

  • app_id (str) – The application ID.

  • app_secret (str) – The application secret.

  • short_lived_token (str) – The short-lived page access token.

  • save_env (Optional[bool], optional) – Whether to save the long-lived token to the .env file. Defaults to False.

Returns:

The long-lived access token if successful, otherwise None.

Return type:

Optional[str]

Exception:

RequestException: If an error occurs during the request.

Example

>>> get_long_lived_token('765xxx', 'e0fcxxx', 'EAAK4AXXXX', True)
"EAAK4XXXX"
pynani.Messenger.jsonify(data: Dict | str, status_code: int) → Tuple#

Converts the given data to a JSON response with the specified status code.

Parameters:

  • data (Union[Dict, str]) – The data to be converted to JSON. It can be a dictionary or a string.

  • status_code (int) – The HTTP status code to be returned with the response.

Returns:

A tuple containing the JSON response, the status code, and the headers.

Return type:

Tuple

Contents