Skip to content

SDK-72: Описать скилы для SDK-шек #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VadimSav merged 1 commit into from
Jul 22, 2026
Merged

SDK-72: Описать скилы для SDK-шек #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
340 changes: 340 additions & 0 deletions skills/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,340 @@
---
name: greenapi-client-python
description: >
Write 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.
license: MIT
metadata:
version: "1.0.0"
sdk: whatsapp-api-client-python
pypi: whatsapp-api-client-python
docs: https://green-api.com/en/docs/api/
github: https://github.com/green-api/whatsapp-api-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](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](references/inventory.md).

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

## Install

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

Requires Python **>= 3.10**. Credentials: `idInstance` and `apiTokenInstance` from
[console.green-api.com](https://console.green-api.com/).

## Client initialization

```python
from whatsapp_api_client_python import API

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

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

| Kwarg | Default | Meaning |
| --- | --- | --- |
| `debug_mode` | `False` | Verbose request logging |
| `raise_errors` | `False` | Raise `GreenAPIError` on failures |
| `host` | `https://api.green-api.com` | API host (`apiUrl`) |
| `media` | `https://media.green-api.com` | Media host for uploads |
| `host_timeout` | `180` | Seconds per host request retry |
| `media_timeout` | `10800` | Seconds per media request |

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

Partner API (separate client):

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

### Response object

Every API method returns `whatsapp_api_client_python.response.Response`:

| Attribute | When | Content |
| --- | --- | --- |
| `code` | always | HTTP status, or `None` on transport failure |
| `data` | `code == 200` | Parsed JSON (`dict` / list) |
| `error` | non-200 | Response body text |

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/

| Kind | Format | Example |
| --- | --- | --- |
| Personal chat | `<phone>@c.us` | `79876543210@c.us` |
| Group chat | `...@g.us` | `120363043968066561@g.us` |
| Lid | `...@lid` | returned by API; do not invent |

- 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:

```python
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):

```python
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/

```python
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/

```python
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).

```python
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.

```python
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:

```python
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.

### 5. Receive notifications — webhook endpoint (your HTTP server)

Docs: https://green-api.com/en/docs/api/receiving/technology-webhook-endpoint/

This SDK does **not** ship a webhook HTTP server. Configure the instance, then run your
own endpoint that accepts POST JSON and returns 200:

```python
greenAPI.account.setSettings({
"webhookUrl": "https://your.public.host/webhook",
"webhookUrlToken": "Bearer your-secret", # optional; see docs for Basic/Bearer
"incomingWebhook": "yes",
"outgoingWebhook": "yes",
"outgoingAPIMessageWebhook": "yes",
"stateWebhook": "yes",
})
```

GREEN-API POSTs notification JSON to `webhookUrl`. Retries every ~1 minute; guaranteed
within 24 hours. While `webhookUrl` is set, **polling will not receive** those notifications.

Common `typeWebhook` values: `incomingMessageReceived`, `outgoingMessageReceived`,
`outgoingAPIMessageReceived`, `outgoingMessageStatus`, `stateInstanceChanged`,
`statusInstanceChanged`, `incomingCall`, `outgoingCall`, `quotaExceeded`, …
Full list: https://green-api.com/en/docs/api/receiving/notifications-format/type-webhook/

### 6. Create a group and message it

Docs: https://green-api.com/en/docs/api/groups/CreateGroup/

```python
created = greenAPI.groups.createGroup("Group Name", ["79876543210@c.us"])
if created.code == 200 and created.data.get("created"):
chat_id = created.data["chatId"] # ...@g.us
greenAPI.sending.sendMessage(chat_id, "Hello group")
```

Do not create groups faster than about **1 per 5 minutes** (anti-spam). Invalid numbers
can get the sender blocked.

## API surface map (SDK attributes)

Access as `greenAPI.<group>.<method>(...)`.

| Attribute | Class | Reference |
| --- | --- | --- |
| `account` | `Account` | [references/account.md](references/account.md) |
| `sending` | `Sending` | [references/sending.md](references/sending.md) |
| `receiving` | `Receiving` | [references/receiving.md](references/receiving.md) |
| `webhooks` | `Webhooks` | [references/receiving.md](references/receiving.md) |
| `groups` | `Groups` | [references/groups.md](references/groups.md) |
| `journals` | `Journals` | [references/journals.md](references/journals.md) |
| `queues` | `Queues` | [references/queues.md](references/queues.md) |
| `serviceMethods` | `ServiceMethods` | [references/service-methods.md](references/service-methods.md) |
| `marking` | `Marking` | [references/marking.md](references/marking.md) |
| `contacts` | `Contacts` | [references/contacts.md](references/contacts.md) |
| `statuses` | `Statuses` | [references/statuses.md](references/statuses.md) |
| `device` | `Device` | [references/device.md](references/device.md) |
| `partner` | `Partner` | only on `GreenApiPartner` — [references/partner.md](references/partner.md) |

Full method list + signatures: [references/inventory.md](references/inventory.md).

## Pitfalls (read before coding)

1. **`chatId` format** — personal `phone@c.us`, group `id@g.us`. No `+` in the phone part.
2. **Authorized instance** — `getStateInstance` must be `authorized` for delivery.
3. **Polling vs webhook** — mutually exclusive for the same traffic: clear `webhookUrl`
for HTTP API polling; set `webhookUrl` for push.
4. **Always `deleteNotification`** after processing a polled notification, or the same
event will be returned forever.
5. **Sending delay** — use `delaySendMessagesMilliseconds` ≥ 500 ms; bulk blasts without
delay risk limits / bans.
6. **File size** — max 100 MB; `sendFileByUpload` goes to `media.green-api.com`.
7. **Response handling** — use `response.data` only when `response.code == 200`.
8. **Deprecated sending APIs** still in SDK but marked deprecated: `sendButtons`,
`sendTemplateButtons`, `sendListMessage`, `sendLink` — prefer
`sendInteractiveButtons` / `sendInteractiveButtonsReply` / `sendMessage`.
9. **`serviceMethods` attribute name** — camelCase `serviceMethods`, not `service`.
10. **Partner methods** require `GreenApiPartner`, not `GreenAPI`.
11. **Groups rate limit** — create groups slowly; non-existent numbers are dangerous.
12. **Hosts** — default `api.green-api.com` / `media.green-api.com`; some accounts use
instance-specific hosts from console — pass `host=` / `media=` if console shows them.

## Agent checklist

When writing code for the user:

- [ ] Import `from whatsapp_api_client_python import API`
- [ ] Init `API.GreenAPI(idInstance, apiTokenInstance)` with real or env credentials
- [ ] Use only methods from [references/inventory.md](references/inventory.md)
- [ ] Format `chatId` as `@c.us` / `@g.us`
- [ ] Check `response.code` before `response.data`
- [ ] For receive: either polling (`startReceivingNotifications` / manual receive+delete)
or webhook endpoint + `setSettings`, not a fictional SDK method
- [ ] Prefer reading the matching `references/*.md` file for parameters before coding
- [ ] Prefer official docs URL from the method docstring when unsure about edge cases
Loading
Loading