green-api/whatsapp-api-client-python / skills
greenapi-client-python
VerifiedWrite correct Python code with the official GREEN-API SDK whatsapp-api-client-python (package whatsapp_api_client_python). Use when sending/receiving WhatsApp messages, files, polls, groups, journals, queues, statuses, contacts, partner instances, polling notifications, or configuring a GREEN-API instance in Python. Triggers: GREEN-API, green-api, whatsapp-api-client-python, GreenAPI, GreenApi, sendMessage, receiveNotification.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.9 KB |
| references/account.md | markdown | 2.9 KB |
| references/contacts.md | markdown | 796 B |
| references/device.md | markdown | 346 B |
| references/groups.md | markdown | 1.9 KB |
| references/inventory.md | markdown | 12.1 KB |
| references/journals.md | markdown | 1.1 KB |
| references/marking.md | markdown | 436 B |
| references/partner.md | markdown | 930 B |
| references/queues.md | markdown | 843 B |
| references/receiving.md | markdown | 4.1 KB |
| references/sending.md | markdown | 3.7 KB |
| references/service-methods.md | markdown | 2.0 KB |
| references/statuses.md | markdown | 1.3 KB |
references/receiving.md
View on GitHub# Receiving notifications
Index: https://green-api.com/en/docs/api/receiving/
Two technologies:
1. **HTTP API polling** — `receiveNotification` + `deleteNotification` (this SDK helps).
2. **Webhook Endpoint** — GREEN-API POSTs to your public URL (configure via `setSettings`;
implement the HTTP server yourself).
They are alternatives for the same instance: if `webhookUrl` is set, polling returns an
error that a custom webhook URL is configured.
## `receiving.receiveNotification`
Docs: https://green-api.com/en/docs/api/receiving/technology-http-api/ReceiveNotification/
| Param | Required | Notes |
| --- | --- | --- |
| `receiveTimeout` | no | 5–60 seconds; default 5 |
Waits up to timeout for one notification. Empty queue → empty/`null` body.
Success shape:
```json
{
"receiptId": 1234567,
"body": {
"typeWebhook": "incomingMessageReceived",
"instanceData": {},
"timestamp": 1588091580,
"idMessage": "...",
"senderData": { "chatId": "...", "sender": "...", "senderName": "..." },
"messageData": { "typeMessage": "textMessage", "textMessageData": { "textMessage": "..." } }
}
}
```
## `receiving.deleteNotification`
Docs: https://green-api.com/en/docs/api/receiving/technology-http-api/DeleteNotification/
Required: `receiptId` (int) from the previous receive. **Must** call after processing,
or the queue will not advance.
## `receiving.downloadFile`
Docs: https://green-api.com/en/docs/api/receiving/files/DownloadFile/
Required: `chatId`, `idMessage`. Downloads media for a message the system knows about.
## `webhooks.startReceivingNotifications`
SDK helper (not a REST method). Implements the recommended poll loop:
1. `receiveNotification`
2. if data: call `onEvent(typeWebhook, body)`
3. `deleteNotification(receiptId)`
4. repeat until `stopReceivingNotifications` or Ctrl+C
```python
def on_event(type_webhook: str, body: dict) -> None:
if type_webhook == "incomingMessageReceived":
...
greenAPI.webhooks.startReceivingNotifications(on_event)
```
Async: `await greenAPI.webhooks.startReceivingNotificationsAsync(on_event)`.
Deprecated: `webhooks.started`, `webhooks.job`.
## Webhook endpoint (no SDK server)
Docs: https://green-api.com/en/docs/api/receiving/technology-webhook-endpoint/
```python
greenAPI.account.setSettings({
"webhookUrl": "https://example.com/green-api/webhook",
"webhookUrlToken": "Bearer secret",
"incomingWebhook": "yes",
"outgoingWebhook": "yes",
"outgoingAPIMessageWebhook": "yes",
"stateWebhook": "yes",
"incomingCallWebhook": "yes",
})
```
- Endpoint must be public and answer **200**.
- Retries ~every 1 minute; delivery guaranteed **24 hours**.
- If `webhookUrlToken` set, expect `Authorization` header (`Bearer` default, or `Basic`).
- To go back to polling: set `webhookUrl` to `""`.
## Notification types (`typeWebhook`)
Docs: https://green-api.com/en/docs/api/receiving/notifications-format/type-webhook/
| typeWebhook | Meaning |
| --- | --- |
| `incomingMessageReceived` | Incoming message/file |
| `outgoingMessageReceived` | Message sent from phone |
| `outgoingAPIMessageReceived` | Message sent via API |
| `outgoingMessageStatus` | Delivery/read status |
| `stateInstanceChanged` | Auth state change |
| `statusInstanceChanged` | Socket status |
| `deviceInfo` | Device/battery (archive / may be off) |
| `incomingCall` / `outgoingCall` | Calls |
| `incomingBlock` | Block events |
| `quotaExceeded` | Developer plan limits |
Enable categories via `setSettings` flags: `incomingWebhook`, `outgoingWebhook`,
`outgoingMessageWebhook`, `outgoingAPIMessageWebhook`, `stateWebhook`,
`incomingCallWebhook`, `pollMessageWebhook`, `editedMessageWebhook`,
`deletedMessageWebhook`, etc.
Docs: https://green-api.com/en/docs/api/account/SetSettings/
Message payload formats: https://green-api.com/en/docs/api/receiving/notifications-format/
### Extracting text from `incomingMessageReceived`
```python
md = body["messageData"]
t = md.get("typeMessage")
if t == "textMessage":
text = md["textMessageData"]["textMessage"]
elif t == "extendedTextMessage":
text = md["extendedTextMessageData"]["text"]
# media types: imageMessage, videoMessage, documentMessage, ... see docs
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |