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.
Files changed (24) hide show
  1. lakshyapocketlab_hello-0.1.0/.gitignore +12 -0
  2. lakshyapocketlab_hello-0.1.0/CHANGELOG.md +8 -0
  3. lakshyapocketlab_hello-0.1.0/LICENSE +21 -0
  4. lakshyapocketlab_hello-0.1.0/PKG-INFO +241 -0
  5. lakshyapocketlab_hello-0.1.0/README.md +203 -0
  6. lakshyapocketlab_hello-0.1.0/examples/send_template.py +25 -0
  7. lakshyapocketlab_hello-0.1.0/examples/send_text.py +20 -0
  8. lakshyapocketlab_hello-0.1.0/examples/upload_and_send_media.py +20 -0
  9. lakshyapocketlab_hello-0.1.0/pyproject.toml +86 -0
  10. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/__init__.py +29 -0
  11. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_client.py +174 -0
  12. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_core.py +206 -0
  13. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_resources_async.py +259 -0
  14. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_resources_sync.py +253 -0
  15. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_specs.py +254 -0
  16. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/_version.py +1 -0
  17. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/errors.py +125 -0
  18. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/py.typed +0 -0
  19. lakshyapocketlab_hello-0.1.0/src/lakshyapocketlab_hello/types.py +117 -0
  20. lakshyapocketlab_hello-0.1.0/tests/__init__.py +0 -0
  21. lakshyapocketlab_hello-0.1.0/tests/conftest.py +70 -0
  22. lakshyapocketlab_hello-0.1.0/tests/test_client_options.py +103 -0
  23. lakshyapocketlab_hello-0.1.0/tests/test_errors_retries.py +342 -0
  24. lakshyapocketlab_hello-0.1.0/tests/test_resources.py +383 -0
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .mypy_cache/
5
+ .ruff_cache/
6
+ .pytest_cache/
7
+ .coverage
8
+ coverage.xml
9
+ htmlcov/
10
+ dist/
11
+ build/
12
+ *.egg-info/
@@ -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
+ [![CI](https://github.com/lakshyapocketlab/hello-python/actions/workflows/ci.yml/badge.svg)](https://github.com/lakshyapocketlab/hello-python/actions/workflows/ci.yml)
44
+ [![PyPI](https://img.shields.io/pypi/v/lakshyapocketlab-hello)](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
+ [![CI](https://github.com/lakshyapocketlab/hello-python/actions/workflows/ci.yml/badge.svg)](https://github.com/lakshyapocketlab/hello-python/actions/workflows/ci.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/lakshyapocketlab-hello)](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
+ ]