whatsapp-api-client-python

whatsapp-api-client-python

Support links

Guides & News

• Документация на русском языке.

whatsapp-api-client-python is a library for integration with WhatsApp messenger using the API service green-api.com. You should get a registration token and an account ID in your personal cabinet to use the library. There is a free developer account tariff.

API

The documentation for the REST API can be found at the link. The library is a wrapper for the REST API, so the documentation at the link above also applies.

Authorization

To send a message or perform other GREEN API methods, the WhatsApp account in the phone app must be authorized. To authorize the account, go to your cabinet and scan the QR code using the WhatsApp app.

Installation

python -m pip install whatsapp-api-client-python

Import

from whatsapp_api_client_python import API

Examples

How to initialize an object

greenAPI = API.GreenAPI(
    "1101000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345"
)

Sending a text message to a WhatsApp number

Link to example: sendTextMessage.py.

response = greenAPI.sending.sendMessage("[e-mail]", "Message text")

print(response.data)

Sending a text message asynchronously

Link to example: sendMessageAsync.py.

import asyncio

async def main():
    response = await greenAPI.sending.sendMessageAsync("[e-mail]", "Message text")
    print(response.data)

asyncio.run(main())

Sending an image via URL

Link to example: sendPictureByLink.py.

response = greenAPI.sending.sendFileByUrl(
    "[e-mail]",
    "https://download.samplelib.com/png/sample-clouds2-400x300.png",
    "sample-clouds2-400x300.png",
    "Sample PNG"
)

print(response.data)

Sending an image by uploading from the disk

Link to example: sendPictureByUpload.py.

response = greenAPI.sending.sendFileByUpload(
    "[e-mail]",
    "data/logo.jpg",
    "logo.jpg",
    "Available rates"
)

print(response.data)

Sending an image asynchronously by uploading from the disk

Link to example: sendFileByUploadAsync.py.

import asyncio

async def main():
    response = await greenAPI.sending.sendFileByUploadAsync(
        "[e-mail]",
        "data/logo.jpg",
        "logo.jpg",
        "Available rates"
    )
    print(response.data)

asyncio.run(main())

Group creation and sending a message to the group

Attention. If one tries to create a group with a non-existent number, WhatsApp may block the sender's number. The number in the example is non-existent.

Link to example: createGroupAndSendMessage.py.

create_group_response = greenAPI.groups.createGroup(
    "Group Name", ["[e-mail]"]
)
if create_group_response.code == 200:
    send_message_response = greenAPI.sending.sendMessage(
        create_group_response.data["chatId"], "Message text"
    )

Receive incoming messages by HTTP API

Link to example: receiveNotification.py.

The general concept of receiving data in the GREEN API is described here. To start receiving notifications by the HTTP API you need to execute the library method:

greenAPI.webhooks.startReceivingNotifications(onEvent)

onEvent - your function which should contain parameters:

Parameter	Description
typeWebhook	received notification type (str)
body	notification body (dict)

Notification body types and formats can be found here.

This method will be called when an incoming notification is received. Next, process notifications according to the business logic of your system.

Receive incoming messages asynchronously by HTTP API

Link to example: receiveNotificationAsync.py.

import asyncio

async def main():
    await greenAPI.webhooks.startReceivingNotificationsAsync(onEvent)

asyncio.run(main())

Sending a polling message

Link to example: sendPoll.py.

response = greenAPI.sending.sendPoll(
    "[e-mail]",
    "Please choose a color:",
    [
        {"optionName": "Red"},
        {"optionName": "Green"},
        {"optionName": "Blue"}
    ]
)

print(response.data)

Sending a text status

Link to example: sendTextStatus.py.

response = greenAPI.statuses.sendTextStatus(
    "I sent this status using Green Api Python SDK!", 
    "#54c774", 
    "NORICAN_REGULAR"
)

print(response.data)

Sending interactive buttons

Link to example: sendInteractiveButtons.py.

response = greenAPI.sending.sendInteractiveButtons(
    "[e-mail]",
    "This is message with buttons!",
    [{
        "type": "call",
        "buttonId": "1",
        "buttonText": "Call me",
        "phoneNumber": "79001234567"
    },
    {
        "type": "url",
        "buttonId": "2",
        "buttonText": "Green-api",
        "url": "https://green-api.com/en/docs/api/sending/SendInteractiveButtons/"
    }],
    "Check this out",
    "Hope you like it"
)

print(response.data)

Sending interactive buttons async

Link to example: sendInteractiveButtonsAsync.py.

import asyncio

async def main():
    response = await greenAPI.sending.sendInteractiveButtonsAsync(
        "[e-mail]",
        "This is message with buttons!",
        [{
            "type": "call",
            "buttonId": "1",
            "buttonText": "Call me",
            "phoneNumber": "79001234567"
        },
        {
            "type": "url",
            "buttonId": "2",
            "buttonText": "Green-api",
            "url": "https://green-api.com/en/docs/api/sending/SendInteractiveButtons/"
        }],
        "Check this out",
        "Hope you like it"
    )
    print(response.data)
asyncio.run(main())

Examples list

Description	Module
Example of sending text	sendTextMessage.py
Example of sending text asynchronously	sendTextMessageAsync.py
Example of sending a picture by URL	sendPictureByLink.py
Example of sending a file by URL asynchronously	sendFileByUrlAsync.py
Example of sending a picture by uploading from the disk	sendPictureByUpload.py
Example of sending file by uploading from the disk asynchronously	sendFileByUploadAsync.py
Example of a group creation and sending a message to the group	createGroupAndSendMessage.py
Example of a group creation and sending a message to the group asynchronously	createGroupAndSendMessageAsync.py
Example of incoming webhooks receiving	receiveNotification.py
Example of incoming webhooks receiving asynchronously	receiveNotificationAsync.py
Example of sending a polling message	sendPoll.py
Example of sending a polling message asynchronously	sendPollAsync.py
Example of sending a text status	sendTextStatus.py
Example of sending a text status asynchronously	sendTextStatusAsync.py
Example of creating instance	CreateInstance.py
Example of creating instance asynchronously	CreateInstanceAsync.py
Example of sending interactive buttons	SendInteractiveButtons.py
Example of sending interactive buttons asynchronously	SendInteractiveButtonsAsync.py
Example of sending interactive buttons with a reply	SendInteractiveButtonsReply.py
Example of sending interactive buttons asynchronously with a reply	SendInteractiveButtonsReplyAsync.py

The full list of the library methods

API method	Description	Documentation link
account.getSettings	The method is designed to get the current settings of the account	GetSettings
account.getWaSettings	The method is designed to get information about the WhatsApp account	GetWaSettings
account.setSettings	The method is designed to set the account settings	SetSettings
account.getStateInstance	The method is designed to get the state of the account	GetStateInstance
account.getStatusInstance	The method is designed to get the socket connection state of the account instance with WhatsApp	GetStatusInstance
account.reboot	The method is designed to restart the account	Reboot
account.logout	The method is designed to unlogin the account	Logout
account.qr	The method is designed to get a QR code	QR
account.setProfilePicture	The method is designed to set the avatar of the account	SetProfilePicture
account.getAuthorizationCode	The method is designed to authorize an instance by phone number	GetAuthorizationCode
device.getDeviceInfo	The method is designed to get information about the device (phone) on which the WhatsApp Business application is running	GetDeviceInfo
groups.createGroup	The method is designed to create a group chat	CreateGroup
groups.updateGroupName	The method changes the name of the group chat	UpdateGroupName
groups.getGroupData	The method gets group chat data	GetGroupData
groups.addGroupParticipant	The method adds a participant to the group chat	AddGroupParticipant
groups.removeGroupParticipant	The method removes the participant from the group chat	RemoveGroupParticipant
groups.setGroupAdmin	The method designates a member of a group chat as an administrator	SetGroupAdmin
groups.removeAdmin	The method deprives the participant of group chat administration rights	RemoveAdmin
groups.setGroupPicture	The method sets the avatar of the group	SetGroupPicture
groups.leaveGroup	The method logs the user of the current account out of the group chat	LeaveGroup
statuses.sendTextStatus	The method is aimed for sending a text status	SendTextStatus
statuses.sendVoiceStatus	The method is aimed for sending a voice status	SendVoiceStatus
statuses.sendMediaStatus	The method is aimed for sending a pictures or video status	SendMediaStatus
statuses.deleteStatus	The method is aimed for deleting a certain status	DeleteStatus
statuses.getStatusStatistic	The method returns an array of recipients marked sent/delivered/read for a given status	GetStatusStatistic
statuses.getOutgoingStatuses	The method returns the outgoing statuses of the account	GetOutgoingStatuses
statuses.getIncomingStatuses	The method returns the incoming statuses of the account	GetIncomingStatuses
journals.getChatHistory	The method returns the chat message history	GetChatHistory
journals.getMessage	The method returns a chat message	GetMessage
journals.lastIncomingMessages	The method returns the most recent incoming messages of the account	LastIncomingMessages
journals.lastOutgoingMessages	The method returns the last sent messages of the account	LastOutgoingMessages
queues.showMessagesQueue	The method is designed to get the list of messages that are in the queue to be sent	ShowMessagesQueue
queues.clearMessagesQueue	The method is designed to clear the queue of messages to be sent	ClearMessagesQueue
marking.readChat	The method is designed to mark chat messages as read	ReadChat
receiving.receiveNotification	The method is designed to receive a single incoming notification from the notification queue	ReceiveNotification
receiving.deleteNotification	The method is designed to remove an incoming notification from the notification queue	DeleteNotification
receiving.downloadFile	The method is for downloading received and sent files	DownloadFile
sending.sendMessage	The method is designed to send a text message to a personal or group chat	SendMessage
sending.sendFileByUpload	The method is designed to send a file loaded through a form (form-data)	SendFileByUpload
sending.sendFileByUrl	The method is designed to send a file downloaded via a link	SendFileByUrl
sending.uploadFile	The method is designed to upload a file to the cloud storage, which can be sent using the sendFileByUrl method	UploadFile
sending.sendLocation	The method is designed to send a geolocation message	SendLocation
sending.sendContact	The method is for sending a message with a contact	SendContact
sending.forwardMessages	The method is designed for forwarding messages to a personal or group chat	ForwardMessages
sending.sendPoll	The method is designed for sending messages with a poll to a private or group chat	SendPoll
sending.sendInteractiveButtons	This method is used to send messages with interactive buttons	sendInteractiveButtons
sending.sendInteractiveButtonsReply	This method is used to send messages with interactive buttons with a reply	sendInteractiveButtonsReply
serviceMethods.checkWhatsapp	The method checks if there is a WhatsApp account on the phone number	CheckWhatsapp
serviceMethods.getAvatar	The method returns the avatar of the correspondent or group chat	GetAvatar
serviceMethods.getContacts	The method is designed to get a list of contacts of the current account	GetContacts
serviceMethods.getContactInfo	The method is designed to obtain information about the contact	GetContactInfo
serviceMethods.deleteMessage	The method deletes the message from chat	DeleteMessage
serviceMethods.editMessage	The method edits the message in chat	EditMessage
serviceMethods.archiveChat	The method archives the chat	ArchiveChat
serviceMethods.unarchiveChat	The method unarchives the chat	UnarchiveChat
serviceMethods.setDisappearingChat	The method is designed to change the settings of disappearing messages in chats	SetDisappearingChat
webhooks.startReceivingNotifications	The method is designed to start receiving new notifications
webhooks.stopReceivingNotifications	The method is designed to stop receiving new notifications
partner.GetInstances	The method is for getting all the account instances created by the partner.	GetInstances
partner.CreateInstance	The method is for creating an instance.	CreateInstance
partner.DeleteInstanceAccount	The method is for deleting an instance.	DeleteInstanceAccount

Service methods documentation

https://green-api.com/en/docs/api/.

External products

• requests - for HTTP requests.
• aiohttp - for async HTTP requests.

License

Licensed under Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) terms. Please see file LICENSE.