sendly 4.4.0__tar.gz → 4.5.1__tar.gz

{sendly-4.4.0 → sendly-4.5.1}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # sendly (Python)
 
+## 4.5.0
+
+### Minor Changes
+
+- `WhatsAppMessage.fell_back` is `True` when the message went as an SMS instead (`fallback.status` is `"sent"`), matching Ruby's `fell_back?` and the other SDKs.
+
+### Patch Changes
+
+- The async `messages.send` docstring said `fallback_to_sms` is RCS only; it documents the WhatsApp fallback too, like the sync one.
+- Docs give 503, the status the API sends, instead of 502 for the WhatsApp and voice errors raised when WhatsApp or the carrier couldn't be reached: `whatsapp_send_failed` when the message never reached WhatsApp (not sent, and safe to send again with the same idempotency key), the WhatsApp signup, profile, conversational-components and calling errors, `voice_attach_failed` and `carrier_refused`. The API answers every 502 as a 503 with a `Sendly-Upstream-Status: 502` header. Nothing changes at runtime.
+
 ## 4.4.0
 
 ### Minor Changes

{sendly-4.4.0 → sendly-4.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendly
-Version: 4.4.0
+Version: 4.5.1
 Summary: Official Sendly Python SDK for SMS messaging
 Project-URL: Homepage, https://sendly.live
 Project-URL: Documentation, https://sendly.live/docs
@@ -1355,7 +1355,7 @@ client.links.update(link.code, True)
 
 ## WhatsApp
 
-Connect a number you own to WhatsApp ($19 one-time, no monthly fee), create
+Connect a number you own to WhatsApp ($9.99 one-time, no monthly fee), create
 Meta-reviewed message templates, and send on the `whatsapp` channel. Connecting
 the first number always ends with a human step: hand the `connect_url` to your
 user - they open it in a browser and log in with Facebook to link their
@@ -1388,9 +1388,10 @@ print(f'Open {signup.connect_url} and log in with Facebook')
 # number. Activation usually takes a few minutes but can take hours. If it
 # hasn't finished about 6 hours after the session began, the session fails
 # with registration_timeout and the fee is refunded ('failed', with
-# signup.failure_reasons explaining why). If the connection fails, the $19 fee
-# is refunded automatically; once a number has connected, a later disconnect
-# gets nothing back.
+# signup.failure_reasons explaining why). The one-time $9.99 connection fee is
+# charged to your card when you start connecting the number and refunded
+# automatically if the connection fails; it is not refundable once the number
+# is connected.
 
 # 2. Create a template (Meta reviews it, usually 24-48h). category is required
 # (UTILITY, AUTHENTICATION or MARKETING) with no default, and an update can't
@@ -1474,7 +1475,7 @@ components = client.whatsapp.senders.get_conversational_components('+15555550123
 client.whatsapp.senders.set_calling('+15555550123', enabled=True)
 
 # Add another number to an account you already connected: no Facebook step.
-# Same $19 fee, refunded if it fails. WhatsApp sends the number a 6-digit code
+# Same $9.99 fee, refunded if it fails. WhatsApp sends the number a 6-digit code
 senders = client.whatsapp.senders.list().senders
 account_id = next(
     s.business_account_id for s in senders if s.status == 'active' and s.business_account_id
@@ -1505,7 +1506,7 @@ codes it fails with `verification_failed` and the fee is refunded. Calls carry
 submitted, it is the newest code that has arrived since the signup started, so
 after a resend it still shows the earlier code until the new one arrives. Once
 WhatsApp has checked a code, only a code that arrived after the last
-submission or resend is returned. A submission answered with 502
+submission or resend is returned. A submission answered with 503
 `whatsapp_verification_unavailable` is not counted, so the same unchecked code
 can come back, and submitting it again is safe.
 
@@ -1535,10 +1536,10 @@ Errors specific to WhatsApp:
   24 hours. It is final and not retried; try again the next day.
 - `whatsapp_send_failed` on a send: HTTP 422 when WhatsApp refused the message,
   which is final (cached under the idempotency key and replayed for 24 hours),
-  or HTTP 502 when the message provably never reached the carrier, so it was
-  not sent and is safe to send again. A 502 is never cached, and the SDK
-  retries it under the same idempotency key. Either way the message was not
-  charged.
+  or HTTP 503 when the message provably never reached WhatsApp, so it was not
+  sent and is safe to resend under the same idempotency key. A 503 is never
+  cached, and the SDK retries it automatically, up to 3 times under the same
+  key, before raising. Either way the message was not charged.
 - `whatsapp_send_unconfirmed` (HTTP 409) on a send: the outcome is unknown.
   The message was marked failed and refunded but may still be delivered, so
   check before sending it again (it could arrive twice). It is not retried
@@ -1556,18 +1557,18 @@ Errors specific to WhatsApp:
   marketing template without an opt-out button only gets a warning.
 - Profile photo: `file_required` and `whatsapp_profile_photo_invalid` (HTTP
   400), `whatsapp_profile_photo_too_large` (HTTP 413),
-  `whatsapp_profile_update_failed` (HTTP 502). Conversational components:
+  `whatsapp_profile_update_failed` (HTTP 503). Conversational components:
   `invalid_request` (HTTP 400) with the reason,
   `whatsapp_conversational_components_fetch_failed` and
-  `whatsapp_conversational_components_update_failed` (HTTP 502). Calling:
+  `whatsapp_conversational_components_update_failed` (HTTP 503). Calling:
   `voice_not_enabled` (HTTP 409), `whatsapp_calling_unavailable` (HTTP 422;
   WhatsApp only allows calling once the account may message 2,000 people a
   day and the display name is approved), `whatsapp_calling_update_failed`
-  (HTTP 502).
+  (HTTP 503).
 - Adding a number by code: `whatsapp_business_account_not_found` (HTTP 404),
   `display_name_required` (HTTP 400), `whatsapp_signup_in_progress` and
   `whatsapp_already_enabled` (HTTP 409), and
-  `whatsapp_verification_start_failed` (HTTP 422 refused, 502 unreachable; the
+  `whatsapp_verification_start_failed` (HTTP 422 refused, 503 unreachable; the
   fee is refunded either way). A Facebook `signup.create()` for a number being
   added by code gets `whatsapp_verification_in_progress` (HTTP 409).
   `verify()`: `invalid_verification_code` (HTTP 400, not 6 digits),
@@ -1575,9 +1576,9 @@ Errors specific to WhatsApp:
   `e.response.attempts_remaining`), `whatsapp_verification_failed` (HTTP 409,
   too many wrong codes), `whatsapp_verification_busy` (HTTP 409, retry),
   `whatsapp_verification_unavailable` and `whatsapp_activation_pending` (HTTP
-  502). `resend()`: `whatsapp_verification_resend_too_soon` (HTTP 429, wait
+  503). `resend()`: `whatsapp_verification_resend_too_soon` (HTTP 429, wait
   `e.response.retry_after` seconds) and `whatsapp_verification_resend_failed`
-  (HTTP 422 or 502). Both raise `signup_not_active` (HTTP 409) once the signup
+  (HTTP 422 or 503). Both raise `signup_not_active` (HTTP 409) once the signup
   stops waiting for a code, and `signup_not_found` (HTTP 404). The SDK never
   retries a `5xx`, a timeout or a network error from `signup.create()` with a
   `business_account_id` or from `verify()`; it retries `resend()` like any
@@ -1585,6 +1586,78 @@ Errors specific to WhatsApp:
 
 `message.whatsapp.message_id` is `None` until the first delivery report lands.
 
+### SMS fallback
+
+Pass `fallback_to_sms=True` and a WhatsApp message that can't be delivered
+goes as an SMS from the same number instead.
+
+```python
+from sendly import Sendly, SendlyError, WhatsAppSmsFallback
+
+client = Sendly('sk_live_v1_YOUR_API_KEY')
+
+try:
+    message = client.messages.send(
+        channel='whatsapp',
+        to='+15555550100',
+        from_='+15555550123',
+        text='Your table is ready!',
+        fallback_to_sms=True,
+    )
+    print(message.fallback.status)  # 'pending', 'sent', 'failed', 'unavailable' or 'skipped'
+    print(message.fallback.reason)  # 'window_closed', 'whatsapp_refused' or 'whatsapp_failed'
+    if message.fell_back and message.fallback.message_id:
+        # The SMS went instead (message.status is 'failed')
+        sms = client.messages.get(message.fallback.message_id)
+        print(sms.fallback_of)  # the WhatsApp message's id
+except SendlyError as e:
+    extra = (e.response.model_extra or {}) if e.response else {}
+    if e.code == 'sms_fallback_unavailable':
+        pass  # 403: this number can't send SMS to the recipient; nothing was sent
+    elif e.code == 'sms_fallback_not_supported':
+        print(extra.get('reason'))  # marketing_template, authentication_template or media_without_caption
+    elif extra.get('fallback'):
+        # 422 whatsapp_window_closed or whatsapp_send_failed: the SMS couldn't go
+        # either. A closed window also carries the WhatsApp message's id.
+        fallback = WhatsAppSmsFallback.model_validate(extra['fallback'])
+        print(e.code, extra.get('id'), fallback.status, fallback.error)
+    else:
+        raise
+```
+
+- It falls back when the 24-hour window is closed (the SMS goes at once:
+  free-form text and media go only within 24 hours of the customer's last
+  message, templates any time), when WhatsApp refuses the message, or when
+  WhatsApp reports it undeliverable later. Never after WhatsApp reports it
+  delivered or read, and at most once per message.
+- The number must already be able to send SMS to the recipient (a verified
+  toll-free number, or a local number on a 10DLC campaign, to a US or Canada
+  number), or the send is refused with HTTP 403 `sms_fallback_unavailable`
+  before anything is sent.
+- Marketing and authentication templates, and media without a caption, can't
+  fall back: HTTP 422 `sms_fallback_not_supported`. A utility template falls
+  back as its text header, body and footer with the variables filled in, and
+  its URL and phone buttons as `label: target`; quick replies are dropped and
+  listed in `fallback.content_dropped`.
+- Billing: the WhatsApp charge is refunded (a closed window is never charged)
+  and the SMS is billed as an SMS. A message that fell back at once comes
+  back with `status == 'failed'`, `credits_used == 0` and
+  `fallback.status == 'sent'` (`message.fell_back` is `True`);
+  `fallback.credits_used` is what the SMS cost.
+- No SMS goes on an HTTP 409 `whatsapp_send_unconfirmed` or an HTTP 503
+  `whatsapp_send_failed`. `fallback.status` is `'unavailable'` when SMS rules
+  stop it (the contact opted out, a promotional-looking text in the
+  recipient's quiet hours, restricted content), with the reason in
+  `fallback.error`, and `'skipped'` for a WhatsApp error an SMS can't fix.
+- There is no time-based fallback: a message WhatsApp accepted but hasn't
+  delivered, for example to a phone that is off, stays `'pending'`, and no
+  SMS goes unless WhatsApp later reports a failure.
+- `messages.get()` and `messages.list()` return the same `fallback` on the
+  WhatsApp message, so check a pending one later. The SMS carries
+  `fallback_of`, the WhatsApp message's id.
+
+Guide: [Send WhatsApp with an SMS Fallback](https://sendly.live/docs/whatsapp/send-with-fallback).
+
 ## RCS
 
 Send branded, verified-sender messages on Android: rich cards, suggestion
@@ -1946,8 +2019,8 @@ default, or `CA`) are optional.
 
 Refusals: `agent_required` (agent mode with no agent), `agent_not_found`,
 `agent_disabled` (turn the agent on first), `agent_limit`, `agent_in_use`,
-`number_not_found`, `invalid_voice_mode`, `voice_attach_failed` (HTTP 502,
-retry shortly), `carrier_refused` (HTTP 502, retry shortly unless the message
+`number_not_found`, `invalid_voice_mode`, `voice_attach_failed` (HTTP 503,
+retry shortly), `carrier_refused` (HTTP 503, retry shortly unless the message
 says the number couldn't be found for emergency registration: contact
 support), `voice_unavailable` (HTTP 503),
 `e911_not_applicable` (only US and Canadian numbers take an emergency

{sendly-4.4.0 → sendly-4.5.1}/README.md

@@ -1320,7 +1320,7 @@ client.links.update(link.code, True)
 
 ## WhatsApp
 
-Connect a number you own to WhatsApp ($19 one-time, no monthly fee), create
+Connect a number you own to WhatsApp ($9.99 one-time, no monthly fee), create
 Meta-reviewed message templates, and send on the `whatsapp` channel. Connecting
 the first number always ends with a human step: hand the `connect_url` to your
 user - they open it in a browser and log in with Facebook to link their
@@ -1353,9 +1353,10 @@ print(f'Open {signup.connect_url} and log in with Facebook')
 # number. Activation usually takes a few minutes but can take hours. If it
 # hasn't finished about 6 hours after the session began, the session fails
 # with registration_timeout and the fee is refunded ('failed', with
-# signup.failure_reasons explaining why). If the connection fails, the $19 fee
-# is refunded automatically; once a number has connected, a later disconnect
-# gets nothing back.
+# signup.failure_reasons explaining why). The one-time $9.99 connection fee is
+# charged to your card when you start connecting the number and refunded
+# automatically if the connection fails; it is not refundable once the number
+# is connected.
 
 # 2. Create a template (Meta reviews it, usually 24-48h). category is required
 # (UTILITY, AUTHENTICATION or MARKETING) with no default, and an update can't
@@ -1439,7 +1440,7 @@ components = client.whatsapp.senders.get_conversational_components('+15555550123
 client.whatsapp.senders.set_calling('+15555550123', enabled=True)
 
 # Add another number to an account you already connected: no Facebook step.
-# Same $19 fee, refunded if it fails. WhatsApp sends the number a 6-digit code
+# Same $9.99 fee, refunded if it fails. WhatsApp sends the number a 6-digit code
 senders = client.whatsapp.senders.list().senders
 account_id = next(
     s.business_account_id for s in senders if s.status == 'active' and s.business_account_id
@@ -1470,7 +1471,7 @@ codes it fails with `verification_failed` and the fee is refunded. Calls carry
 submitted, it is the newest code that has arrived since the signup started, so
 after a resend it still shows the earlier code until the new one arrives. Once
 WhatsApp has checked a code, only a code that arrived after the last
-submission or resend is returned. A submission answered with 502
+submission or resend is returned. A submission answered with 503
 `whatsapp_verification_unavailable` is not counted, so the same unchecked code
 can come back, and submitting it again is safe.
 
@@ -1500,10 +1501,10 @@ Errors specific to WhatsApp:
   24 hours. It is final and not retried; try again the next day.
 - `whatsapp_send_failed` on a send: HTTP 422 when WhatsApp refused the message,
   which is final (cached under the idempotency key and replayed for 24 hours),
-  or HTTP 502 when the message provably never reached the carrier, so it was
-  not sent and is safe to send again. A 502 is never cached, and the SDK
-  retries it under the same idempotency key. Either way the message was not
-  charged.
+  or HTTP 503 when the message provably never reached WhatsApp, so it was not
+  sent and is safe to resend under the same idempotency key. A 503 is never
+  cached, and the SDK retries it automatically, up to 3 times under the same
+  key, before raising. Either way the message was not charged.
 - `whatsapp_send_unconfirmed` (HTTP 409) on a send: the outcome is unknown.
   The message was marked failed and refunded but may still be delivered, so
   check before sending it again (it could arrive twice). It is not retried
@@ -1521,18 +1522,18 @@ Errors specific to WhatsApp:
   marketing template without an opt-out button only gets a warning.
 - Profile photo: `file_required` and `whatsapp_profile_photo_invalid` (HTTP
   400), `whatsapp_profile_photo_too_large` (HTTP 413),
-  `whatsapp_profile_update_failed` (HTTP 502). Conversational components:
+  `whatsapp_profile_update_failed` (HTTP 503). Conversational components:
   `invalid_request` (HTTP 400) with the reason,
   `whatsapp_conversational_components_fetch_failed` and
-  `whatsapp_conversational_components_update_failed` (HTTP 502). Calling:
+  `whatsapp_conversational_components_update_failed` (HTTP 503). Calling:
   `voice_not_enabled` (HTTP 409), `whatsapp_calling_unavailable` (HTTP 422;
   WhatsApp only allows calling once the account may message 2,000 people a
   day and the display name is approved), `whatsapp_calling_update_failed`
-  (HTTP 502).
+  (HTTP 503).
 - Adding a number by code: `whatsapp_business_account_not_found` (HTTP 404),
   `display_name_required` (HTTP 400), `whatsapp_signup_in_progress` and
   `whatsapp_already_enabled` (HTTP 409), and
-  `whatsapp_verification_start_failed` (HTTP 422 refused, 502 unreachable; the
+  `whatsapp_verification_start_failed` (HTTP 422 refused, 503 unreachable; the
   fee is refunded either way). A Facebook `signup.create()` for a number being
   added by code gets `whatsapp_verification_in_progress` (HTTP 409).
   `verify()`: `invalid_verification_code` (HTTP 400, not 6 digits),
@@ -1540,9 +1541,9 @@ Errors specific to WhatsApp:
   `e.response.attempts_remaining`), `whatsapp_verification_failed` (HTTP 409,
   too many wrong codes), `whatsapp_verification_busy` (HTTP 409, retry),
   `whatsapp_verification_unavailable` and `whatsapp_activation_pending` (HTTP
-  502). `resend()`: `whatsapp_verification_resend_too_soon` (HTTP 429, wait
+  503). `resend()`: `whatsapp_verification_resend_too_soon` (HTTP 429, wait
   `e.response.retry_after` seconds) and `whatsapp_verification_resend_failed`
-  (HTTP 422 or 502). Both raise `signup_not_active` (HTTP 409) once the signup
+  (HTTP 422 or 503). Both raise `signup_not_active` (HTTP 409) once the signup
   stops waiting for a code, and `signup_not_found` (HTTP 404). The SDK never
   retries a `5xx`, a timeout or a network error from `signup.create()` with a
   `business_account_id` or from `verify()`; it retries `resend()` like any
@@ -1550,6 +1551,78 @@ Errors specific to WhatsApp:
 
 `message.whatsapp.message_id` is `None` until the first delivery report lands.
 
+### SMS fallback
+
+Pass `fallback_to_sms=True` and a WhatsApp message that can't be delivered
+goes as an SMS from the same number instead.
+
+```python
+from sendly import Sendly, SendlyError, WhatsAppSmsFallback
+
+client = Sendly('sk_live_v1_YOUR_API_KEY')
+
+try:
+    message = client.messages.send(
+        channel='whatsapp',
+        to='+15555550100',
+        from_='+15555550123',
+        text='Your table is ready!',
+        fallback_to_sms=True,
+    )
+    print(message.fallback.status)  # 'pending', 'sent', 'failed', 'unavailable' or 'skipped'
+    print(message.fallback.reason)  # 'window_closed', 'whatsapp_refused' or 'whatsapp_failed'
+    if message.fell_back and message.fallback.message_id:
+        # The SMS went instead (message.status is 'failed')
+        sms = client.messages.get(message.fallback.message_id)
+        print(sms.fallback_of)  # the WhatsApp message's id
+except SendlyError as e:
+    extra = (e.response.model_extra or {}) if e.response else {}
+    if e.code == 'sms_fallback_unavailable':
+        pass  # 403: this number can't send SMS to the recipient; nothing was sent
+    elif e.code == 'sms_fallback_not_supported':
+        print(extra.get('reason'))  # marketing_template, authentication_template or media_without_caption
+    elif extra.get('fallback'):
+        # 422 whatsapp_window_closed or whatsapp_send_failed: the SMS couldn't go
+        # either. A closed window also carries the WhatsApp message's id.
+        fallback = WhatsAppSmsFallback.model_validate(extra['fallback'])
+        print(e.code, extra.get('id'), fallback.status, fallback.error)
+    else:
+        raise
+```
+
+- It falls back when the 24-hour window is closed (the SMS goes at once:
+  free-form text and media go only within 24 hours of the customer's last
+  message, templates any time), when WhatsApp refuses the message, or when
+  WhatsApp reports it undeliverable later. Never after WhatsApp reports it
+  delivered or read, and at most once per message.
+- The number must already be able to send SMS to the recipient (a verified
+  toll-free number, or a local number on a 10DLC campaign, to a US or Canada
+  number), or the send is refused with HTTP 403 `sms_fallback_unavailable`
+  before anything is sent.
+- Marketing and authentication templates, and media without a caption, can't
+  fall back: HTTP 422 `sms_fallback_not_supported`. A utility template falls
+  back as its text header, body and footer with the variables filled in, and
+  its URL and phone buttons as `label: target`; quick replies are dropped and
+  listed in `fallback.content_dropped`.
+- Billing: the WhatsApp charge is refunded (a closed window is never charged)
+  and the SMS is billed as an SMS. A message that fell back at once comes
+  back with `status == 'failed'`, `credits_used == 0` and
+  `fallback.status == 'sent'` (`message.fell_back` is `True`);
+  `fallback.credits_used` is what the SMS cost.
+- No SMS goes on an HTTP 409 `whatsapp_send_unconfirmed` or an HTTP 503
+  `whatsapp_send_failed`. `fallback.status` is `'unavailable'` when SMS rules
+  stop it (the contact opted out, a promotional-looking text in the
+  recipient's quiet hours, restricted content), with the reason in
+  `fallback.error`, and `'skipped'` for a WhatsApp error an SMS can't fix.
+- There is no time-based fallback: a message WhatsApp accepted but hasn't
+  delivered, for example to a phone that is off, stays `'pending'`, and no
+  SMS goes unless WhatsApp later reports a failure.
+- `messages.get()` and `messages.list()` return the same `fallback` on the
+  WhatsApp message, so check a pending one later. The SMS carries
+  `fallback_of`, the WhatsApp message's id.
+
+Guide: [Send WhatsApp with an SMS Fallback](https://sendly.live/docs/whatsapp/send-with-fallback).
+
 ## RCS
 
 Send branded, verified-sender messages on Android: rich cards, suggestion
@@ -1911,8 +1984,8 @@ default, or `CA`) are optional.
 
 Refusals: `agent_required` (agent mode with no agent), `agent_not_found`,
 `agent_disabled` (turn the agent on first), `agent_limit`, `agent_in_use`,
-`number_not_found`, `invalid_voice_mode`, `voice_attach_failed` (HTTP 502,
-retry shortly), `carrier_refused` (HTTP 502, retry shortly unless the message
+`number_not_found`, `invalid_voice_mode`, `voice_attach_failed` (HTTP 503,
+retry shortly), `carrier_refused` (HTTP 503, retry shortly unless the message
 says the number couldn't be found for emergency registration: contact
 support), `voice_unavailable` (HTTP 503),
 `e911_not_applicable` (only US and Canadian numbers take an emergency

{sendly-4.4.0 → sendly-4.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sendly"
-version = "4.4.0"
+version = "4.5.1"
 description = "Official Sendly Python SDK for SMS messaging"
 readme = "README.md"
 license = "MIT"

{sendly-4.4.0 → sendly-4.5.1}/sendly/__init__.py

@@ -29,7 +29,7 @@ Async Example:
     >>> asyncio.run(main())
 """
 
-__version__ = "4.4.0"
+__version__ = "4.5.1"
 
 # Main clients
 from .client import AsyncSendly, Sendly

{sendly-4.4.0 → sendly-4.5.1}/sendly/resources/messages.py

@@ -152,8 +152,8 @@ class MessagesResource:
             SendlyError: ``whatsapp_send_failed`` on WhatsApp: 422 when
                 WhatsApp refused the message, which is final and not retried
                 (cached under the idempotency key and replayed for 24 hours);
-                502 when the message provably never reached the carrier, so it
-                was not sent and is safe to send again. A 502 is never cached,
+                503 when the message provably never reached the carrier, so it
+                was not sent and is safe to send again. A 503 is never cached,
                 so the SDK retries it like any 5xx under the same idempotency
                 key. Either way the message wasn't charged. No send returns
                 503 ``whatsapp_unavailable``.
@@ -1060,8 +1060,13 @@ class AsyncMessagesResource:
             agent_id: RCS only - the agent to send as
             card: RCS only - a rich card (title and description required)
             suggestions: RCS only - suggestion chips for a text message
-            fallback_to_sms: RCS only - deliver as SMS when the recipient
-                doesn't support RCS (default True)
+            fallback_to_sms: RCS - deliver as SMS when the recipient
+                doesn't support RCS (default True). Pass False to get a 422
+                rcs_not_supported_for_recipient instead. WhatsApp - default
+                False; True sends an SMS from the same number when WhatsApp
+                can't deliver the message (see message.fallback). The number
+                must be able to send SMS to the recipient, or the API answers
+                403 sms_fallback_unavailable
             idempotency_key: Optional key (1-255 printable ASCII characters)
                 sent as the Idempotency-Key header - retrying with the same
                 key returns the original result instead of sending again.

{sendly-4.4.0 → sendly-4.5.1}/sendly/resources/whatsapp.py

@@ -5,7 +5,7 @@ WhatsApp is a first-class Sendly channel: connect a number you own, create
 Meta-reviewed message templates, and send via
 ``client.messages.send(channel='whatsapp', ...)``.
 
-Connecting a number is a one-time $19 setup (no monthly fee) and always ends
+Connecting a number costs a one-time $9.99 fee (no monthly fee) and always ends
 with a human step: ``signup.create()`` returns a ``connect_url`` that a person
 must open in a browser and log in with Facebook to link their WhatsApp
 Business Account. Hand the URL to your user - that connection cannot be
@@ -99,7 +99,8 @@ class WhatsAppSignupResource:
     ) -> Union[WhatsAppSignupSession, WhatsAppSignup]:
         """Start connecting a number to WhatsApp.
 
-        Charges a one-time $19 setup fee (no monthly fee) and returns a
+        Charges a one-time $9.99 connection fee per number (no monthly fee) to
+        your card when the connection starts, and returns a
         ``connect_url``. Completing the connection requires a human: hand the
         URL to your user - they open it in a browser and log in with Facebook
         to link their WhatsApp Business Account. Then poll :meth:`get` until
@@ -113,13 +114,13 @@ class WhatsAppSignupResource:
         activates the number. Activation usually takes a few minutes but can
         take hours. If it hasn't finished about 6 hours after the session
         began, the session fails with ``registration_timeout`` and the fee is
-        refunded. If the connection fails, the $19 fee is refunded
-        automatically; once the number has connected there is no refund, and
+        refunded. If the connection fails, the $9.99 fee is refunded
+        automatically; once the number has connected it is not refundable, and
         a later disconnect gets nothing back.
 
         Pass ``business_account_id`` to add the number to a WhatsApp
         Business Account this workspace has already connected, without the
-        Facebook step. The same $19 fee applies (refunded automatically if the
+        Facebook step. The same $9.99 fee applies (refunded automatically if the
         connection fails), then WhatsApp sends the number a 6-digit code by
         text or voice call. This returns a :class:`WhatsAppSignup` with status
         ``verifying`` and no ``connect_url``: submit the code with
@@ -174,8 +175,8 @@ class WhatsAppSignupResource:
                 ``Retry-After: 3600`` header. The SDK retries it like any 5xx
                 before raising.
             SendlyError: ``whatsapp_signup_limit_reached`` (429) after 5
-                failed, charged signups in 24 hours. Not retried; try again
-                the next day.
+                failed, charged signups (or 20 cancelled) in 24 hours. Not retried;
+                try again the next day.
             SendlyError: ``whatsapp_verification_in_progress`` (409) without
                 ``business_account_id`` for a number being added by code;
                 ``e.response.model_extra['id']`` is that signup.
@@ -188,7 +189,7 @@ class WhatsAppSignupResource:
                 (``e.response.model_extra['id']`` is that signup);
                 ``whatsapp_already_enabled`` (409) when it is connected.
             SendlyError: ``whatsapp_verification_start_failed``: 422 when
-                WhatsApp refused to send a code (final), 502 when it couldn't
+                WhatsApp refused to send a code (final), 503 when it couldn't
                 be reached. Either way the signup failed and the fee is
                 refunded; start again. Not retried automatically.
         """
@@ -218,7 +219,7 @@ class WhatsAppSignupResource:
         (``settings:write``).
 
         A 5xx, a timeout or a network error is raised at once, never retried:
-        every submission uses one of the 5 attempts, and a 502
+        every submission uses one of the 5 attempts, and a 503
         ``whatsapp_activation_pending`` means WhatsApp already accepted the
         code. Only a 429 the API never ran is retried.
 
@@ -238,9 +239,9 @@ class WhatsAppSignupResource:
                 code for the number is being checked; try again in a moment.
             SendlyError: ``signup_not_active`` (409) when the signup isn't
                 waiting for a code, or is more than 3 hours old.
-            SendlyError: ``whatsapp_verification_unavailable`` (502) when
+            SendlyError: ``whatsapp_verification_unavailable`` (503) when
                 WhatsApp couldn't check the code (the attempt isn't counted),
-                or ``whatsapp_activation_pending`` (502) when the code was
+                or ``whatsapp_activation_pending`` (503) when the code was
                 accepted but the connection didn't finish; Sendly is alerted,
                 so check back with :meth:`get`. Neither is retried
                 automatically.
@@ -280,7 +281,7 @@ class WhatsAppSignupResource:
                 ``e.response.retry_after`` is the wait in seconds. Not
                 retried.
             SendlyError: ``whatsapp_verification_resend_failed``: 422 when
-                WhatsApp wouldn't send another code yet, 502 when it couldn't
+                WhatsApp wouldn't send another code yet, 503 when it couldn't
                 be reached.
             SendlyError: ``signup_not_active`` (409) when the signup isn't
                 waiting for a code, or is more than 3 hours old.
@@ -444,7 +445,7 @@ class WhatsAppSendersResource:
                 5 MB.
             SendlyError: ``whatsapp_sender_not_connected`` (404) when the
                 number isn't connected to WhatsApp.
-            SendlyError: ``whatsapp_profile_update_failed`` (502) when
+            SendlyError: ``whatsapp_profile_update_failed`` (503) when
                 WhatsApp refused the photo or couldn't be reached; check the
                 image is square and at least 192 pixels wide. A 5xx, a
                 timeout or a network error is raised at once, not retried
@@ -482,7 +483,7 @@ class WhatsAppSendersResource:
         Raises:
             SendlyError: ``whatsapp_sender_not_connected`` (404) when the
                 number isn't connected to WhatsApp.
-            SendlyError: ``whatsapp_profile_update_failed`` (502) when
+            SendlyError: ``whatsapp_profile_update_failed`` (503) when
                 WhatsApp couldn't remove it.
         """
         validate_phone_number(phone_number)
@@ -512,7 +513,7 @@ class WhatsAppSendersResource:
             SendlyError: ``whatsapp_sender_not_connected`` (404) when the
                 number isn't connected to WhatsApp.
             SendlyError: ``whatsapp_conversational_components_fetch_failed``
-                (502) when WhatsApp couldn't be reached.
+                (503) when WhatsApp couldn't be reached.
         """
         validate_phone_number(phone_number)
         data = self._http.request(
@@ -555,7 +556,7 @@ class WhatsAppSendersResource:
             SendlyError: ``whatsapp_sender_not_connected`` (404) when the
                 number isn't connected to WhatsApp.
             SendlyError: ``whatsapp_conversational_components_update_failed``
-                (502) when WhatsApp couldn't save them.
+                (503) when WhatsApp couldn't save them.
 
         Example:
             >>> client.whatsapp.senders.update_conversational_components(
@@ -599,7 +600,7 @@ class WhatsAppSendersResource:
                 at least 2,000 people a day and the display name is approved.
             SendlyError: ``whatsapp_sender_not_connected`` (404) when the
                 number isn't connected to WhatsApp.
-            SendlyError: ``whatsapp_calling_update_failed`` (502) when
+            SendlyError: ``whatsapp_calling_update_failed`` (503) when
                 WhatsApp couldn't be reached.
 
         Example:
@@ -771,7 +772,7 @@ class WhatsAppResource:
     """WhatsApp API resource (sync)
 
     Example:
-        >>> # 1. Connect a number ($19 one-time, no monthly fee). The connect
+        >>> # 1. Connect a number ($9.99 one-time, no monthly fee). The connect
         >>> #    URL must be opened by a human - they log in with Facebook in
         >>> #    a browser to link their WhatsApp Business Account.
         >>> signup = client.whatsapp.signup.create('+15559876543')

{sendly-4.4.0 → sendly-4.5.1}/sendly/types.py

@@ -2941,7 +2941,7 @@ class WhatsAppSignup(BaseModel):
             "it still shows the earlier code until the new one arrives. Once "
             "WhatsApp has checked a code, only a code that arrived after the "
             "last submission or resend is returned. A submission answered with "
-            "502 whatsapp_verification_unavailable is not counted, so the same "
+            "503 whatsapp_verification_unavailable is not counted, so the same "
             "unchecked code can come back, and submitting it again is safe"
         ),
     )
@@ -3320,12 +3320,17 @@ class WhatsAppMessage(BaseModel):
         description=(
             "Present when the send asked for fallback_to_sms. When WhatsApp "
             "couldn't take the message and it went as an SMS, status is "
-            "failed and fallback.status is sent"
+            "failed and fallback.status is sent (check with fell_back)"
         ),
     )
 
     model_config = ConfigDict(populate_by_name=True)
 
+    @property
+    def fell_back(self) -> bool:
+        """True when the message went as an SMS instead: fallback.status is sent"""
+        return self.fallback is not None and self.fallback.status == "sent"
+
 
 # ============================================================================
 # RCS

{sendly-4.4.0 → sendly-4.5.1}/sendly/utils/http.py

@@ -28,7 +28,7 @@ T = TypeVar("T")
 DEFAULT_BASE_URL = "https://sendly.live/api/v1"
 DEFAULT_TIMEOUT = 30.0
 DEFAULT_MAX_RETRIES = 3
-SDK_VERSION = "4.4.0"
+SDK_VERSION = "4.5.1"
 
 
 _WAIT_AND_RETRY_CODES = (

{sendly-4.4.0 → sendly-4.5.1}/tests/test_whatsapp.py

@@ -1088,6 +1088,19 @@ class TestWhatsAppSmsFallback:
         assert message.fallback.status == "sent"
         assert message.fallback.message_id == "msg_sms_1"
         assert message.fallback.credits_used == 2
+        assert message.fell_back is True
+
+    @pytest.mark.parametrize("status", ["pending", "failed", "unavailable", "skipped"])
+    def test_fell_back_is_false_until_the_sms_went(
+        self, mock_whatsapp_message, status
+    ):
+        message = WhatsAppMessage.model_validate(
+            {
+                **mock_whatsapp_message,
+                "fallback": {"channel": "sms", "status": status},
+            }
+        )
+        assert message.fell_back is False
 
     def test_leaves_fallback_out_by_default(
         self, api_key, mock_whatsapp_message, httpx_mock: HTTPXMock
@@ -1106,6 +1119,7 @@ class TestWhatsAppSmsFallback:
         payload = json.loads(httpx_mock.get_request().read().decode())
         assert "fallbackToSms" not in payload
         assert message.fallback is None
+        assert message.fell_back is False
 
     @pytest.mark.asyncio
     async def test_async_sends_fallback_to_sms(
@@ -1129,6 +1143,7 @@ class TestWhatsAppSmsFallback:
         payload = json.loads(httpx_mock.get_request().read().decode())
         assert payload["fallbackToSms"] is True
         assert message.fallback.status == "sent"
+        assert message.fell_back is True
 
 
 class TestWhatsAppRecoveredSend: