planvortex 0.17.0__tar.gz → 0.18.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 (109) hide show
  1. {planvortex-0.17.0 → planvortex-0.18.0}/CHANGELOG.md +28 -0
  2. {planvortex-0.17.0 → planvortex-0.18.0}/PKG-INFO +17 -2
  3. {planvortex-0.17.0 → planvortex-0.18.0}/README.md +16 -1
  4. {planvortex-0.17.0 → planvortex-0.18.0}/openapi/planvortex.openapi.json +249 -25
  5. {planvortex-0.17.0 → planvortex-0.18.0}/pyproject.toml +1 -1
  6. {planvortex-0.17.0 → planvortex-0.18.0}/scripts/route_coverage.py +2 -0
  7. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/__init__.py +2 -0
  8. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/errors.py +6 -2
  9. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/http.py +4 -1
  10. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/http_sync.py +4 -1
  11. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/transport.py +23 -2
  12. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_generated/models.py +38 -9
  13. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_version.py +1 -1
  14. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/base.py +43 -2
  15. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/comments.py +21 -1
  16. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/messages.py +29 -1
  17. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/base.py +41 -2
  18. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/comments.py +21 -1
  19. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/messages.py +29 -1
  20. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_comments.py +16 -0
  21. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_core.py +11 -0
  22. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_messages.py +82 -0
  23. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_route_coverage.py +5 -3
  24. {planvortex-0.17.0 → planvortex-0.18.0}/.gitignore +0 -0
  25. {planvortex-0.17.0 → planvortex-0.18.0}/LICENSE +0 -0
  26. {planvortex-0.17.0 → planvortex-0.18.0}/scripts/build_docs.py +0 -0
  27. {planvortex-0.17.0 → planvortex-0.18.0}/scripts/check_packaging.py +0 -0
  28. {planvortex-0.17.0 → planvortex-0.18.0}/scripts/generate_models.py +0 -0
  29. {planvortex-0.17.0 → planvortex-0.18.0}/scripts/generate_sync.py +0 -0
  30. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_client.py +0 -0
  31. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_client_sync.py +0 -0
  32. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/__init__.py +0 -0
  33. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/auth.py +0 -0
  34. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/auth_sync.py +0 -0
  35. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/files.py +0 -0
  36. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/pagination.py +0 -0
  37. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_core/query.py +0 -0
  38. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_generated/__init__.py +0 -0
  39. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/_shapes.py +0 -0
  40. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/py.typed +0 -0
  41. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/__init__.py +0 -0
  42. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/accounts.py +0 -0
  43. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/ai_plans.py +0 -0
  44. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/apps.py +0 -0
  45. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/catalog.py +0 -0
  46. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/clients.py +0 -0
  47. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/contacts.py +0 -0
  48. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/dashboard.py +0 -0
  49. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/integrations.py +0 -0
  50. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/organizations.py +0 -0
  51. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/products.py +0 -0
  52. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/publications.py +0 -0
  53. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources/uploads.py +0 -0
  54. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/__init__.py +0 -0
  55. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/accounts.py +0 -0
  56. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/ai_plans.py +0 -0
  57. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/apps.py +0 -0
  58. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/catalog.py +0 -0
  59. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/clients.py +0 -0
  60. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/contacts.py +0 -0
  61. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/dashboard.py +0 -0
  62. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/integrations.py +0 -0
  63. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/organizations.py +0 -0
  64. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/products.py +0 -0
  65. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/publications.py +0 -0
  66. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/resources_sync/uploads.py +0 -0
  67. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/types.py +0 -0
  68. {planvortex-0.17.0 → planvortex-0.18.0}/src/planvortex/webhooks.py +0 -0
  69. {planvortex-0.17.0 → planvortex-0.18.0}/tests/__init__.py +0 -0
  70. {planvortex-0.17.0 → planvortex-0.18.0}/tests/conftest.py +0 -0
  71. {planvortex-0.17.0 → planvortex-0.18.0}/tests/contrato.py +0 -0
  72. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/__init__.py +0 -0
  73. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/conftest.py +0 -0
  74. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/test_auth.py +0 -0
  75. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/test_catalog.py +0 -0
  76. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/test_connect_flow.py +0 -0
  77. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/test_errors.py +0 -0
  78. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/test_publish.py +0 -0
  79. {planvortex-0.17.0 → planvortex-0.18.0}/tests/live/test_read.py +0 -0
  80. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_accounts.py +0 -0
  81. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_ai_plans.py +0 -0
  82. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_apps.py +0 -0
  83. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_catalog.py +0 -0
  84. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_client.py +0 -0
  85. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_clients.py +0 -0
  86. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_contacts.py +0 -0
  87. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_dashboard.py +0 -0
  88. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_example_comments.py +0 -0
  89. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_example_connect.py +0 -0
  90. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_example_publish.py +0 -0
  91. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_example_schedule.py +0 -0
  92. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_example_webhooks.py +0 -0
  93. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_files.py +0 -0
  94. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_generate_models.py +0 -0
  95. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_generate_sync.py +0 -0
  96. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_integrations.py +0 -0
  97. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_models.py +0 -0
  98. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_openapi_freshness.py +0 -0
  99. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_organizations.py +0 -0
  100. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_packaging.py +0 -0
  101. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_pagination.py +0 -0
  102. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_products.py +0 -0
  103. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_publications.py +0 -0
  104. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_query_parity.py +0 -0
  105. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_readme.py +0 -0
  106. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_shapes_parity.py +0 -0
  107. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_types.py +0 -0
  108. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_uploads.py +0 -0
  109. {planvortex-0.17.0 → planvortex-0.18.0}/tests/test_webhooks.py +0 -0
@@ -4,6 +4,34 @@ All notable changes to this package are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
5
5
  [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [Unreleased]
8
+
9
+ ## [0.18.0] - 2026-11-10
10
+
11
+ ### Added
12
+
13
+ - **`pv.messages.download_file()` and `pv.comments.download_file()`.** The files that arrive from
14
+ the network (a photo, a voice note or a document in a private message; a photo, a GIF or a sticker
15
+ in a comment) are not stored by PlanVortex: `files_urls` says where each one is, and these two ask
16
+ PlanVortex to fetch it from the network right then. They return a `DownloadedFile` with the
17
+ `data` bytes, the real `content_type`, the `file_name` when there is one and the `disposition`.
18
+ Every WhatsApp file needs them (none has a `url`, photos and videos included), as do Telegram
19
+ files, LinkedIn images and Bluesky videos. Both exist in the async and the sync client.
20
+ - **`files_urls` on comments**: a comment that is only a photo is no longer an empty row. Facebook,
21
+ Threads, LinkedIn, X, Bluesky, Discord and Telegram give them, and on Google Business they are the
22
+ photos and videos of a review; on Instagram and YouTube the list is always empty.
23
+
24
+ ### Fixed
25
+
26
+ - **Errors 1515 and 1516 are `MessagingError`.** They are the files: 1515 is the network no longer
27
+ having one (on a comment too), 1516 a message with no file at that position.
28
+
29
+ - **Errors 1513 and 1514 are `MessagingError`.** They are the WhatsApp message templates: 1513 is a
30
+ template PlanVortex refuses before sending it to WhatsApp because WhatsApp would reject its format
31
+ (`data.field` and `data.reason` say which rule, such as `missing_examples`), and 1514 is WhatsApp
32
+ refusing it when it is created (`data.code`, `data.subcode` and `data.message` are WhatsApp’s). Both
33
+ were above the top of the messaging range and arrived as the base error.
34
+
7
35
  ## [0.17.0] - 2026-10-28
8
36
 
9
37
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: planvortex
3
- Version: 0.17.0
3
+ Version: 0.18.0
4
4
  Summary: Official Python client for the PlanVortex API
5
5
  Project-URL: Homepage, https://planvortex.com/en/developers
6
6
  Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
@@ -214,6 +214,21 @@ if (pv.comments.actions_for("linkedin") or {}).get("hide"):
214
214
  ...
215
215
  ```
216
216
 
217
+ A photo, a voice note or a document in a private message, and a photo or a sticker in a comment,
218
+ **are not stored by PlanVortex**: they stay on the network, and `files_urls` says where each one is.
219
+ When an entry has a `url`, load it directly. When it has none (every WhatsApp and Telegram file, a
220
+ LinkedIn image, a Bluesky video) or the `url` stopped loading, ask PlanVortex for it:
221
+
222
+ ```python
223
+ file = pv.messages.download_file(org_id, account_id, message["_id"], 0)
224
+ # or: pv.comments.download_file(org_id, comment["_id"], 0)
225
+ print(file.content_type, file.file_name, len(file.data))
226
+ ```
227
+
228
+ WhatsApp lets go of a file 7 days after it arrived; from then on the answer is error 1515. A
229
+ `disposition` of `"attachment"` is a document somebody outside the business sent: don't render it
230
+ inside your own pages.
231
+
217
232
  ## AI plans, and what they are generated from
218
233
 
219
234
  A plan is a **week** of drafts written by a model: you queue it, a job generates it, and what comes
@@ -285,7 +300,7 @@ memorising numbers:
285
300
  | 1100-1111 | `organization` | `OrganizationError` |
286
301
  | 1200-1207 | `role` | `PlanVortexError` |
287
302
  | 1300-1308, 1400-1408 | `plan_limit` | `PlanLimitError` |
288
- | 1500-1512 | `messaging` | `MessagingError` |
303
+ | 1500-1516 | `messaging` | `MessagingError` |
289
304
  | 1600-1601 | `contact` | `ContactError` |
290
305
  | 1900-1906 | `payment` | `PlanVortexError` |
291
306
  | 2000-2099 | `product` | `ProductError` |
@@ -184,6 +184,21 @@ if (pv.comments.actions_for("linkedin") or {}).get("hide"):
184
184
  ...
185
185
  ```
186
186
 
187
+ A photo, a voice note or a document in a private message, and a photo or a sticker in a comment,
188
+ **are not stored by PlanVortex**: they stay on the network, and `files_urls` says where each one is.
189
+ When an entry has a `url`, load it directly. When it has none (every WhatsApp and Telegram file, a
190
+ LinkedIn image, a Bluesky video) or the `url` stopped loading, ask PlanVortex for it:
191
+
192
+ ```python
193
+ file = pv.messages.download_file(org_id, account_id, message["_id"], 0)
194
+ # or: pv.comments.download_file(org_id, comment["_id"], 0)
195
+ print(file.content_type, file.file_name, len(file.data))
196
+ ```
197
+
198
+ WhatsApp lets go of a file 7 days after it arrived; from then on the answer is error 1515. A
199
+ `disposition` of `"attachment"` is a document somebody outside the business sent: don't render it
200
+ inside your own pages.
201
+
187
202
  ## AI plans, and what they are generated from
188
203
 
189
204
  A plan is a **week** of drafts written by a model: you queue it, a job generates it, and what comes
@@ -255,7 +270,7 @@ memorising numbers:
255
270
  | 1100-1111 | `organization` | `OrganizationError` |
256
271
  | 1200-1207 | `role` | `PlanVortexError` |
257
272
  | 1300-1308, 1400-1408 | `plan_limit` | `PlanLimitError` |
258
- | 1500-1512 | `messaging` | `MessagingError` |
273
+ | 1500-1516 | `messaging` | `MessagingError` |
259
274
  | 1600-1601 | `contact` | `ContactError` |
260
275
  | 1900-1906 | `payment` | `PlanVortexError` |
261
276
  | 2000-2099 | `product` | `ProductError` |
@@ -107,7 +107,7 @@
107
107
  "accounts"
108
108
  ],
109
109
  "summary": "Get the connection links of every connectable network",
110
- "description": "The authorization URL of each network, so the user can connect an account to this organization.\n\n**A network that cannot produce a link simply does not appear.** That is a legitimate answer, not a failure: it is what happens with `discord` in an organization that has not saved its own bot credentials yet (see `PUT /organizations/{id_organization}/social_credentials/{social_network}`).\n\n**An app cannot call this.** Connecting a social account is an OAuth flow with a person in front of it, so this endpoint only accepts a user token or a temporal connect token; with app credentials it answers error 519. The way an integration does it is to issue a temporal connect token with `GET /organizations/{id_organization}/temporal_connect_token` and hand it to its end user.\n\n**Read `authorization`, not `link`.** Almost every network is `redirect` and you send the person to `link`. Two are not, and neither of them fails visibly if you treat it as one:\n\n• **WhatsApp is not a URL at all.** Its sign-up is Meta's Embedded Signup, a popup you raise with the Facebook JavaScript SDK, so its `link` is an empty string and everything you need to open that popup travels in `authorization`. A client that loops over the list and redirects to `link` sends its user to its own page.\n• **Telegram has a link and still is not a redirect.** It opens a chat with the PlanVortex bot, and nobody comes back from it: the account is born minutes later, from the bot being added to a channel, and it is announced over the WebSocket. Open it in another tab and keep listening; redirect to it and there is nobody left to tell.\n\n**With a temporal token issued with `account_selection=integrator`** the list has a single entry: the session's network, with the session's `state` inside its link. Any other link would go back through the hosted flow, which that token cannot use (error 554). Once the person has come back from the network the session is no longer waiting for a link, and this answers 551.",
110
+ "description": "The authorization URL of each network, so the user can connect an account to this organization.\n\n**A network that cannot produce a link simply does not appear.** That is a legitimate answer, not a failure: it is what happens with `discord` in an organization that has not saved its own bot credentials yet (see `PUT /organizations/{id_organization}/social_credentials/{social_network}`).\n\n**On the free plan `whatsapp` does not appear either**, unless the organization already has an active WhatsApp account, which has to stay reconnectable. Its chat and its templates need a paid plan, so enabling a new account answers error 516. Asking for it by name gets you an empty list, not an error.\n\n**An app cannot call this.** Connecting a social account is an OAuth flow with a person in front of it, so this endpoint only accepts a user token or a temporal connect token; with app credentials it answers error 519. The way an integration does it is to issue a temporal connect token with `GET /organizations/{id_organization}/temporal_connect_token` and hand it to its end user.\n\n**Read `authorization`, not `link`.** Almost every network is `redirect` and you send the person to `link`. Two are not, and neither of them fails visibly if you treat it as one:\n\n• **WhatsApp is not a URL at all.** Its sign-up is Meta's Embedded Signup, a popup you raise with the Facebook JavaScript SDK, so its `link` is an empty string and everything you need to open that popup travels in `authorization`. A client that loops over the list and redirects to `link` sends its user to its own page.\n• **Telegram has a link and still is not a redirect.** It opens a chat with the PlanVortex bot, and nobody comes back from it: the account is born minutes later, from the bot being added to a channel, and it is announced over the WebSocket. Open it in another tab and keep listening; redirect to it and there is nobody left to tell.\n\n**With a temporal token issued with `account_selection=integrator`** the list has a single entry: the session's network, with the session's `state` inside its link. Any other link would go back through the hosted flow, which that token cannot use (error 554). Once the person has come back from the network the session is no longer waiting for a link, and this answers 551.",
111
111
  "operationId": "getConnectLinks",
112
112
  "x-planvortex-identity": [
113
113
  "current_user",
@@ -872,7 +872,7 @@
872
872
  "accounts"
873
873
  ],
874
874
  "summary": "Re-enable a disconnected account",
875
- "description": "Brings back an account that was removed, without going through the authorization again — as long as its stored token still works.\n\nIt takes a **slot of the plan**, so it fails with error 706 when the organization is already at its account limit. It also turns the network's webhooks back on, on any plan but the free one.\n\n**On `telegram` you normally never call this.** That network's accounts are born active — there is no authorization return in which to choose them, so PlanVortex takes the slot when the bot is added to the channel. The one case left is a channel that arrived while the plan was full: it stays off until a slot frees up, and this is what turns it on.\n\n**On `slack` this is also what puts the PlanVortex app inside the channel**, with `conversations.join`. It works on a **public** channel and it cannot work on a private one: Slack has no API for joining one. The account is enabled all the same and the connection looks healthy, and then the first publication fails with error 980 — so a private channel has to be told to the person **before** they pick it, together with the `/invite @PlanVortex` they have to run in that channel. Whether the app is inside travels in `extra_data.is_member`, and it can turn `false` later, the day somebody removes the app from an already connected channel.",
875
+ "description": "Brings back an account that was removed, without going through the authorization again — as long as its stored token still works.\n\nIt takes a **slot of the plan**, so it fails with error 706 when the organization is already at its account limit. It also turns the network's webhooks back on, on any plan but the free one. On the free plan a `whatsapp` account that is not active cannot be enabled (error 516), because its chat and its templates need a paid plan. One that is already active can still be reconnected.\n\n**On `telegram` you normally never call this.** That network's accounts are born active — there is no authorization return in which to choose them, so PlanVortex takes the slot when the bot is added to the channel. The one case left is a channel that arrived while the plan was full: it stays off until a slot frees up, and this is what turns it on.\n\n**On `slack` this is also what puts the PlanVortex app inside the channel**, with `conversations.join`. It works on a **public** channel and it cannot work on a private one: Slack has no API for joining one. The account is enabled all the same and the connection looks healthy, and then the first publication fails with error 980 — so a private channel has to be told to the person **before** they pick it, together with the `/invite @PlanVortex` they have to run in that channel. Whether the app is inside travels in `extra_data.is_member`, and it can turn `false` later, the day somebody removes the app from an already connected channel.",
876
876
  "operationId": "enableAccount",
877
877
  "x-planvortex-identity": [
878
878
  "current_user",
@@ -918,7 +918,7 @@
918
918
  }
919
919
  },
920
920
  "400": {
921
- "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `700` | The account has no usable token: it has to be connected again |\n| `706` | The organization has no account slots left in its plan |\n| `519` | This endpoint does not accept app credentials |\n| `544` | This temporal connect token was issued for a different social network |",
921
+ "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `700` | The account has no usable token: it has to be connected again |\n| `706` | The organization has no account slots left in its plan |\n| `516` | The plan is free and this network needs a paid plan (today, `whatsapp`) |\n| `519` | This endpoint does not accept app credentials |\n| `544` | This temporal connect token was issued for a different social network |",
922
922
  "content": {
923
923
  "application/json": {
924
924
  "schema": {
@@ -1321,7 +1321,7 @@
1321
1321
  }
1322
1322
  },
1323
1323
  "400": {
1324
- "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials |\n| `551` | Connect session not found, expired, or issued by another app |\n| `552` | The session is not waiting for a confirmation: the person has not come back yet, or it was already confirmed. `data.status` says which |\n| `553` | Some account is not part of this session. `data.accounts` lists them |\n| `706` | The new accounts do not fit in the plan. `data` carries `limit`, `used` and `requested`, and none was enabled |\n| `1101` | Invalid organization |",
1324
+ "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials |\n| `551` | Connect session not found, expired, or issued by another app |\n| `552` | The session is not waiting for a confirmation: the person has not come back yet, or it was already confirmed. `data.status` says which |\n| `553` | Some account is not part of this session. `data.accounts` lists them |\n| `706` | The new accounts do not fit in the plan. `data` carries `limit`, `used` and `requested`, and none was enabled |\n| `1101` | Invalid organization |\n| `516` | The plan is free and one of the accounts belongs to a network that needs a paid plan (today, `whatsapp`) |",
1325
1325
  "content": {
1326
1326
  "application/json": {
1327
1327
  "schema": {
@@ -5274,6 +5274,71 @@
5274
5274
  ]
5275
5275
  }
5276
5276
  },
5277
+ "/organizations/{id_organization}/comments/{id_comment}/files/{index}": {
5278
+ "get": {
5279
+ "tags": [
5280
+ "comments"
5281
+ ],
5282
+ "summary": "One file of a comment, fetched from the network",
5283
+ "description": "Files in a comment (a photo, a GIF, a sticker, a video) **are not stored by PlanVortex**: they stay on the network, and the comment's `files_urls` says where each one is. This endpoint asks the network for the file now and streams it back without keeping a copy. `index` is the file's position in `files_urls`.\n\nYou need it when a file has no `url`, or when its `url` stopped loading:\n\n• **LinkedIn** gives only the image's id, never a link.\n• **Telegram**'s download link carries the bot's token, so it never leaves PlanVortex. A bot can only download up to 20 MB: past that the answer is **1515** with `data.reason: \"too_big\"`, and the file is only visible in Telegram.\n• **Bluesky** videos are an HLS playlist that browsers other than Safari do not play; this returns the video file itself.\n• **Facebook, Threads and Discord** links expire; this reads the comment again and returns the file behind a fresh link.\n• **X** links do not expire, and reading a post again costs money, so X is not re-read: if its `url` no longer loads, the post was deleted and the answer is **1515**.\n\n**1515** means the network no longer has the file (`data.social_network`), and **2602** that the comment has no file at that position. A comment of another organization is **1102**.\n\nImages, videos and audio come back `inline`. Anything else comes back as an `attachment`: someone outside the business posted it, so don't render it inside your own pages.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
5284
+ "operationId": "getCommentFile",
5285
+ "x-planvortex-identity": [
5286
+ "current_user",
5287
+ "current_app"
5288
+ ],
5289
+ "parameters": [
5290
+ {
5291
+ "$ref": "#/components/parameters/CommentsidOrganization"
5292
+ },
5293
+ {
5294
+ "$ref": "#/components/parameters/CommentsidComment"
5295
+ },
5296
+ {
5297
+ "name": "index",
5298
+ "in": "path",
5299
+ "required": true,
5300
+ "description": "Position of the file in the comment's `files_urls`, from 0.",
5301
+ "schema": {
5302
+ "type": "integer",
5303
+ "minimum": 0
5304
+ }
5305
+ }
5306
+ ],
5307
+ "responses": {
5308
+ "200": {
5309
+ "description": "The file, with the network's `Content-Type`.",
5310
+ "content": {
5311
+ "*/*": {
5312
+ "schema": {
5313
+ "type": "string",
5314
+ "format": "binary"
5315
+ }
5316
+ }
5317
+ }
5318
+ },
5319
+ "400": {
5320
+ "$ref": "#/components/responses/CommentsCommentError"
5321
+ }
5322
+ },
5323
+ "x-codeSamples": [
5324
+ {
5325
+ "lang": "curl",
5326
+ "label": "curl",
5327
+ "source": "curl \"https://api.planvortex.com/v1.0.0/organizations/$ID_ORGANIZATION/comments/$ID_COMMENT/files/1\" \\\n -H \"Authorization: Bearer $PLANVORTEX_TOKEN\""
5328
+ },
5329
+ {
5330
+ "lang": "JavaScript",
5331
+ "label": "Node",
5332
+ "source": "import { PlanVortex } from \"planvortex\";\n\nconst pv = new PlanVortex({\n clientId: process.env.PLANVORTEX_CLIENT_ID,\n clientSecret: process.env.PLANVORTEX_CLIENT_SECRET,\n});\n\nconst result = await pv.comments.downloadFile(idOrganization, idComment, 1);"
5333
+ },
5334
+ {
5335
+ "lang": "Python",
5336
+ "label": "Python",
5337
+ "source": "from planvortex import PlanVortex\n\npv = PlanVortex()\n\nresult = pv.comments.download_file(id_organization, id_comment, 1)"
5338
+ }
5339
+ ]
5340
+ }
5341
+ },
5277
5342
  "/organizations/{id_organization}/comments/{id_comment}/replies": {
5278
5343
  "get": {
5279
5344
  "tags": [
@@ -7959,7 +8024,7 @@
7959
8024
  "message templates"
7960
8025
  ],
7961
8026
  "summary": "List the account's message templates",
7962
- "description": "The templates the **network** has approved for this account. They are read live from the network, not from our database, so a template approved a minute ago shows up here.\n\nThe shape of a template is the network's own: PlanVortex does not normalise it.\n\n**WhatsApp only.** No other network implements message templates: asking any of them returns HTTP 500 with `code: 500` (an unhandled server error), not the 1502 you would expect. Check `messages` in `GET /social_capabilities` and that the account is WhatsApp before calling.",
8027
+ "description": "The templates the **network** has approved for this account. They are read live from the network, not from our database, so a template approved a minute ago shows up here.\n\nThe shape of a template is the network's own: PlanVortex does not normalise it.\n\n**A rejected template says why.** WhatsApp templates carry `rejected_reason` (`INVALID_FORMAT`, `PROMOTIONAL`, `TAG_CONTENT_MISMATCH`...) next to their `status`, as WhatsApp sends it.\n\n**`health` says whether the account can start conversations at all.** A template is only needed outside the 24-hour window, which is exactly what a failed payment method or an unverified business blocks, and neither of them fails when you create or approve a template: the message is simply never delivered. `health` is WhatsApp's own status for the phone number, reduced to `can_send_message` (`AVAILABLE`, `LIMITED`, `BLOCKED`), the `issues` behind it with WhatsApp's code (141006 = payment method, 141010 = business not verified) and `notes`. When it can't be read the field is absent, which means unknown, not healthy.\n\n**WhatsApp only.** No other network implements message templates: asking any of them returns HTTP 500 with `code: 500` (an unhandled server error), not the 1502 you would expect. Check `messages` in `GET /social_capabilities` and that the account is WhatsApp before calling.",
7963
8028
  "operationId": "getMessageTemplates",
7964
8029
  "x-planvortex-identity": [
7965
8030
  "current_user",
@@ -7990,7 +8055,7 @@
7990
8055
  "properties": {
7991
8056
  "templates": {
7992
8057
  "type": "array",
7993
- "description": "Templates as the network returns them.",
8058
+ "description": "Templates as the network returns them. For WhatsApp: `id`, `name`, `status`, `category`, `language`, `components` and, when rejected, `rejected_reason`.",
7994
8059
  "items": {
7995
8060
  "type": "object",
7996
8061
  "additionalProperties": true
@@ -7998,6 +8063,59 @@
7998
8063
  },
7999
8064
  "total": {
8000
8065
  "type": "integer"
8066
+ },
8067
+ "health": {
8068
+ "type": "object",
8069
+ "description": "Whether the account can start conversations. WhatsApp only, and absent when it couldn't be read.",
8070
+ "properties": {
8071
+ "can_send_message": {
8072
+ "type": "string",
8073
+ "enum": [
8074
+ "AVAILABLE",
8075
+ "LIMITED",
8076
+ "BLOCKED"
8077
+ ]
8078
+ },
8079
+ "issues": {
8080
+ "type": "array",
8081
+ "description": "What blocks or limits it. Calling (SIP) errors are left out: they don't affect messaging.",
8082
+ "items": {
8083
+ "type": "object",
8084
+ "properties": {
8085
+ "code": {
8086
+ "type": "integer",
8087
+ "description": "WhatsApp's code: 141006 = payment method, 141010 = business not verified."
8088
+ },
8089
+ "entity_type": {
8090
+ "type": "string",
8091
+ "description": "Where the problem is: `PHONE_NUMBER`, `WABA`, `BUSINESS` or `APP`."
8092
+ },
8093
+ "description": {
8094
+ "type": "string"
8095
+ },
8096
+ "solution": {
8097
+ "type": "string"
8098
+ }
8099
+ },
8100
+ "required": [
8101
+ "code",
8102
+ "entity_type"
8103
+ ]
8104
+ }
8105
+ },
8106
+ "notes": {
8107
+ "type": "array",
8108
+ "items": {
8109
+ "type": "string"
8110
+ },
8111
+ "description": "Warnings that are not errors, such as a display name still pending approval."
8112
+ }
8113
+ },
8114
+ "required": [
8115
+ "can_send_message",
8116
+ "issues",
8117
+ "notes"
8118
+ ]
8001
8119
  }
8002
8120
  },
8003
8121
  "required": [
@@ -8035,7 +8153,7 @@
8035
8153
  "message templates"
8036
8154
  ],
8037
8155
  "summary": "Create a message template",
8038
- "description": "Sends a template to the network for approval. The body travels to the network as it is, so its fields are the network's (for WhatsApp: `name`, `language`, `category`, `components`).\n\n**Approval is not immediate.** The template comes back in a pending state and only becomes usable when the network approves it, which takes minutes or hours and can be refused.\n\n**WhatsApp only.** No other network implements message templates: asking any of them returns HTTP 500 with `code: 500` (an unhandled server error), not the 1502 you would expect. Check `messages` in `GET /social_capabilities` and that the account is WhatsApp before calling.",
8156
+ "description": "Sends a template to the network for approval. The body travels to the network as it is, so its fields are the network's (for WhatsApp: `name`, `language`, `category`, `components`).\n\n**Approval is not immediate.** The template comes back in a pending state and only becomes usable when the network approves it, which takes minutes or hours and can be refused.\n\n**WhatsApp templates are checked before they leave.** WhatsApp rejects a badly formatted template in the same second with `INVALID_FORMAT` and no explanation, so PlanVortex checks the rules it documents first and answers **1513** with `data.field` and `data.reason`: `invalid_name` (lowercase letters, numbers and underscores only), `missing_language`, `missing_body`, `body_too_long` (1,024 characters), `malformed_variable`, `variables_not_sequential`, `variable_at_edge` (the text can't start or end with a variable), `adjacent_variables` and `missing_examples`. **A body with variables needs one example per variable** in `example.body_text`, as in the example below.\n\nIf WhatsApp refuses the template when it is created (a language it doesn't have, a name already in use), the answer is **1514** with WhatsApp's own `code`, `subcode` and `message` in `data`.\n\n**WhatsApp only.** No other network implements message templates: asking any of them returns HTTP 500 with `code: 500` (an unhandled server error), not the 1502 you would expect. Check `messages` in `GET /social_capabilities` and that the account is WhatsApp before calling.",
8039
8157
  "operationId": "createMessageTemplate",
8040
8158
  "x-planvortex-identity": [
8041
8159
  "current_user",
@@ -8069,7 +8187,14 @@
8069
8187
  "components": [
8070
8188
  {
8071
8189
  "type": "BODY",
8072
- "text": "Hi {{1}}, your order is ready to pick up."
8190
+ "text": "Hi {{1}}, your order is ready to pick up.",
8191
+ "example": {
8192
+ "body_text": [
8193
+ [
8194
+ "Ana"
8195
+ ]
8196
+ ]
8197
+ }
8073
8198
  }
8074
8199
  ]
8075
8200
  }
@@ -8106,17 +8231,17 @@
8106
8231
  {
8107
8232
  "lang": "curl",
8108
8233
  "label": "curl",
8109
- "source": "curl -X POST \"https://api.planvortex.com/v1.0.0/organizations/$ID_ORGANIZATION/accounts/$ID_ACCOUNT/message_templates\" \\\n -H \"Authorization: Bearer $PLANVORTEX_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"order_ready\",\n \"language\": \"es\",\n \"category\": \"UTILITY\",\n \"components\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, your order is ready to pick up.\"\n }\n ]\n }'"
8234
+ "source": "curl -X POST \"https://api.planvortex.com/v1.0.0/organizations/$ID_ORGANIZATION/accounts/$ID_ACCOUNT/message_templates\" \\\n -H \"Authorization: Bearer $PLANVORTEX_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"order_ready\",\n \"language\": \"es\",\n \"category\": \"UTILITY\",\n \"components\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, your order is ready to pick up.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\"\n ]\n ]\n }\n }\n ]\n }'"
8110
8235
  },
8111
8236
  {
8112
8237
  "lang": "JavaScript",
8113
8238
  "label": "Node",
8114
- "source": "import { PlanVortex } from \"planvortex\";\n\nconst pv = new PlanVortex({\n clientId: process.env.PLANVORTEX_CLIENT_ID,\n clientSecret: process.env.PLANVORTEX_CLIENT_SECRET,\n});\n\nconst result = await pv.messages.createTemplate(idOrganization, idAccount, {\n name: \"order_ready\",\n language: \"es\",\n category: \"UTILITY\",\n components: [\n {\n type: \"BODY\",\n text: \"Hi {{1}}, your order is ready to pick up.\",\n },\n ],\n});"
8239
+ "source": "import { PlanVortex } from \"planvortex\";\n\nconst pv = new PlanVortex({\n clientId: process.env.PLANVORTEX_CLIENT_ID,\n clientSecret: process.env.PLANVORTEX_CLIENT_SECRET,\n});\n\nconst result = await pv.messages.createTemplate(idOrganization, idAccount, {\n name: \"order_ready\",\n language: \"es\",\n category: \"UTILITY\",\n components: [\n {\n type: \"BODY\",\n text: \"Hi {{1}}, your order is ready to pick up.\",\n example: {\n body_text: [\n [\n \"Ana\",\n ],\n ],\n },\n },\n ],\n});"
8115
8240
  },
8116
8241
  {
8117
8242
  "lang": "Python",
8118
8243
  "label": "Python",
8119
- "source": "from planvortex import PlanVortex\n\npv = PlanVortex()\n\nresult = pv.messages.create_template(\n id_organization,\n id_account,\n {\n \"name\": \"order_ready\",\n \"language\": \"es\",\n \"category\": \"UTILITY\",\n \"components\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, your order is ready to pick up.\",\n },\n ],\n },\n)"
8244
+ "source": "from planvortex import PlanVortex\n\npv = PlanVortex()\n\nresult = pv.messages.create_template(\n id_organization,\n id_account,\n {\n \"name\": \"order_ready\",\n \"language\": \"es\",\n \"category\": \"UTILITY\",\n \"components\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, your order is ready to pick up.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n ],\n ],\n },\n },\n ],\n },\n)"
8120
8245
  }
8121
8246
  ]
8122
8247
  },
@@ -8192,6 +8317,81 @@
8192
8317
  ]
8193
8318
  }
8194
8319
  },
8320
+ "/organizations/{id_organization}/accounts/{id_account}/messages/{id_message}/files/{index}": {
8321
+ "get": {
8322
+ "tags": [
8323
+ "messages"
8324
+ ],
8325
+ "summary": "One file of a message, fetched from the network",
8326
+ "description": "Files that arrive in a message (a photo, a video, a voice note, a document, a sticker) **are not stored by PlanVortex**: they stay on the network, and `message_options.files_urls` says where each one is.\n\n• **With `url`** (Instagram and Messenger): Meta's own CDN link. It works until Meta expires it.\n• **Without `url`** (every WhatsApp file): WhatsApp only hands a file over with the account's token, through a link that lasts five minutes, so there is no link to give you.\n\nEither way, this endpoint asks the network for the file now and streams it back without keeping a copy. `index` is the file's position in `files_urls`. `message_options.files` holds only the files **you** sent from PlanVortex, which are uploads.\n\n**The network decides how long a file lives.** WhatsApp lets go of a file 7 days after it arrived, and Meta drops one when the message or the story is deleted. After that the answer is **1515**, with `data.social_network`; on a number that also runs the WhatsApp Business app, the file is still there. **1516** means the message is not from this account, or has no file at that position.\n\nImages, videos and audio come back `inline`. Anything else (a PDF, a spreadsheet, an HTML file, an SVG) comes back as an `attachment`: someone outside the business sent it, so don't render it inside your own pages.",
8327
+ "operationId": "getMessageFile",
8328
+ "x-planvortex-identity": [
8329
+ "current_user",
8330
+ "current_app"
8331
+ ],
8332
+ "x-planvortex-plan": "paid",
8333
+ "parameters": [
8334
+ {
8335
+ "$ref": "#/components/parameters/MessagesidOrganization"
8336
+ },
8337
+ {
8338
+ "$ref": "#/components/parameters/MessagesidAccount"
8339
+ },
8340
+ {
8341
+ "name": "id_message",
8342
+ "in": "path",
8343
+ "required": true,
8344
+ "description": "The message's `_id`.",
8345
+ "schema": {
8346
+ "type": "string"
8347
+ }
8348
+ },
8349
+ {
8350
+ "name": "index",
8351
+ "in": "path",
8352
+ "required": true,
8353
+ "description": "Position of the file in `message_options.files_urls`, from 0.",
8354
+ "schema": {
8355
+ "type": "integer",
8356
+ "minimum": 0
8357
+ }
8358
+ }
8359
+ ],
8360
+ "responses": {
8361
+ "200": {
8362
+ "description": "The file, with the network's `Content-Type`.",
8363
+ "content": {
8364
+ "*/*": {
8365
+ "schema": {
8366
+ "type": "string",
8367
+ "format": "binary"
8368
+ }
8369
+ }
8370
+ }
8371
+ },
8372
+ "400": {
8373
+ "$ref": "#/components/responses/MessagesError"
8374
+ }
8375
+ },
8376
+ "x-codeSamples": [
8377
+ {
8378
+ "lang": "curl",
8379
+ "label": "curl",
8380
+ "source": "curl \"https://api.planvortex.com/v1.0.0/organizations/$ID_ORGANIZATION/accounts/$ID_ACCOUNT/messages/$ID_MESSAGE/files/1\" \\\n -H \"Authorization: Bearer $PLANVORTEX_TOKEN\""
8381
+ },
8382
+ {
8383
+ "lang": "JavaScript",
8384
+ "label": "Node",
8385
+ "source": "import { PlanVortex } from \"planvortex\";\n\nconst pv = new PlanVortex({\n clientId: process.env.PLANVORTEX_CLIENT_ID,\n clientSecret: process.env.PLANVORTEX_CLIENT_SECRET,\n});\n\nconst result = await pv.messages.downloadFile(idOrganization, idAccount, idMessage, 1);"
8386
+ },
8387
+ {
8388
+ "lang": "Python",
8389
+ "label": "Python",
8390
+ "source": "from planvortex import PlanVortex\n\npv = PlanVortex()\n\nresult = pv.messages.download_file(id_organization, id_account, id_message, 1)"
8391
+ }
8392
+ ]
8393
+ }
8394
+ },
8195
8395
  "/organizations/{id_organization}": {
8196
8396
  "get": {
8197
8397
  "tags": [
@@ -8944,7 +9144,7 @@
8944
9144
  "orgnaizations"
8945
9145
  ],
8946
9146
  "summary": "Issue a temporal connect token for an end user",
8947
- "description": "Returns a URL that lets **a person** connect a social account to this organization, without that person having a PlanVortex account and without your `client_secret` ever leaving your server.\n\nIt exists because **an app cannot connect accounts**: `connect_links` and `account-connect` refuse app credentials with error 519, since authorizing Instagram is an OAuth flow with a human in front of it. The shape of the integration is therefore:\n\n1. Your server asks for this token — **this endpoint is the one that requires app credentials**, and a user token is refused. So is a temporal connect token: it cannot renew itself, which is what keeps its life a real limit rather than the first link of a chain.\n2. You send your end user to the `url` that comes back, by redirect or in an iframe. The bare\n `token` comes back too, so a server-side client can authenticate with it directly instead of\n parsing it out of that URL.\n3. With that token the browser completes `connect_links` and `account-connect`.\n\nThe token lasts **fifteen minutes**, is tied to **this** organization — using it against another answers error 1101 — and carries only two permissions: create accounts and read the organization. It is the piece designed for a browser, and the only credential of ours that belongs there.\n\n**It connects once.** As soon as an `account-connect` succeeds, the token stops being able to connect anything else and answers error 543; the `enable` calls that finish that same connection keep working until it expires. Issue a new one per connection — they are free and immediate.\n\n**If you pass `social_network`, the token is bound to that network** and will not connect any other (error 544). Leave it out to let the person pick.\n\n**Or show the account picker yourself** with `account_selection=integrator`. By default PlanVortex shows the screen where the person picks which accounts to enable, and only then sends them to your `redirect_uri`. In this mode that screen is yours:\n\n1. The `url` that comes back is **the network's own authorization page**, so the person goes there straight from your app. Keep the `connect_session` id next to your user's session.\n2. When they finish, the network sends them through PlanVortex, which renders nothing, to `redirect_uri?connect_session=…&social_network=…`. Check that the id is the one you started.\n3. Read the accounts with `GET /organizations/{id_organization}/connect_sessions/{id_session}`, show your picker, and confirm with `POST /organizations/{id_organization}/connect_sessions/{id_session}/confirm`.\n\nThis mode needs `redirect_uri` and `social_network` (error 549): your app also picks the network. `telegram` cannot use it (error 550), because its link opens a chat that never comes back to the browser. On `whatsapp` the `url` is still a PlanVortex page with one button, because Meta's popup only opens on our domain; the picker after it is yours.\n\nPlanVortex's domain does show in the address bar on the way back: networks only return to the URLs registered in their own portals.\n\nIf you send `redirect_uri` it has to be one of the app's `redirect_urls`, or the call answers error 532.",
9147
+ "description": "Returns a URL that lets **a person** connect a social account to this organization, without that person having a PlanVortex account and without your `client_secret` ever leaving your server.\n\nIt exists because **an app cannot connect accounts**: `connect_links` and `account-connect` refuse app credentials with error 519, since authorizing Instagram is an OAuth flow with a human in front of it. The shape of the integration is therefore:\n\n1. Your server asks for this token — **this endpoint is the one that requires app credentials**, and a user token is refused. So is a temporal connect token: it cannot renew itself, which is what keeps its life a real limit rather than the first link of a chain.\n2. You send your end user to the `url` that comes back, by redirect or in an iframe. The bare\n `token` comes back too, so a server-side client can authenticate with it directly instead of\n parsing it out of that URL.\n3. With that token the browser completes `connect_links` and `account-connect`.\n\nThe token lasts **fifteen minutes**, is tied to **this** organization — using it against another answers error 1101 — and carries only two permissions: create accounts and read the organization. It is the piece designed for a browser, and the only credential of ours that belongs there.\n\n**It connects once.** As soon as an `account-connect` succeeds, the token stops being able to connect anything else and answers error 543; the `enable` calls that finish that same connection keep working until it expires. Issue a new one per connection — they are free and immediate.\n\n**If you pass `social_network`, the token is bound to that network** and will not connect any other (error 544). Leave it out to let the person pick. On the free plan, asking for `whatsapp` answers error 516 unless the organization already has an active WhatsApp account to reconnect: its chat and its templates need a paid plan.\n\n**Or show the account picker yourself** with `account_selection=integrator`. By default PlanVortex shows the screen where the person picks which accounts to enable, and only then sends them to your `redirect_uri`. In this mode that screen is yours:\n\n1. The `url` that comes back is **the network's own authorization page**, so the person goes there straight from your app. Keep the `connect_session` id next to your user's session.\n2. When they finish, the network sends them through PlanVortex, which renders nothing, to `redirect_uri?connect_session=…&social_network=…`. Check that the id is the one you started.\n3. Read the accounts with `GET /organizations/{id_organization}/connect_sessions/{id_session}`, show your picker, and confirm with `POST /organizations/{id_organization}/connect_sessions/{id_session}/confirm`.\n\nThis mode needs `redirect_uri` and `social_network` (error 549): your app also picks the network. `telegram` cannot use it (error 550), because its link opens a chat that never comes back to the browser. On `whatsapp` the `url` is still a PlanVortex page with one button, because Meta's popup only opens on our domain; the picker after it is yours.\n\nPlanVortex's domain does show in the address bar on the way back: networks only return to the URLs registered in their own portals.\n\nIf you send `redirect_uri` it has to be one of the app's `redirect_urls`, or the call answers error 532.",
8948
9148
  "operationId": "createTemporalConnectToken",
8949
9149
  "x-planvortex-identity": [
8950
9150
  "current_app"
@@ -9028,7 +9228,7 @@
9028
9228
  }
9029
9229
  },
9030
9230
  "400": {
9031
- "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials: neither a user token nor a temporal connect token can issue one |\n| `532` | `redirect_uri` is not one of the app's registered `redirect_urls` |\n| `549` | `account_selection` is not `planvortex` or `integrator`, or it is `integrator` without `redirect_uri` or `social_network`. `data` says which |\n| `550` | `account_selection=integrator` on a network with no return to the browser (`telegram`) |\n| `702` | `social_network` is not one of the networks PlanVortex supports |\n| `1101` | Invalid organization |",
9231
+ "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials: neither a user token nor a temporal connect token can issue one |\n| `516` | The plan is free, `social_network` needs a paid plan (today, `whatsapp`) and the organization has no active account of it to reconnect |\n| `532` | `redirect_uri` is not one of the app's registered `redirect_urls` |\n| `549` | `account_selection` is not `planvortex` or `integrator`, or it is `integrator` without `redirect_uri` or `social_network`. `data` says which |\n| `550` | `account_selection=integrator` on a network with no return to the browser (`telegram`) |\n| `702` | `social_network` is not one of the networks PlanVortex supports |\n| `1101` | Invalid organization |",
9032
9232
  "content": {
9033
9233
  "application/json": {
9034
9234
  "schema": {
@@ -15184,7 +15384,14 @@
15184
15384
  },
15185
15385
  "text": {
15186
15386
  "type": "string",
15187
- "description": "**May legitimately be empty.** A stars-only review carries no text at all, so render `rating` alongside it and never assume a blank comment is a loading failure."
15387
+ "description": "**May legitimately be empty.** A stars-only review carries no text at all, and a comment can be only a photo or a sticker (see `files_urls`), so render `rating` and the files alongside it and never assume a blank comment is a loading failure."
15388
+ },
15389
+ "files_urls": {
15390
+ "type": "array",
15391
+ "description": "The comment's files: a photo, a GIF, a sticker, a video. **PlanVortex does not store them** (see `SocialFileUrl`): open `url` when there is one, and when there is not, or it stops loading, fetch the file with `GET /organizations/{id_organization}/comments/{id_comment}/files/{index}`.\n\nFacebook, Threads, LinkedIn, X, Bluesky, Discord and Telegram give a comment's files, and on Google Business they are the photos and videos of a review. Instagram and YouTube do not expose them in their APIs, so there the list is always empty. A comment that is only a photo has an empty `text` and one file here.",
15392
+ "items": {
15393
+ "$ref": "#/components/schemas/SocialFileUrl"
15394
+ }
15188
15395
  },
15189
15396
  "rating": {
15190
15397
  "type": "integer",
@@ -16421,7 +16628,7 @@
16421
16628
  },
16422
16629
  "code": {
16423
16630
  "type": "integer",
16424
- "description": "PlanVortex error code. Ranges: 500-554 auth, tokens, client apps and connect sessions · 601-612 user · 700-716 social accounts · 800-810 files · 900-996 publications · 1000-1003 general · 1100-1111 organizations · 1200-1207 roles · 1300-1308 client plan · 1400-1408 organization plan · 1500-1512 messaging · 1600-1601 contacts · 1900-1906 payments · 2000-2099 products · 2100-2199 AI plans · 2200-2299 integrations · 2500-2599 publication fields, the ones that no longer fit in 900-996 (visibility, made for kids, TikTok's interactions and commercial content) · 2600-2699 comments, the ones that no longer fit in 945-948."
16631
+ "description": "PlanVortex error code. Ranges: 500-554 auth, tokens, client apps and connect sessions · 601-612 user · 700-716 social accounts · 800-810 files · 900-996 publications · 1000-1003 general · 1100-1111 organizations · 1200-1207 roles · 1300-1309 client plan · 1400-1408 organization plan · 1500-1516 messaging · 1600-1601 contacts · 1900-1906 payments · 2000-2099 products · 2100-2199 AI plans · 2200-2299 integrations · 2500-2599 publication fields, the ones that no longer fit in 900-996 (visibility, made for kids, TikTok's interactions and commercial content) · 2600-2699 comments, the ones that no longer fit in 945-948."
16425
16632
  },
16426
16633
  "data": {
16427
16634
  "additionalProperties": true,
@@ -17045,17 +17252,9 @@
17045
17252
  },
17046
17253
  "files_urls": {
17047
17254
  "type": "array",
17048
- "description": "Files already hosted somewhere else. Filled in by PlanVortex when a message arrives from the network.",
17255
+ "description": "Files that arrived with the message from the network. PlanVortex does not store them: they live on the network (see `SocialFileUrl`). On WhatsApp every file is here, photos and videos included, and none has a `url`.",
17049
17256
  "items": {
17050
- "type": "object",
17051
- "properties": {
17052
- "url": {
17053
- "type": "string"
17054
- },
17055
- "mime_type": {
17056
- "type": "string"
17057
- }
17058
- }
17257
+ "$ref": "#/components/schemas/SocialFileUrl"
17059
17258
  }
17060
17259
  },
17061
17260
  "template_name": {
@@ -18904,6 +19103,31 @@
18904
19103
  }
18905
19104
  }
18906
19105
  },
19106
+ "SocialFileUrl": {
19107
+ "type": "object",
19108
+ "description": "A file that arrived from the network: a photo, a video, a voice note, a document or a sticker in a private message or a comment. **PlanVortex does not store it**: it stays on the network, and this says where to find it.\n\n• **With `url`**: the network's own link, which your page can load directly. On Instagram, Messenger, Facebook, Threads and Discord it **expires**; on X and Bluesky it does not.\n• **Without `url`**: the network only hands the file over with a token that never leaves PlanVortex (WhatsApp, and Telegram, whose download link carries the bot's token), or gives only an identifier (LinkedIn, a Bluesky video). Fetch it through the API.\n\nEither way, when `url` is missing or stops loading, fetch the file with `GET .../messages/{id_message}/files/{index}` or `GET .../comments/{id_comment}/files/{index}`, where `index` is its position in the list. PlanVortex asks the network for it at that moment and streams it back without keeping a copy.",
19109
+ "properties": {
19110
+ "url": {
19111
+ "type": "string",
19112
+ "description": "The network's direct link, when there is one a browser can open. It may expire. Never present on WhatsApp, Telegram, LinkedIn or a Bluesky video."
19113
+ },
19114
+ "mime_type": {
19115
+ "type": "string",
19116
+ "description": "Always present, so you can decide how to show it. When the network does not say, it is the most likely type: the file fetched through the API comes with its real `Content-Type`."
19117
+ },
19118
+ "name": {
19119
+ "type": "string",
19120
+ "description": "The document's file name, when the network gives one."
19121
+ },
19122
+ "external_id": {
19123
+ "type": "string",
19124
+ "description": "The file's id on the network (WhatsApp's media id, Telegram's `file_id`, a Bluesky CID, a LinkedIn image URN). Treat it as opaque."
19125
+ }
19126
+ },
19127
+ "required": [
19128
+ "mime_type"
19129
+ ]
19130
+ },
18907
19131
  "SocialIdentifier": {
18908
19132
  "type": "object",
18909
19133
  "description": "The same person, on one channel.",
@@ -9,7 +9,7 @@ name = "planvortex"
9
9
  # entonces `project.version` desapareceria del pyproject y el paso del workflow de release que
10
10
  # compara el tag con la version —que lo lee con `tomllib`— dejaria de encontrarla. Se quedan las dos
11
11
  # y las ata `tests/test_packaging.py`, que falla si se separan.
12
- version = "0.17.0"
12
+ version = "0.18.0"
13
13
  description = "Official Python client for the PlanVortex API"
14
14
  readme = "README.md"
15
15
  requires-python = ">=3.10"
@@ -60,6 +60,8 @@ VERBOS: dict[str, str] = {
60
60
  "_put_one": "PUT",
61
61
  "_delete": "DELETE",
62
62
  "_delete_one": "DELETE",
63
+ # Un archivo que llega de la red (mensajes y comentarios): un GET que devuelve bytes, no JSON
64
+ "_download_file": "GET",
63
65
  }
64
66
 
65
67
  # El comodin con el que se reemplaza cualquier trozo interpolado de una ruta. Es tambien lo que se
@@ -100,6 +100,7 @@ from planvortex._core.errors import (
100
100
  from planvortex._core.pagination import DEFAULT_PAGE_SIZE, MAX_PAGES, Page
101
101
  from planvortex._core.transport import (
102
102
  DEFAULT_TIMEOUT_SECONDS,
103
+ DownloadedFile,
103
104
  HttpHooks,
104
105
  HttpRequest,
105
106
  HttpResponse,
@@ -146,6 +147,7 @@ __all__ = [
146
147
  "AsyncPlanVortex",
147
148
  "AuthError",
148
149
  "ContactError",
150
+ "DownloadedFile",
149
151
  "ErrorRange",
150
152
  "FileError",
151
153
  "HttpHooks",
@@ -50,7 +50,11 @@ PLANVORTEX_ERROR_RANGES: tuple[ErrorRange, ...] = (
50
50
  # 1308 es el tope de APPS del plan, que nacio al quitar el candado de precio de la API.
51
51
  ErrorRange(1300, 1308, "plan_limit"),
52
52
  ErrorRange(1400, 1408, "plan_limit"),
53
- ErrorRange(1500, 1512, "messaging"),
53
+ # 1513 y 1514 son las plantillas de WhatsApp: el formato que Meta rechazaria sin decir por que,
54
+ # y Meta rechazandola al crearla. Nacieron por encima del techo, la cuarta vez que pasa. 1515 y
55
+ # 1516 son los archivos que llegan de la red: 1515 = la red ya no lo tiene (tambien en un
56
+ # comentario), 1516 = ese mensaje o esa posicion no existen.
57
+ ErrorRange(1500, 1516, "messaging"),
54
58
  ErrorRange(1600, 1601, "contact"),
55
59
  ErrorRange(1900, 1906, "payment"),
56
60
  ErrorRange(2000, 2099, "product"),
@@ -170,7 +174,7 @@ class PlanLimitError(PlanVortexError):
170
174
 
171
175
 
172
176
  class MessagingError(PlanVortexError):
173
- """1500-1512 — conversations, messages and templates. Requires a paid plan."""
177
+ """1500-1516 — conversations, messages, templates and their files. Requires a paid plan."""
174
178
 
175
179
 
176
180
  class ContactError(PlanVortexError):
@@ -179,7 +179,10 @@ class AsyncHttpClient:
179
179
 
180
180
  if response.is_success:
181
181
  vacia = request.parse == "none" or response.status_code == 204
182
- datos = None if vacia else _parse_body(response)
182
+ if request.parse == "binary":
183
+ datos: Any = response.content
184
+ else:
185
+ datos = None if vacia else _parse_body(response)
183
186
  return HttpResponse(datos, response.status_code, response.headers, request_id)
184
187
 
185
188
  retry_after = parse_retry_after(response.headers.get("retry-after"))