Leverage the Cloud API to send messages using the cloud-hosted version of the WhatsApp Business Platform.
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.
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)
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.
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 )
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!" )
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
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="firstname.lastname@example.org" )
Contact card sent: