Greenapi Client Python

GREEN-API Python client (whatsapp-api-client-python)

When to apply

Use this skill whenever the task is to call GREEN-API from Python via the official SDK. Do not invent HTTP paths or method names from memory: only methods listed in references/inventory.md exist in this SDK. Semantics of parameters, chatId formats, delays, and notification types come from the official docs linked in each method section — not from other repos.

For webhook HTTP server libraries in other languages, use a language-specific webhook skill if present. This SDK receives notifications via polling (webhooks.startReceivingNotifications / receiving.receiveNotification) or you can build your own HTTP endpoint for webhook-endpoint technology.

Sources of truth (mandatory)

1. Official API docs — https://green-api.com/en/docs/api/
   Parameters, response shapes, limits, chatId, delays, notification formats.
2. This repository / installed package — method names, class attributes, init signatures. Inventory: references/inventory.md.

If a method exists in the docs but not in the inventory → do not use it in code.

Install

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

Requires Python >= 3.10. Credentials: idInstance and apiTokenInstance from console.green-api.com.

Client initialization

from whatsapp_api_client_python import API

greenAPI = API.GreenAPI(
    "1101000001",  # idInstance (string)
    "d75b3a66374942c5b3c019c698abc2067e151558acbd412345",  # apiTokenInstance
)

Optional constructor kwargs (from GreenApi.__init__ in API.py):

Aliases: API.GreenAPI is the same class as API.GreenApi.

Partner API (separate client):

partner = API.GreenApiPartner(partnerToken="PARTNER_TOKEN")
# then: partner.partner.getInstances() / createInstance / deleteInstanceAccount

Response object

Every API method returns whatsapp_api_client_python.response.Response:

Always check response.code == 200 before reading response.data.

Async

Most groups expose *Async twins (sendMessageAsync, receiveNotificationAsync, …). Call them with await inside asyncio.

chatId and phone format

Docs: https://green-api.com/en/docs/api/chat-id/

• Phone: full international number, digits only, no +, spaces, or leading zeros tricks.
• Never hand-craft group IDs — take them from createGroup, journals, or notifications.
• Wrong chatId → validation 400: must be phone_number@c.us or group_id@g.us.

Instance must be authorized

Docs: https://green-api.com/en/docs/api/account/GetStateInstance/

Before sending, verify:

state = greenAPI.account.getStateInstance()
print(state.data)  # expect {"stateInstance": "authorized"}

Important states: authorized, notAuthorized, blocked, starting, suspended. Authorize via console QR / account.qr() / account.getAuthorizationCode(phoneNumber). Messages sit in the send queue up to 24 hours until the instance is authorized.

Message sending delay

Docs: https://green-api.com/en/docs/api/send-messages-delay/

Outgoing messages go through a FIFO queue. Delay is controlled by instance setting delaySendMessagesMilliseconds (min 500 ms, max 600000 ms; recommend ≤ 300000):

greenAPI.account.setSettings({"delaySendMessagesMilliseconds": 5000})

Note: setSettings reboots the instance; settings apply within ~5 minutes.

Typical scenarios

1. Send a text message

Docs: https://green-api.com/en/docs/api/sending/SendMessage/

from whatsapp_api_client_python import API

greenAPI = API.GreenAPI(id_instance, api_token)

response = greenAPI.sending.sendMessage(
    "79876543210@c.us",
    "Hello from GREEN-API",
    typingTime=3000,  # optional: 1000–20000 ms typing indicator
)

if response.code == 200:
    print(response.data["idMessage"])
else:
    print(response.error)

Required: chatId, message (max 20000 chars). Optional in SDK: quotedMessageId, archiveChat, linkPreview, typingTime, typePreview, customPreview. Response: { "idMessage": "..." }.

2. Send a file by URL

Docs: https://green-api.com/en/docs/api/sending/SendFileByUrl/

response = greenAPI.sending.sendFileByUrl(
    "79876543210@c.us",
    "https://download.samplelib.com/png/sample-clouds2-400x300.png",
    "sample-clouds2-400x300.png",
    "Caption text",
)

Required: chatId, urlFile, fileName (with extension). Max file size 100 MB.

3. Send a file by upload (local path)

Docs: https://green-api.com/en/docs/api/sending/SendFileByUpload/
Uses media host (SDK sets this automatically).

response = greenAPI.sending.sendFileByUpload(
    "79876543210@c.us",
    "data/logo.jpg",
    "logo.jpg",
    "Available rates",
)
# response.data: idMessage, urlFile (link valid 15 days)

SDK signature: sendFileByUpload(chatId, path, fileName=None, caption=None, ...). The local path is the second argument (path), not a raw file object.

4. Receive notifications — polling (built-in)

Docs: https://green-api.com/en/docs/api/receiving/technology-http-api/ReceiveNotification/

Requirement: instance webhookUrl must be empty. If a custom webhook URL is set, receiveNotification returns an error telling you to clear it.

from whatsapp_api_client_python import API

greenAPI = API.GreenAPI(id_instance, api_token)


def on_event(type_webhook: str, body: dict) -> None:
    if type_webhook == "incomingMessageReceived":
        chat_id = body["senderData"]["chatId"]
        msg = body["messageData"]
        if msg.get("typeMessage") == "textMessage":
            text = msg["textMessageData"]["textMessage"]
            print(chat_id, text)


# Blocks; Ctrl+C to stop. Internally: receiveNotification → handler → deleteNotification
greenAPI.webhooks.startReceivingNotifications(on_event)

Handler signature is fixed: (typeWebhook: str, body: dict). After handling, the SDK deletes the notification by receiptId (do not skip this if you poll manually).

Manual poll loop:

resp = greenAPI.receiving.receiveNotification(receiveTimeout=5)
if resp.code == 200 and resp.data:
    receipt_id = resp.data["receiptId"]
    body = resp.data["body"]
    # ... process body["typeWebhook"] ...
    greenAPI.receiving.deleteNotification(receipt_id)

receiveTimeout: 5–60 seconds (API default 5). Empty queue → empty body / no data. Notifications live in the queue 24 hours, FIFO.