Skip to content

WhatsApp

Leverage the Cloud API to send messages using the cloud-hosted version of the WhatsApp Business Platform.

Warning

This plugin is based on the WhatsApp Business Cloud API. To use the features available through the plugin, it is necessary to have a properly configured Meta developer account.

If you don't already have an account set up, please see the Set up Account section.

Installation

pip install botcity-whatsapp-plugin

Importing the Plugin

After you installed this package, the next step is to import the package into your code and start using the functions.

from botcity.plugins.whatsapp import BotWhatsappPlugin

Instantiating the plugin

First, let's instantiate the plugin by passing in some information from your WhatsApp developer account. All we need is the ACCESS TOKEN and the PHONE NUMBER ID of the number being used.

token = "<YOUR_ACCESS_TOKEN>"
number_id = "<YOUR_WHATSAPP_NUMBER_ID>"

# Instantiate the plugin
whatsapp = BotWhatsappPlugin(access_token=token, whatsapp_number_id=number_id)

Note

In the examples below, a test number provided by WhatsApp is being used.

If you want, you can configure and use your own numbers. (details here).

Sending text messages

We can send text messages easily, just passing the number that will receive the message and the text content.

Important

In some cases it may be necessary for the recipient's number to send a message to your number before receiving your messages. This is a Cloud API issue, making it necessary for the conversation to be initiated by the number that will receive the messages. So if your messages are not being sent, please ask the recipient number to send a message first.

token = "<YOUR_ACCESS_TOKEN>"
number_id = "<YOUR_WHATSAPP_NUMBER_ID>"

whatsapp = BotWhatsappPlugin(access_token=token, whatsapp_number_id=number_id)

# Phone numbers must be used in format:
# [country code][phone number including area code]
whatsapp.send_text_message("5519987654321", "Hey! Sending a simple message! 😃")

When using text messages, we can also work with the preview url parameter. This parameter can be used when the text message contains an HTTP or HTTPS link. In this case, when we set it to True, a preview box referring to the link will be included for the message recipient.

whatsapp.send_text_message(
    to_number="5519987654321",
    msg_content="BotCity website: https://botcity.dev",
    preview_url=True
)

View of sent message:

Sending media messages

You can also send messages that contain media content. In this case, it is necessary to pass the type of media being sent and the link referring to the content of this media. The media content must be a publicly accessible URL

Available media types are defined as an Enum in the MediaType class, just use MediaType.TYPE to select the type of media that will be sent.

from botcity.plugins.whatsapp import BotWhatsappPlugin, MediaType

whatsapp = BotWhatsappPlugin(access_token=token, whatsapp_number_id=number_id)

whatsapp.send_media_message(
    to_number="5519987654321",
    media_type=MediaType.IMAGE,
    media_link="https://i.imgur.com/70fV8e4.png",
    caption="The beast!"
)

Sent message:

Warning

The caption parameter can only be used with image and document type media, and the filename parameter can only be used with document type media. Using these parameters with other media types will cause an exception.

Sending location messages

It is possible to send messages that contain location via WhatsApp, just have the location data in hand and an interactive message will automatically be sent.

whatsapp = BotWhatsappPlugin(access_token=token, whatsapp_number_id=number_id)

# Location data
longt = "-23.52742958804382"
lat = "-46.67852205062807"
address = "Av. Francisco Matarazzo, 1705 - Água Branca, São Paulo - SP, 05001-200"

whatsapp.send_location_message(
    to_number="5519987654321",
    longitude=longt,
    latitude=lat,
    name="Football stadium",
    address=address
)

View of location sent:

Sending contact messages

You can also send messages that contain some contact information. In this way, an interactive card containing the contact information passed will be sent to the recipient. You can send a contact with just a name, or use some optional parameter, such as the contact's phone number or email.

whatsapp = BotWhatsappPlugin(access_token=token, whatsapp_number_id=number_id)

whatsapp.send_contact_message(
    to_number="5519987654321",
    contact_name="Test Contact",
    contact_phone="5519912345678",
    contact_email="contact@email.com"
)

Contact card sent: