lakshyapocketlab-hello 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lakshyapocketlab_hello-0.1.0/.gitignore +12 -0
- lakshyapocketlab_hello-0.1.0/CHANGELOG.md +8 -0
- lakshyapocketlab_hello-0.1.0/LICENSE +21 -0
- lakshyapocketlab_hello-0.1.0/PKG-INFO +241 -0
- lakshyapocketlab_hello-0.1.0/README.md +203 -0
- lakshyapocketlab_hello-0.1.0/examples/send_template.py +25 -0
- lakshyapocketlab_hello-0.1.0/examples/send_text.py +20 -0
- lakshyapocketlab_hello-0.1.0/examples/upload_and_send_media.py +20 -0
- lakshyapocketlab_hello-0.1.0/pyproject.toml +86 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/__init__.py +29 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_client.py +174 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_core.py +206 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_resources_async.py +259 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_resources_sync.py +253 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_specs.py +254 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_version.py +1 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/errors.py +125 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/py.typed +0 -0
- lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/types.py +117 -0
- lakshyapocketlab_hello-0.1.0/tests/__init__.py +0 -0
- lakshyapocketlab_hello-0.1.0/tests/conftest.py +70 -0
- lakshyapocketlab_hello-0.1.0/tests/test_client_options.py +103 -0
- lakshyapocketlab_hello-0.1.0/tests/test_errors_retries.py +342 -0
- lakshyapocketlab_hello-0.1.0/tests/test_resources.py +383 -0
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
- Initial release: sync `Hello` and async `AsyncHello` clients for the Hello `/v1` Integration API
|
|
6
|
+
(ping, phone numbers, messages, media, templates, direct webhook override).
|
|
7
|
+
- Typed exceptions for both error envelopes, retries with backoff and `Retry-After`,
|
|
8
|
+
idempotency-key-gated send retries.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lakshya Pocket Lab
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: lakshyapocketlab-hello
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Official Python SDK for Hello, the WhatsApp Business API. Send messages, templates and webhooks.
|
|
5
|
+
Project-URL: Homepage, https://github.com/lakshyapocketlab/hello-python
|
|
6
|
+
Project-URL: Repository, https://github.com/lakshyapocketlab/hello-python
|
|
7
|
+
Project-URL: Issues, https://github.com/lakshyapocketlab/hello-python/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/lakshyapocketlab/hello-python/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Lakshya Pocket Lab
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: mcp,wa-business,whatsapp,whatsapp-api,whatsapp-business,whatsapp-cloud-api
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Framework :: AsyncIO
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Topic :: Communications :: Chat
|
|
26
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
27
|
+
Classifier: Typing :: Typed
|
|
28
|
+
Requires-Python: >=3.9
|
|
29
|
+
Requires-Dist: httpx<1,>=0.25
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
32
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
35
|
+
Requires-Dist: respx>=0.21; extra == 'dev'
|
|
36
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
37
|
+
Description-Content-Type: text/markdown
|
|
38
|
+
|
|
39
|
+
# Hello Python SDK for the WhatsApp Business API
|
|
40
|
+
|
|
41
|
+
Official Python SDK for Hello, the WhatsApp Business API. Send messages, templates and webhooks.
|
|
42
|
+
|
|
43
|
+
[](https://github.com/lakshyapocketlab/hello-python/actions/workflows/ci.yml)
|
|
44
|
+
[](https://pypi.org/project/lakshyapocketlab-hello/)
|
|
45
|
+
|
|
46
|
+
A typed, sync and async client for the Hello `/v1` Integration API (a drop-in for the WhatsApp
|
|
47
|
+
Cloud API). Python 3.9+, one dependency (`httpx`), `py.typed`, 100% test coverage.
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install lakshyapocketlab-hello
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The distribution is `lakshyapocketlab-hello`; the import package is `lakshyapocketlab_hello`.
|
|
56
|
+
|
|
57
|
+
## Quickstart
|
|
58
|
+
|
|
59
|
+
Create an API key (`hello_live_...`) in the Hello dashboard and export it:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
export HELLO_API_KEY=hello_live_xxxxxxxx
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
from lakshyapocketlab_hello import Hello
|
|
67
|
+
|
|
68
|
+
with Hello() as client: # reads HELLO_API_KEY
|
|
69
|
+
number = client.phone_numbers.list()["data"][0]
|
|
70
|
+
sent = client.messages.send_text(
|
|
71
|
+
number["phone_number_id"], "+919999999999", "Hello from Python!"
|
|
72
|
+
)
|
|
73
|
+
print(sent["messages"][0]["hello_id"])
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Async:
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
import asyncio
|
|
80
|
+
from lakshyapocketlab_hello import AsyncHello
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
async def main() -> None:
|
|
84
|
+
async with AsyncHello() as client:
|
|
85
|
+
await client.ping()
|
|
86
|
+
await client.messages.send_template(
|
|
87
|
+
"106540352242922",
|
|
88
|
+
"+919999999999",
|
|
89
|
+
"order_shipped",
|
|
90
|
+
"en",
|
|
91
|
+
components=[{"type": "body", "parameters": [{"type": "text", "text": "Asha"}]}],
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
asyncio.run(main())
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Client options
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
Hello(api_key=None, base_url=None, timeout=30, max_retries=2, http_client=None)
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
| Option | Default | Notes |
|
|
105
|
+
|---|---|---|
|
|
106
|
+
| `api_key` | env `HELLO_API_KEY` | `HelloError` is raised if neither is set |
|
|
107
|
+
| `base_url` | `https://api.lakshyapocketlab.com` | staging / self-host |
|
|
108
|
+
| `timeout` | `30` | seconds, or an `httpx.Timeout` |
|
|
109
|
+
| `max_retries` | `2` | see [Retries](#retries) |
|
|
110
|
+
| `http_client` | none | your own `httpx.Client` / `httpx.AsyncClient` (proxies, mTLS); you close it |
|
|
111
|
+
|
|
112
|
+
Requests send `Authorization: Bearer <key>` and `User-Agent: lakshyapocketlab-hello-python/<version>`.
|
|
113
|
+
`AsyncHello` has the identical surface; every method is awaited.
|
|
114
|
+
|
|
115
|
+
## Methods
|
|
116
|
+
|
|
117
|
+
All methods return the decoded JSON as a `dict` (except `media.download`, which returns `bytes`).
|
|
118
|
+
Message and template bodies accept plain dicts or the `TypedDict`s in `lakshyapocketlab_hello.types`.
|
|
119
|
+
|
|
120
|
+
| Method | Route |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `client.ping()` | `GET /v1/ping` |
|
|
123
|
+
| `client.phone_numbers.list()` | `GET /v1/phone_numbers` |
|
|
124
|
+
| `client.phone_numbers.list_for_waba(waba_id)` | `GET /v1/{waba_id}/phone_numbers` |
|
|
125
|
+
| `client.messages.send(phone_number_id, message, *, sync, async_, idempotency_key)` | `POST /v1/{phone_number_id}/messages` |
|
|
126
|
+
| `client.messages.send_text(pnid, to, body, *, preview_url, reply_to, ...)` | same |
|
|
127
|
+
| `client.messages.send_template(pnid, to, name, language="en_US", components=None, ...)` | same |
|
|
128
|
+
| `client.messages.send_media(pnid, to, "image", media_id=... or link=..., caption, filename, ...)` | same |
|
|
129
|
+
| `client.messages.mark_as_read(pnid, message_id, *, typing_indicator)` | same, `status: read` |
|
|
130
|
+
| `client.messages.get(message_id)` | `GET /v1/messages/{id}` |
|
|
131
|
+
| `client.media.upload(pnid, file, mime_type, filename=None)` | `POST /v1/{pnid}/media` |
|
|
132
|
+
| `client.media.get(media_id)` | `GET /v1/{media_id}` |
|
|
133
|
+
| `client.media.download(media_id)` | `GET /v1/{media_id}/download` |
|
|
134
|
+
| `client.templates.list(waba_id, *, name, search, status, category, language, limit, after, before, summary, sort_by, sort_order)` | `GET /v1/{waba_id}/message_templates` |
|
|
135
|
+
| `client.templates.get(template_id)` | `GET /v1/templates/{id}` |
|
|
136
|
+
| `client.templates.create(waba_id, template)` | `POST /v1/{waba_id}/message_templates` |
|
|
137
|
+
| `client.templates.create_bulk(waba_id, templates)` | `POST /v1/{waba_id}/templates/bulk` |
|
|
138
|
+
| `client.templates.edit(template_id, changes)` | `POST /v1/templates/{id}` |
|
|
139
|
+
| `client.templates.sync(waba_id)` | `POST /v1/{waba_id}/templates/sync` |
|
|
140
|
+
| `client.templates.delete(template_id)` | `DELETE /v1/templates/{id}` |
|
|
141
|
+
| `client.templates.delete_by_name(waba_id, name)` | `DELETE /v1/{waba_id}/message_templates?name=` |
|
|
142
|
+
| `client.webhook_override.get(pnid, *, refresh=False)` | `GET /v1/{pnid}/webhook-override` |
|
|
143
|
+
| `client.webhook_override.set(pnid, url, verify_token, *, acknowledge_no_tracking)` | `PUT /v1/{pnid}/webhook-override` |
|
|
144
|
+
| `client.webhook_override.remove(pnid)` | `DELETE /v1/{pnid}/webhook-override` |
|
|
145
|
+
| `client.webhook_override.reapply(pnid)` | `POST /v1/{pnid}/webhook-override/reapply` |
|
|
146
|
+
|
|
147
|
+
### Sending
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
# Raw Cloud API body: any message type
|
|
151
|
+
client.messages.send(pnid, {"to": "+16505551234", "type": "text", "text": {"body": "Hi"}})
|
|
152
|
+
|
|
153
|
+
# Wait up to 25 s for WhatsApp to accept (messages[0].id is the wamid), or return queued:
|
|
154
|
+
client.messages.send_text(pnid, to, "Hi", sync=True)
|
|
155
|
+
client.messages.send_text(pnid, to, "Hi", async_=True)
|
|
156
|
+
|
|
157
|
+
# Safe retries: the same key returns the original message instead of sending again
|
|
158
|
+
client.messages.send_template(pnid, to, "promo", "en", idempotency_key="order-1042")
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Free-form types need an open 24-hour window; otherwise send an approved template.
|
|
162
|
+
`to` must include the `+` and country code.
|
|
163
|
+
|
|
164
|
+
### Media
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
media = client.media.upload(pnid, "invoice.pdf", "application/pdf") # path
|
|
168
|
+
media = client.media.upload(pnid, pdf_bytes, "application/pdf", "invoice.pdf") # bytes
|
|
169
|
+
with open("photo.jpg", "rb") as fh: # file object
|
|
170
|
+
media = client.media.upload(pnid, fh, "image/jpeg")
|
|
171
|
+
client.messages.send_media(pnid, to, "document", media_id=media["id"], filename="invoice.pdf")
|
|
172
|
+
|
|
173
|
+
data = client.media.download(inbound_media_id) # bytes
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Templates and direct webhooks
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
client.templates.list(waba_id, status="APPROVED", limit=50)
|
|
180
|
+
client.templates.create(
|
|
181
|
+
waba_id,
|
|
182
|
+
{
|
|
183
|
+
"name": "order_shipped",
|
|
184
|
+
"language": "en",
|
|
185
|
+
"category": "UTILITY",
|
|
186
|
+
"components": [{"type": "BODY", "text": "Order {{1}} shipped."}],
|
|
187
|
+
},
|
|
188
|
+
)
|
|
189
|
+
client.webhook_override.set(
|
|
190
|
+
pnid, "https://example.com/hooks/meta/9f2c4e1a", "my-verify-token", acknowledge_no_tracking=True
|
|
191
|
+
)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`webhook_override.set` stops Hello from showing that number's incoming messages and delivery
|
|
195
|
+
statuses; read the Hello docs before enabling it.
|
|
196
|
+
|
|
197
|
+
## Errors
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
from lakshyapocketlab_hello import APIError, RateLimitError, HelloError
|
|
201
|
+
|
|
202
|
+
try:
|
|
203
|
+
client.messages.send_text(pnid, to, "Hi")
|
|
204
|
+
except RateLimitError as e:
|
|
205
|
+
print("retry in", e.retry_after)
|
|
206
|
+
except APIError as e:
|
|
207
|
+
print(e.status, e.message, e.code, e.subcode, e.hello_code, e.fbtrace_id, e.details)
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
| Exception | When |
|
|
211
|
+
|---|---|
|
|
212
|
+
| `HelloError` | base class of everything below; also missing API key |
|
|
213
|
+
| `APIError` | any non-2xx: `status`, `message`, `code`, `subcode`, `hello_code`, `fbtrace_id`, `details`, `body`, `retry_after` |
|
|
214
|
+
| `AuthenticationError` | 401 |
|
|
215
|
+
| `NotFoundError` | 404 |
|
|
216
|
+
| `RateLimitError` | 429 |
|
|
217
|
+
| `APIConnectionError` | no response (DNS, TLS, reset) |
|
|
218
|
+
| `APITimeoutError` | timeout (subclass of `APIConnectionError`) |
|
|
219
|
+
|
|
220
|
+
Both error envelopes are parsed: Meta-style `{"error": {message, code, error_subcode,
|
|
221
|
+
error_data: {details, hello_code}, fbtrace_id}}` on send/media routes, and Hello's `{message, code}`
|
|
222
|
+
elsewhere (where `code` becomes `hello_code`).
|
|
223
|
+
|
|
224
|
+
## Retries
|
|
225
|
+
|
|
226
|
+
429, 5xx and network errors are retried `max_retries` times with exponential backoff and jitter
|
|
227
|
+
(0.5 s, 1 s, 2 s ... capped at 8 s), honouring `Retry-After` (a wait over 60 s raises instead).
|
|
228
|
+
Retried calls: GET, PUT, DELETE, `templates.sync`, `mark_as_read`, `webhook_override.reapply`, and
|
|
229
|
+
`messages.send*` **only when you pass `idempotency_key`**. Plain sends, template create/edit and
|
|
230
|
+
media upload are never retried automatically, so a billed message is never sent twice by accident.
|
|
231
|
+
|
|
232
|
+
## Development
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
|
236
|
+
.venv/bin/ruff check . && .venv/bin/mypy && .venv/bin/pytest
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
|
|
241
|
+
MIT, Copyright (c) 2026 Lakshya Pocket Lab.
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# Hello Python SDK for the WhatsApp Business API
|
|
2
|
+
|
|
3
|
+
Official Python SDK for Hello, the WhatsApp Business API. Send messages, templates and webhooks.
|
|
4
|
+
|
|
5
|
+
[](https://github.com/lakshyapocketlab/hello-python/actions/workflows/ci.yml)
|
|
6
|
+
[](https://pypi.org/project/lakshyapocketlab-hello/)
|
|
7
|
+
|
|
8
|
+
A typed, sync and async client for the Hello `/v1` Integration API (a drop-in for the WhatsApp
|
|
9
|
+
Cloud API). Python 3.9+, one dependency (`httpx`), `py.typed`, 100% test coverage.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install lakshyapocketlab-hello
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The distribution is `lakshyapocketlab-hello`; the import package is `lakshyapocketlab_hello`.
|
|
18
|
+
|
|
19
|
+
## Quickstart
|
|
20
|
+
|
|
21
|
+
Create an API key (`hello_live_...`) in the Hello dashboard and export it:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
export HELLO_API_KEY=hello_live_xxxxxxxx
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from lakshyapocketlab_hello import Hello
|
|
29
|
+
|
|
30
|
+
with Hello() as client: # reads HELLO_API_KEY
|
|
31
|
+
number = client.phone_numbers.list()["data"][0]
|
|
32
|
+
sent = client.messages.send_text(
|
|
33
|
+
number["phone_number_id"], "+919999999999", "Hello from Python!"
|
|
34
|
+
)
|
|
35
|
+
print(sent["messages"][0]["hello_id"])
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Async:
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import asyncio
|
|
42
|
+
from lakshyapocketlab_hello import AsyncHello
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
async def main() -> None:
|
|
46
|
+
async with AsyncHello() as client:
|
|
47
|
+
await client.ping()
|
|
48
|
+
await client.messages.send_template(
|
|
49
|
+
"106540352242922",
|
|
50
|
+
"+919999999999",
|
|
51
|
+
"order_shipped",
|
|
52
|
+
"en",
|
|
53
|
+
components=[{"type": "body", "parameters": [{"type": "text", "text": "Asha"}]}],
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
asyncio.run(main())
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Client options
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
Hello(api_key=None, base_url=None, timeout=30, max_retries=2, http_client=None)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
| Option | Default | Notes |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| `api_key` | env `HELLO_API_KEY` | `HelloError` is raised if neither is set |
|
|
69
|
+
| `base_url` | `https://api.lakshyapocketlab.com` | staging / self-host |
|
|
70
|
+
| `timeout` | `30` | seconds, or an `httpx.Timeout` |
|
|
71
|
+
| `max_retries` | `2` | see [Retries](#retries) |
|
|
72
|
+
| `http_client` | none | your own `httpx.Client` / `httpx.AsyncClient` (proxies, mTLS); you close it |
|
|
73
|
+
|
|
74
|
+
Requests send `Authorization: Bearer <key>` and `User-Agent: lakshyapocketlab-hello-python/<version>`.
|
|
75
|
+
`AsyncHello` has the identical surface; every method is awaited.
|
|
76
|
+
|
|
77
|
+
## Methods
|
|
78
|
+
|
|
79
|
+
All methods return the decoded JSON as a `dict` (except `media.download`, which returns `bytes`).
|
|
80
|
+
Message and template bodies accept plain dicts or the `TypedDict`s in `lakshyapocketlab_hello.types`.
|
|
81
|
+
|
|
82
|
+
| Method | Route |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `client.ping()` | `GET /v1/ping` |
|
|
85
|
+
| `client.phone_numbers.list()` | `GET /v1/phone_numbers` |
|
|
86
|
+
| `client.phone_numbers.list_for_waba(waba_id)` | `GET /v1/{waba_id}/phone_numbers` |
|
|
87
|
+
| `client.messages.send(phone_number_id, message, *, sync, async_, idempotency_key)` | `POST /v1/{phone_number_id}/messages` |
|
|
88
|
+
| `client.messages.send_text(pnid, to, body, *, preview_url, reply_to, ...)` | same |
|
|
89
|
+
| `client.messages.send_template(pnid, to, name, language="en_US", components=None, ...)` | same |
|
|
90
|
+
| `client.messages.send_media(pnid, to, "image", media_id=... or link=..., caption, filename, ...)` | same |
|
|
91
|
+
| `client.messages.mark_as_read(pnid, message_id, *, typing_indicator)` | same, `status: read` |
|
|
92
|
+
| `client.messages.get(message_id)` | `GET /v1/messages/{id}` |
|
|
93
|
+
| `client.media.upload(pnid, file, mime_type, filename=None)` | `POST /v1/{pnid}/media` |
|
|
94
|
+
| `client.media.get(media_id)` | `GET /v1/{media_id}` |
|
|
95
|
+
| `client.media.download(media_id)` | `GET /v1/{media_id}/download` |
|
|
96
|
+
| `client.templates.list(waba_id, *, name, search, status, category, language, limit, after, before, summary, sort_by, sort_order)` | `GET /v1/{waba_id}/message_templates` |
|
|
97
|
+
| `client.templates.get(template_id)` | `GET /v1/templates/{id}` |
|
|
98
|
+
| `client.templates.create(waba_id, template)` | `POST /v1/{waba_id}/message_templates` |
|
|
99
|
+
| `client.templates.create_bulk(waba_id, templates)` | `POST /v1/{waba_id}/templates/bulk` |
|
|
100
|
+
| `client.templates.edit(template_id, changes)` | `POST /v1/templates/{id}` |
|
|
101
|
+
| `client.templates.sync(waba_id)` | `POST /v1/{waba_id}/templates/sync` |
|
|
102
|
+
| `client.templates.delete(template_id)` | `DELETE /v1/templates/{id}` |
|
|
103
|
+
| `client.templates.delete_by_name(waba_id, name)` | `DELETE /v1/{waba_id}/message_templates?name=` |
|
|
104
|
+
| `client.webhook_override.get(pnid, *, refresh=False)` | `GET /v1/{pnid}/webhook-override` |
|
|
105
|
+
| `client.webhook_override.set(pnid, url, verify_token, *, acknowledge_no_tracking)` | `PUT /v1/{pnid}/webhook-override` |
|
|
106
|
+
| `client.webhook_override.remove(pnid)` | `DELETE /v1/{pnid}/webhook-override` |
|
|
107
|
+
| `client.webhook_override.reapply(pnid)` | `POST /v1/{pnid}/webhook-override/reapply` |
|
|
108
|
+
|
|
109
|
+
### Sending
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
# Raw Cloud API body: any message type
|
|
113
|
+
client.messages.send(pnid, {"to": "+16505551234", "type": "text", "text": {"body": "Hi"}})
|
|
114
|
+
|
|
115
|
+
# Wait up to 25 s for WhatsApp to accept (messages[0].id is the wamid), or return queued:
|
|
116
|
+
client.messages.send_text(pnid, to, "Hi", sync=True)
|
|
117
|
+
client.messages.send_text(pnid, to, "Hi", async_=True)
|
|
118
|
+
|
|
119
|
+
# Safe retries: the same key returns the original message instead of sending again
|
|
120
|
+
client.messages.send_template(pnid, to, "promo", "en", idempotency_key="order-1042")
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Free-form types need an open 24-hour window; otherwise send an approved template.
|
|
124
|
+
`to` must include the `+` and country code.
|
|
125
|
+
|
|
126
|
+
### Media
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
media = client.media.upload(pnid, "invoice.pdf", "application/pdf") # path
|
|
130
|
+
media = client.media.upload(pnid, pdf_bytes, "application/pdf", "invoice.pdf") # bytes
|
|
131
|
+
with open("photo.jpg", "rb") as fh: # file object
|
|
132
|
+
media = client.media.upload(pnid, fh, "image/jpeg")
|
|
133
|
+
client.messages.send_media(pnid, to, "document", media_id=media["id"], filename="invoice.pdf")
|
|
134
|
+
|
|
135
|
+
data = client.media.download(inbound_media_id) # bytes
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Templates and direct webhooks
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
client.templates.list(waba_id, status="APPROVED", limit=50)
|
|
142
|
+
client.templates.create(
|
|
143
|
+
waba_id,
|
|
144
|
+
{
|
|
145
|
+
"name": "order_shipped",
|
|
146
|
+
"language": "en",
|
|
147
|
+
"category": "UTILITY",
|
|
148
|
+
"components": [{"type": "BODY", "text": "Order {{1}} shipped."}],
|
|
149
|
+
},
|
|
150
|
+
)
|
|
151
|
+
client.webhook_override.set(
|
|
152
|
+
pnid, "https://example.com/hooks/meta/9f2c4e1a", "my-verify-token", acknowledge_no_tracking=True
|
|
153
|
+
)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`webhook_override.set` stops Hello from showing that number's incoming messages and delivery
|
|
157
|
+
statuses; read the Hello docs before enabling it.
|
|
158
|
+
|
|
159
|
+
## Errors
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from lakshyapocketlab_hello import APIError, RateLimitError, HelloError
|
|
163
|
+
|
|
164
|
+
try:
|
|
165
|
+
client.messages.send_text(pnid, to, "Hi")
|
|
166
|
+
except RateLimitError as e:
|
|
167
|
+
print("retry in", e.retry_after)
|
|
168
|
+
except APIError as e:
|
|
169
|
+
print(e.status, e.message, e.code, e.subcode, e.hello_code, e.fbtrace_id, e.details)
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
| Exception | When |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `HelloError` | base class of everything below; also missing API key |
|
|
175
|
+
| `APIError` | any non-2xx: `status`, `message`, `code`, `subcode`, `hello_code`, `fbtrace_id`, `details`, `body`, `retry_after` |
|
|
176
|
+
| `AuthenticationError` | 401 |
|
|
177
|
+
| `NotFoundError` | 404 |
|
|
178
|
+
| `RateLimitError` | 429 |
|
|
179
|
+
| `APIConnectionError` | no response (DNS, TLS, reset) |
|
|
180
|
+
| `APITimeoutError` | timeout (subclass of `APIConnectionError`) |
|
|
181
|
+
|
|
182
|
+
Both error envelopes are parsed: Meta-style `{"error": {message, code, error_subcode,
|
|
183
|
+
error_data: {details, hello_code}, fbtrace_id}}` on send/media routes, and Hello's `{message, code}`
|
|
184
|
+
elsewhere (where `code` becomes `hello_code`).
|
|
185
|
+
|
|
186
|
+
## Retries
|
|
187
|
+
|
|
188
|
+
429, 5xx and network errors are retried `max_retries` times with exponential backoff and jitter
|
|
189
|
+
(0.5 s, 1 s, 2 s ... capped at 8 s), honouring `Retry-After` (a wait over 60 s raises instead).
|
|
190
|
+
Retried calls: GET, PUT, DELETE, `templates.sync`, `mark_as_read`, `webhook_override.reapply`, and
|
|
191
|
+
`messages.send*` **only when you pass `idempotency_key`**. Plain sends, template create/edit and
|
|
192
|
+
media upload are never retried automatically, so a billed message is never sent twice by accident.
|
|
193
|
+
|
|
194
|
+
## Development
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
|
198
|
+
.venv/bin/ruff check . && .venv/bin/mypy && .venv/bin/pytest
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
MIT, Copyright (c) 2026 Lakshya Pocket Lab.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Send an approved template (the only type that can start a conversation)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import sys
|
|
6
|
+
|
|
7
|
+
from lakshyapocketlab_hello import Hello
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def main(to: str, template_name: str) -> None:
|
|
11
|
+
with Hello() as client:
|
|
12
|
+
number = client.phone_numbers.list()["data"][0]
|
|
13
|
+
sent = client.messages.send_template(
|
|
14
|
+
number["phone_number_id"],
|
|
15
|
+
to,
|
|
16
|
+
template_name,
|
|
17
|
+
"en_US",
|
|
18
|
+
components=[{"type": "body", "parameters": [{"type": "text", "text": "Asha"}]}],
|
|
19
|
+
idempotency_key=f"example-{template_name}-{to}", # makes retries safe
|
|
20
|
+
)
|
|
21
|
+
print(sent["messages"][0]["hello_id"])
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
if __name__ == "__main__":
|
|
25
|
+
main(sys.argv[1], sys.argv[2])
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""Send a text message. Needs an open 24-hour window with the recipient."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import sys
|
|
6
|
+
|
|
7
|
+
from lakshyapocketlab_hello import Hello
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def main(to: str) -> None:
|
|
11
|
+
with Hello() as client: # reads HELLO_API_KEY
|
|
12
|
+
number = client.phone_numbers.list()["data"][0]
|
|
13
|
+
sent = client.messages.send_text(
|
|
14
|
+
number["phone_number_id"], to, "Hello from the Hello Python SDK!", sync=True
|
|
15
|
+
)
|
|
16
|
+
print(sent["messages"][0]["id"])
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
if __name__ == "__main__":
|
|
20
|
+
main(sys.argv[1])
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""Upload a file, then send it as a document."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import sys
|
|
6
|
+
|
|
7
|
+
from lakshyapocketlab_hello import Hello
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def main(to: str, path: str) -> None:
|
|
11
|
+
with Hello() as client:
|
|
12
|
+
number = client.phone_numbers.list()["data"][0]
|
|
13
|
+
pnid = number["phone_number_id"]
|
|
14
|
+
media = client.media.upload(pnid, path, "application/pdf")
|
|
15
|
+
sent = client.messages.send_media(pnid, to, "document", media_id=media["id"])
|
|
16
|
+
print(sent["messages"][0]["hello_id"])
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
if __name__ == "__main__":
|
|
20
|
+
main(sys.argv[1], sys.argv[2])
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "lakshyapocketlab-hello"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Official Python SDK for Hello, the WhatsApp Business API. Send messages, templates and webhooks."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.9"
|
|
13
|
+
authors = [{ name = "Lakshya Pocket Lab" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"whatsapp",
|
|
16
|
+
"whatsapp-business",
|
|
17
|
+
"whatsapp-api",
|
|
18
|
+
"wa-business",
|
|
19
|
+
"whatsapp-cloud-api",
|
|
20
|
+
"mcp",
|
|
21
|
+
]
|
|
22
|
+
classifiers = [
|
|
23
|
+
"Development Status :: 4 - Beta",
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"License :: OSI Approved :: MIT License",
|
|
26
|
+
"Operating System :: OS Independent",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
29
|
+
"Programming Language :: Python :: 3.9",
|
|
30
|
+
"Programming Language :: Python :: 3.10",
|
|
31
|
+
"Programming Language :: Python :: 3.11",
|
|
32
|
+
"Programming Language :: Python :: 3.12",
|
|
33
|
+
"Programming Language :: Python :: 3.13",
|
|
34
|
+
"Topic :: Communications :: Chat",
|
|
35
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
36
|
+
"Typing :: Typed",
|
|
37
|
+
"Framework :: AsyncIO",
|
|
38
|
+
]
|
|
39
|
+
dependencies = ["httpx>=0.25,<1"]
|
|
40
|
+
|
|
41
|
+
[project.optional-dependencies]
|
|
42
|
+
dev = [
|
|
43
|
+
"pytest>=8",
|
|
44
|
+
"pytest-asyncio>=0.23",
|
|
45
|
+
"pytest-cov>=5",
|
|
46
|
+
"respx>=0.21",
|
|
47
|
+
"ruff>=0.5",
|
|
48
|
+
"mypy>=1.10",
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
[project.urls]
|
|
52
|
+
Homepage = "https://github.com/lakshyapocketlab/hello-python"
|
|
53
|
+
Repository = "https://github.com/lakshyapocketlab/hello-python"
|
|
54
|
+
Issues = "https://github.com/lakshyapocketlab/hello-python/issues"
|
|
55
|
+
Changelog = "https://github.com/lakshyapocketlab/hello-python/blob/main/CHANGELOG.md"
|
|
56
|
+
|
|
57
|
+
[tool.hatch.version]
|
|
58
|
+
path = "src/lakshyapocketlab_hello/_version.py"
|
|
59
|
+
|
|
60
|
+
[tool.hatch.build.targets.wheel]
|
|
61
|
+
packages = ["src/lakshyapocketlab_hello"]
|
|
62
|
+
|
|
63
|
+
[tool.hatch.build.targets.sdist]
|
|
64
|
+
include = ["src", "tests", "examples", "README.md", "LICENSE", "CHANGELOG.md"]
|
|
65
|
+
|
|
66
|
+
[tool.pytest.ini_options]
|
|
67
|
+
testpaths = ["tests"]
|
|
68
|
+
asyncio_mode = "auto"
|
|
69
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
70
|
+
addopts = "--cov=lakshyapocketlab_hello --cov-branch --cov-report=term-missing --cov-fail-under=100"
|
|
71
|
+
|
|
72
|
+
[tool.coverage.run]
|
|
73
|
+
source = ["lakshyapocketlab_hello"]
|
|
74
|
+
branch = true
|
|
75
|
+
|
|
76
|
+
[tool.mypy]
|
|
77
|
+
strict = true
|
|
78
|
+
files = ["src", "tests", "examples"]
|
|
79
|
+
|
|
80
|
+
[tool.ruff]
|
|
81
|
+
line-length = 100
|
|
82
|
+
target-version = "py39"
|
|
83
|
+
src = ["src", "tests"]
|
|
84
|
+
|
|
85
|
+
[tool.ruff.lint]
|
|
86
|
+
select = ["E", "F", "W", "I", "B", "SIM", "RUF"]
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Official Python SDK for Hello, the WhatsApp Business API.
|
|
2
|
+
|
|
3
|
+
from lakshyapocketlab_hello import Hello
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from ._client import AsyncHello, Hello
|
|
7
|
+
from ._version import __version__
|
|
8
|
+
from .errors import (
|
|
9
|
+
APIConnectionError,
|
|
10
|
+
APIError,
|
|
11
|
+
APITimeoutError,
|
|
12
|
+
AuthenticationError,
|
|
13
|
+
HelloError,
|
|
14
|
+
NotFoundError,
|
|
15
|
+
RateLimitError,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"APIConnectionError",
|
|
20
|
+
"APIError",
|
|
21
|
+
"APITimeoutError",
|
|
22
|
+
"AsyncHello",
|
|
23
|
+
"AuthenticationError",
|
|
24
|
+
"Hello",
|
|
25
|
+
"HelloError",
|
|
26
|
+
"NotFoundError",
|
|
27
|
+
"RateLimitError",
|
|
28
|
+
"__version__",
|
|
29
|
+
]
|