sendly 4.4.0__tar.gz → 4.5.0__tar.gz

{sendly-4.4.0 → sendly-4.5.0}/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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendly
-Version: 4.4.0
+Version: 4.5.0
 Summary: Official Sendly Python SDK for SMS messaging
 Project-URL: Homepage, https://sendly.live
 Project-URL: Documentation, https://sendly.live/docs
@@ -448,7 +448,7 @@ File uploads (`media.upload()`, `business_upgrade.start()` and `resubmit()`,
 make is the `too_many_concurrent_verifications` wait. `whatsapp.signup.verify()`
 and `whatsapp.signup.create()` with a `business_account_id` also raise a
 timeout, a network error or a `5xx` at once, because repeating them can use up
-a verification attempt or start a new charged signup; they still wait out a
+a verification attempt or start a new signup; they still wait out a
 `429` the API never ran.
 
 After the last attempt the SDK raises the error it last saw (`TimeoutError`,
@@ -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 (free to connect, 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
@@ -1387,10 +1387,8 @@ print(f'Open {signup.connect_url} and log in with Facebook')
 # After the Facebook step it stays 'registering' while WhatsApp 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 ('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.
+# with registration_timeout ('failed', with signup.failure_reasons explaining
+# why).
 
 # 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 +1472,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
+# Free, like a Facebook connection. 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
@@ -1498,14 +1496,14 @@ Senders also carry `business_account_id` (None while `pending`),
 name on file), `calling_enabled`, and `outbound_calling_allowed`, which is
 False for +1, +20, +84 and +234 numbers. A signup that is `verifying` carries
 `verification_method` and `verification_attempts_remaining`; after 5 wrong
-codes it fails with `verification_failed` and the fee is refunded. Calls carry
+codes it fails with `verification_failed`. Calls carry
 `channel` (`phone`, `whatsapp` or `browser`; see `CallChannel`).
 
 `verification_code` comes only from `signup.get()`. Until a code has been
 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.
 
@@ -1531,14 +1529,14 @@ Errors specific to WhatsApp:
   body carries `retryAfter: 3600` and the response a `Retry-After: 3600`
   header. The SDK retries it like any `5xx` before raising;
   `e.response.retry_after` says how many seconds to wait before trying again.
-- `whatsapp_signup_limit_reached` (HTTP 429) after 5 failed, charged signups in
+- `whatsapp_signup_limit_reached` (HTTP 429) after 5 failed signups in
   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,28 +1554,28 @@ 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
-  fee is refunded either way). A Facebook `signup.create()` for a number being
+  `whatsapp_verification_start_failed` (HTTP 422 refused, 503 unreachable). 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),
   `whatsapp_verification_code_invalid` (HTTP 422, with
   `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 +1583,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 +2016,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.0}/README.md

@@ -413,7 +413,7 @@ File uploads (`media.upload()`, `business_upgrade.start()` and `resubmit()`,
 make is the `too_many_concurrent_verifications` wait. `whatsapp.signup.verify()`
 and `whatsapp.signup.create()` with a `business_account_id` also raise a
 timeout, a network error or a `5xx` at once, because repeating them can use up
-a verification attempt or start a new charged signup; they still wait out a
+a verification attempt or start a new signup; they still wait out a
 `429` the API never ran.
 
 After the last attempt the SDK raises the error it last saw (`TimeoutError`,
@@ -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 (free to connect, 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
@@ -1352,10 +1352,8 @@ print(f'Open {signup.connect_url} and log in with Facebook')
 # After the Facebook step it stays 'registering' while WhatsApp 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 ('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.
+# with registration_timeout ('failed', with signup.failure_reasons explaining
+# why).
 
 # 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 +1437,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
+# Free, like a Facebook connection. 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
@@ -1463,14 +1461,14 @@ Senders also carry `business_account_id` (None while `pending`),
 name on file), `calling_enabled`, and `outbound_calling_allowed`, which is
 False for +1, +20, +84 and +234 numbers. A signup that is `verifying` carries
 `verification_method` and `verification_attempts_remaining`; after 5 wrong
-codes it fails with `verification_failed` and the fee is refunded. Calls carry
+codes it fails with `verification_failed`. Calls carry
 `channel` (`phone`, `whatsapp` or `browser`; see `CallChannel`).
 
 `verification_code` comes only from `signup.get()`. Until a code has been
 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.
 
@@ -1496,14 +1494,14 @@ Errors specific to WhatsApp:
   body carries `retryAfter: 3600` and the response a `Retry-After: 3600`
   header. The SDK retries it like any `5xx` before raising;
   `e.response.retry_after` says how many seconds to wait before trying again.
-- `whatsapp_signup_limit_reached` (HTTP 429) after 5 failed, charged signups in
+- `whatsapp_signup_limit_reached` (HTTP 429) after 5 failed signups in
   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,28 +1519,28 @@ 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
-  fee is refunded either way). A Facebook `signup.create()` for a number being
+  `whatsapp_verification_start_failed` (HTTP 422 refused, 503 unreachable). 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),
   `whatsapp_verification_code_invalid` (HTTP 422, with
   `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 +1548,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 +1981,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.0}/pyproject.toml

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

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

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

{sendly-4.4.0 → sendly-4.5.0}/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.0}/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 is free (no setup or 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,40 +99,35 @@ class WhatsAppSignupResource:
     ) -> Union[WhatsAppSignupSession, WhatsAppSignup]:
         """Start connecting a number to WhatsApp.
 
-        Charges a one-time $19 setup fee (no monthly fee) and returns a
+        Connecting a number is free (no setup or monthly fee). 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
         the status is ``active``.
 
         Calling again for a number with an in-flight signup returns the
-        existing signup (same ``connect_url``) without charging again.
+        existing signup (same ``connect_url``).
         Requires a live API key with the ``whatsapp:write`` scope and, in a
         team workspace, an owner or admin (``settings:write``). After the
         Facebook step the signup stays ``registering`` while WhatsApp
         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
-        a later disconnect gets nothing back.
+        began, the session fails with ``registration_timeout``.
 
         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
-        connection fails), then WhatsApp sends the number a 6-digit code by
-        text or voice call. This returns a :class:`WhatsAppSignup` with status
+        Facebook step. It is free too: 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
         :meth:`verify`, or read it from :meth:`get` as ``verification_code``
         once the text reaches the number. Calling again for a number that is
-        already verifying returns that signup without a second charge or a
-        second code, with two exceptions: if the first call stopped before
+        already verifying returns that signup without a second code, with
+        two exceptions: if the first call stopped before
         the code was requested, the repeat requests it (201); and a verifying
-        signup more than 3 hours old is failed and refunded, and a new charged
-        one is started. With ``business_account_id`` a 5xx, a timeout or a
+        signup more than 3 hours old is failed and a new one is started. With ``business_account_id`` a 5xx, a timeout or a
         network error is raised at once, never retried: each attempt can
-        start a new signup that is charged and, when it fails, refunded. Only
-        a 429 the API never ran is retried.
+        start a new signup and ask WhatsApp for another code. Only a 429 the
+        API never ran is retried.
 
         Args:
             phone_number: The number to connect, in E.164 format. Must be an
@@ -169,13 +164,13 @@ class WhatsAppSignupResource:
                 lacks ``whatsapp:write`` or the role isn't owner or admin.
             SendlyError: ``whatsapp_requires_live_key`` (403) with a test key.
             SendlyError: ``whatsapp_unavailable`` (503) while WhatsApp
-                connections are unavailable. Nothing is charged. Only signup
+                connections are unavailable. Only signup
                 returns it, with ``retryAfter: 3600`` in the body and a
                 ``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 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,9 +183,9 @@ 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
-                be reached. Either way the signup failed and the fee is
-                refunded; start again. Not retried automatically.
+                WhatsApp refused to send a code (final), 503 when it couldn't
+                be reached. Either way the signup failed; start again. Not
+                retried automatically.
         """
         validate_phone_number(phone_number)
         body = _signup_body(phone_number, business_account_id, verification_method, display_name)
@@ -218,7 +213,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.
 
@@ -233,14 +228,14 @@ class WhatsAppSignupResource:
                 wrong code; ``e.response.attempts_remaining`` says how many
                 tries are left.
             SendlyError: ``whatsapp_verification_failed`` (409) after 5 wrong
-                codes: the signup failed and the fee is refunded.
+                codes: the signup failed.
             SendlyError: ``whatsapp_verification_busy`` (409) while another
                 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 +275,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 +439,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 +477,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 +507,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 +550,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 +594,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 +766,7 @@ class WhatsAppResource:
     """WhatsApp API resource (sync)
 
     Example:
-        >>> # 1. Connect a number ($19 one-time, no monthly fee). The connect
+        >>> # 1. Connect a number (free, 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.0}/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.0}/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.0"
 
 
 _WAIT_AND_RETRY_CODES = (

{sendly-4.4.0 → sendly-4.5.0}/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:

{sendly-4.4.0 → sendly-4.5.0}/tests/test_whatsapp_extras.py

@@ -892,8 +892,7 @@ def no_async_sleep(monkeypatch):
 START_FAILED = {
     "error": "whatsapp_verification_start_failed",
     "message": (
-        "WhatsApp couldn't start verifying this number. Any setup fee is refunded "
-        "automatically. Please try again shortly."
+        "WhatsApp couldn't start verifying this number. Please try again shortly."
     ),
 }
 
@@ -944,8 +943,7 @@ class TestServerErrorsOnCallsThatMustNotRepeat:
             json={
                 "error": "internal_error",
                 "message": (
-                    "Something went wrong asking WhatsApp for the code. Any setup fee is "
-                    "refunded automatically. Please try again."
+                    "Something went wrong asking WhatsApp for the code. Please try again."
                 ),
             },
             is_reusable=True,