sendly 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a69a00fe63398e0ad342ed03ad9ddf38d668fe0d2ddd85533a2aa43e534eacb
-  data.tar.gz: 8488579a38c0f09720a8d9e67a5084819eb884dfe6cc99afc66be5d143ae5323
+  metadata.gz: 511e36e32d4475552b4000a026856bde62c06bd7f43a52b59646c347d7ff4b0c
+  data.tar.gz: 92531f77aa366320d2887a3b9a0ac9793c6562d507f3863577352830097f4d32
 SHA512:
-  metadata.gz: caa9cd2bb16dc70c5eea42f760fe9295587e0f3b8c7a83bb4de6af903b5ba29ff6ec89c6c53ab211fc630c68d8139648516a95dccd27412382be08012ba922ed
-  data.tar.gz: b5ef93d9ce46c42dd53ef375b23aa66a5027e6534bf93425ab507d37f4c2f17311cdefbda52269e2fbad9b167808ad96abae255fd0b216942d5af1873d5f8337
+  metadata.gz: 000020f0a21c87fb3f4b33ca84fad93e36a73abaa936ca602b22c3065e7fbc3d09b2c0fe62b02f2080dbab1f2b4d37d8ad60648d08e0a0d022a71bbcd64b1ee6
+  data.tar.gz: fbc1718f201afe7895d433d989bf41e7c0938fac6c029dca8380b2d88620ef56d65851a258b9d3e39ad683652023e8468ef534c8a459ce930fcf35cc6d07ddba

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # sendly (Ruby)
 
+## 4.5.0
+
+### Patch Changes
+
+- **`Sendly::ValidationError#status_code` is the response's real status.** It was always 400, so a 422 (such as `whatsapp_window_closed` or `sms_fallback_not_supported`) reported 400. Code that compared `status_code` with 400 to spot a validation error should check the class (or `code`) instead. `ValidationError.new` takes an optional `status_code:`, 400 by default.
+- 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (4.4.0)
+    sendly (4.5.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 

data/README.md

@@ -1153,11 +1153,11 @@ puts status.disabled?
 
 Connect a number you own to WhatsApp, create Meta-reviewed message
 templates, and send via `client.messages.send(channel: "whatsapp", ...)`.
-Connecting is a one-time $19 setup (no monthly fee). The first number always
+Connecting is free (no monthly fee either). The first number always
 ends with a human step: the signup returns a connect URL a person must open in
 a browser and log in with Facebook to link their WhatsApp Business Account.
 More numbers can then be added to that account with a 6-digit code Meta sends
-to the number, with no Facebook step (same $19 fee, refunded if it fails).
+to the number, with no Facebook step (also free).
 
 Sends go through `messages.send(channel: "whatsapp")` and need `sms:send`,
 not `whatsapp:write`. Reads (`signup.get`, templates, the window, senders and
@@ -1191,16 +1191,14 @@ gives its slot back. Note: Meta
 has paused marketing template delivery to US (+1) numbers.
 
 ```ruby
-# 1. Connect a number ($19 one-time; a human must open the connect URL)
+# 1. Connect a number (free; a human must open the connect URL)
 signup = client.whatsapp.signup.create(phone_number: "+15125550123")
 puts "Have your user open: #{signup.connect_url}"
 
 # 2. Poll until active. After the Facebook step the signup is "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 a
-# number has connected, a later disconnect gets nothing back.
+# began, the session fails with registration_timeout.
 status = client.whatsapp.signup.get(signup.id)
 puts status.failure_reasons if status.failed?  # e.g. ["waba_mismatch"]
 
@@ -1257,7 +1255,7 @@ puts added.status  # "verifying"
 # code has been submitted it is the newest code 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 502 whatsapp_verification_unavailable
+# submission or resend is returned. A 503 whatsapp_verification_unavailable
 # isn't counted, so the same unchecked code can come back, and submitting it
 # again is safe.
 code = client.whatsapp.signup.get(added.id).verification_code
@@ -1316,25 +1314,6 @@ client.messages.send(
   text: "Here is your receipt",
   media_urls: ["https://acme.example/receipt.pdf"]
 )
-
-# Fall back to SMS from the same number when WhatsApp can't deliver: the
-# window is closed, WhatsApp refuses it, or reports it undeliverable later.
-# The SMS is billed as an SMS. The number must already be able to send SMS to
-# the recipient (US and Canada), or this raises 403 sms_fallback_unavailable;
-# marketing and authentication templates, and media without a caption, raise
-# 422 sms_fallback_not_supported.
-message = client.messages.send(
-  channel: "whatsapp",
-  to: "+15555550100",
-  from: "+15125550123",
-  text: "Your table is ready!",
-  fallback_to_sms: true
-)
-message.fallback.status    # "pending", "sent", "failed", "unavailable" or "skipped"
-message.fallback.reason    # "window_closed", "whatsapp_refused" or "whatsapp_failed"
-message.fell_back?         # true when the SMS went (message.status is then "failed")
-sms = client.messages.get(message.fallback.message_id) if message.fallback.message_id
-sms&.fallback_of           # the WhatsApp message's id
 ```
 
 WhatsApp errors map onto the usual classes:
@@ -1343,7 +1322,7 @@ WhatsApp errors map onto the usual classes:
   while WhatsApp connections are unavailable. Only signup returns it; no send
   does. Nothing is charged, the response carries a `Retry-After: 3600` header,
   and `e.response_body["retryAfter"]` (3600) says how many seconds to wait; the client
-  retries it like any 5xx before raising. After 5 failed, charged signups in
+  retries it like any 5xx before raising. After 5 failed signups in
   24 hours it raises `Sendly::RateLimitError` for 429
   `whatsapp_signup_limit_reached`, which is not retried: try again the next
   day.
@@ -1351,10 +1330,13 @@ WhatsApp errors map onto the usual classes:
   `whatsapp_window_closed`); send a template instead.
 - `whatsapp_send_failed` is a `Sendly::ValidationError` (422) when WhatsApp
   refused the message, which is final (cached under the idempotency key and
-  replayed for 24 hours), and a `Sendly::ServerError` (502) when the message
-  provably never reached the carrier, so it was not sent and is safe to send
-  again; the 502 is never cached and the client retries it first under the
-  same idempotency key. Neither is charged.
+  replayed for 24 hours), and a `Sendly::ServerError` (503) when the message
+  provably never reached WhatsApp, so it was not sent and is safe to resend
+  under the same idempotency key; the 503 is never cached and the client
+  retries it automatically, up to 3 times under the same key, before raising.
+  Neither is charged. With `fallback_to_sms: true`, a 422 means the SMS
+  couldn't go either, and `e.response_body["fallback"]` says why; see
+  [SMS fallback](#sms-fallback).
 - `whatsapp_send_unconfirmed` is a `Sendly::APIError` with `status_code` 409:
   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
@@ -1382,11 +1364,11 @@ WhatsApp errors map onto the usual classes:
   400 `display_name_required` and for 422 `whatsapp_verification_start_failed`
   (WhatsApp refused to verify the number; final), `Sendly::APIError` (409) for
   `whatsapp_signup_in_progress` and `whatsapp_already_enabled`, and
-  `Sendly::ServerError` for 502 `whatsapp_verification_start_failed` (WhatsApp
+  `Sendly::ServerError` for 503 `whatsapp_verification_start_failed` (WhatsApp
   couldn't start verifying the number; start again). Either failure fails the
-  session and refunds its fee. With `business_account_id:` the client never
-  retries a 5xx, a timeout or a dropped connection, because each retry would
-  start a new charged session. A
+  session. With `business_account_id:` the client never retries a 5xx, a
+  timeout or a dropped connection, because each retry would start a new
+  session. A
   Facebook signup for a number
   that is being added by code gets 409 `whatsapp_verification_in_progress`,
   with that session's id in `e.response_body["id"]`.
@@ -1394,9 +1376,9 @@ WhatsApp errors map onto the usual classes:
   `invalid_verification_code` (not 6 digits) and 422
   `whatsapp_verification_code_invalid` (a wrong code, with
   `e.response_body["attemptsRemaining"]`); `Sendly::APIError` (409) for
-  `whatsapp_verification_failed` (after 5 wrong codes the session fails and
-  the fee is refunded), `whatsapp_verification_busy` (try again) and
-  `signup_not_active`; and `Sendly::ServerError` for 502
+  `whatsapp_verification_failed` (after 5 wrong codes the session fails),
+  `whatsapp_verification_busy` (try again) and
+  `signup_not_active`; and `Sendly::ServerError` for 503
   `whatsapp_verification_unavailable` (the attempt isn't counted) and
   `whatsapp_activation_pending` (the code was accepted but connecting didn't
   finish; check back shortly with `signup.get`). The client never retries a
@@ -1406,13 +1388,13 @@ WhatsApp errors map onto the usual classes:
 - `signup.resend` raises `Sendly::RateLimitError` for 429
   `whatsapp_verification_resend_too_soon` at once, with the seconds to wait in
   `e.retry_after`, and `whatsapp_verification_resend_failed` as a
-  `Sendly::ValidationError` (422) or a `Sendly::ServerError` (502).
+  `Sendly::ValidationError` (422) or a `Sendly::ServerError` (503).
 - `senders.upload_profile_photo` raises `Sendly::ValidationError` for 400
   `whatsapp_profile_photo_invalid` (not a JPEG or PNG) and `file_required`,
   and `Sendly::APIError` with `status_code` 413 for
   `whatsapp_profile_photo_too_large`. The photo methods raise
-  `Sendly::ServerError` for 502 `whatsapp_profile_update_failed`, and the
-  conversational component methods for 502
+  `Sendly::ServerError` for 503 `whatsapp_profile_update_failed`, and the
+  conversational component methods for 503
   `whatsapp_conversational_components_fetch_failed` and
   `whatsapp_conversational_components_update_failed`; an invalid list is a
   `Sendly::ValidationError` (400 `invalid_request`) with a message naming the
@@ -1422,10 +1404,78 @@ WhatsApp errors map onto the usual classes:
   (switch voice on for the number first), `Sendly::ValidationError` for 422
   `whatsapp_calling_unavailable` (Meta only allows calling once the account may
   message at least 2,000 people a day and the display name is approved), and
-  `Sendly::ServerError` for 502 `whatsapp_calling_update_failed`.
+  `Sendly::ServerError` for 503 `whatsapp_calling_update_failed`.
 - A sender method for a number that isn't connected raises
   `Sendly::NotFoundError` (404 `whatsapp_sender_not_connected`).
 
+### 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.
+
+```ruby
+begin
+  message = client.messages.send(
+    channel: "whatsapp",
+    to: "+15555550100",
+    from: "+15125550123",
+    text: "Your table is ready!",
+    fallback_to_sms: true
+  )
+  puts message.fallback.status  # "pending", "sent", "failed", "unavailable" or "skipped"
+  puts message.fallback.reason  # "window_closed", "whatsapp_refused" or "whatsapp_failed"
+  if message.fell_back?         # the SMS went instead (message.status is "failed")
+    sms = client.messages.get(message.fallback.message_id)
+    puts sms.fallback_of        # the WhatsApp message's id
+  end
+rescue Sendly::Error => e
+  body = e.response_body || {}
+  case e.code
+  when "sms_fallback_unavailable"
+    # 403: this number can't send SMS to the recipient; nothing was sent
+  when "sms_fallback_not_supported"
+    puts body["reason"] # marketing_template, authentication_template or media_without_caption
+  else
+    raise unless body["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 = Sendly::WhatsAppSmsFallback.new(body["fallback"])
+    puts "#{e.code} #{body["id"]} #{fallback.status}: #{fallback.error}"
+  end
+end
+```
+
+- 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 403 `sms_fallback_unavailable`
+  before anything is sent.
+- Marketing and authentication templates, and media without a caption, can't
+  fall back: 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"`; `fallback.credits_used` is
+  what the SMS cost.
+- No SMS goes on a 409 `whatsapp_send_unconfirmed` or a 503
+  `whatsapp_send_failed`. The 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 rich messages — text with suggested replies and actions, or
@@ -1769,8 +1819,8 @@ string), `invalid_voice_mode`, `agent_required`,
 the address could not be validated, and `e.response_body["suggested"]` holds
 a corrected address when one was found); `Sendly::APIError` with
 `status_code` 409 for `agent_disabled`, `agent_limit` (20 agents per
-workspace) and `agent_in_use`; and `Sendly::ServerError` for 502
-`voice_attach_failed` and `carrier_refused` and 503 `voice_unavailable`,
+workspace) and `agent_in_use`; and `Sendly::ServerError` for 503
+`voice_attach_failed`, `carrier_refused` and `voice_unavailable`,
 raised after the client has already retried the 5xx on its own. Not every
 `carrier_refused` is worth retrying: when the message says the number
 couldn't be found for emergency registration, retrying won't help, so

data/lib/sendly/errors.rb

@@ -73,9 +73,9 @@ module Sendly
     #   e.g. +[{ "path" => "brand.ein", "message" => "Enter a 9-digit EIN" }]+
     attr_reader :field_errors
 
-    def initialize(message = "Validation failed", field_errors: nil, details: nil, code: nil)
+    def initialize(message = "Validation failed", field_errors: nil, details: nil, code: nil, status_code: 400)
       @field_errors = field_errors
-      super(message, code: code || "VALIDATION_ERROR", details: details, status_code: 400)
+      super(message, code: code || "VALIDATION_ERROR", details: details, status_code: status_code)
     end
   end
 
@@ -127,7 +127,7 @@ module Sendly
 
       error = case status
               when 400, 422
-                ValidationError.new(message, details: details, field_errors: body["errors"], code: code)
+                ValidationError.new(message, details: details, field_errors: body["errors"], code: code, status_code: status)
               when 401
                 AuthenticationError.new(message, code: code)
               when 402

data/lib/sendly/messages.rb

@@ -86,7 +86,7 @@ module Sendly
     #   WhatsApp the 422 +whatsapp_send_failed+ when WhatsApp refused the
     #   message (final, not retried, not charged; cached under the
     #   idempotency key and replayed for 24 hours)
-    # @raise [Sendly::ServerError] On WhatsApp, the 502 +whatsapp_send_failed+:
+    # @raise [Sendly::ServerError] On WhatsApp, the 503 +whatsapp_send_failed+:
     #   the message provably never reached the carrier, so it was not sent
     #   and is safe to send again. It isn't charged and is never cached, so
     #   the client retries it like any 5xx first under the same idempotency

data/lib/sendly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sendly
-  VERSION = "4.4.0"
+  VERSION = "4.5.0"
 end

data/lib/sendly/voice_resource.rb

@@ -402,7 +402,7 @@ module Sendly
     # @raise [Sendly::NotFoundError] HTTP 404 +number_not_found+ / +agent_not_found+
     # @raise [Sendly::APIError] HTTP 409 +agent_disabled+ (the agent is
     #   switched off), 403 +forbidden+ / +live_key_required+
-    # @raise [Sendly::ServerError] HTTP 502 +voice_attach_failed+ (voice could
+    # @raise [Sendly::ServerError] HTTP 503 +voice_attach_failed+ (voice could
     #   not be switched on; try again) or 503 +voice_unavailable+, after the
     #   client's automatic retries. Either can follow a mode alone on a number
     #   whose voice is off.
@@ -454,7 +454,7 @@ module Sendly
     #   422 +invalid_address+ when the address could not be validated, with a
     #   corrected address (or +nil+) in +e.response_body["suggested"]+
     # @raise [Sendly::NotFoundError] HTTP 404 +number_not_found+
-    # @raise [Sendly::ServerError] HTTP 502 +carrier_refused+ when the
+    # @raise [Sendly::ServerError] HTTP 503 +carrier_refused+ when the
     #   registration was refused, raised after the client has already retried
     #   the 5xx on its own. When the message says the number couldn't be
     #   found for emergency registration, retrying won't help: contact
@@ -691,7 +691,7 @@ module Sendly
   # +agent_disabled+ / +agent_limit+ / +agent_in_use+ (409) and +forbidden+
   # / +live_key_required+ / +insufficient_permissions+ (403); and
   # {Sendly::ServerError} (not an +APIError+) for +voice_attach_failed+ /
-  # +carrier_refused+ (502), +voice_unavailable+ (503) and
+  # +carrier_refused+ / +voice_unavailable+ (503) and
   # +voice_internal_error+ (500). Every API error keeps the parsed body on
   # {Sendly::Error#response_body}. The full list is {Call::ERROR_CODES}.
   #

data/lib/sendly/whatsapp_resource.rb

@@ -63,8 +63,8 @@ module Sendly
   # The status of a WhatsApp signup. +status+ is +"initiated"+,
   # +"registering"+ (WhatsApp is activating the number; activation usually
   # takes a few minutes but can take hours, and a session that hasn't
-  # finished about 6 hours after it began fails with +registration_timeout+
-  # and the fee is refunded), +"verifying"+ (a number being added to an
+  # finished about 6 hours after it began fails with +registration_timeout+),
+  # +"verifying"+ (a number being added to an
   # already-connected account, waiting for its code), +"active"+ or
   # +"failed"+. The API does not send +"expired"+,
   # so {#expired?} is never true; it stays for compatibility.
@@ -72,7 +72,8 @@ module Sendly
   # +"active"+ (from the start for a number added by code); it is nil while
   # +"initiated"+ or +"registering"+ and after a failure.
   # +failure_reasons+ is set when the status is +"failed"+, with one code:
-  # +setup_fee_payment_failed+, +signup_abandoned+, +meta_exchange_failed+,
+  # +setup_fee_payment_failed+ (the connection couldn't be started),
+  # +signup_abandoned+, +meta_exchange_failed+,
   # +registration_failed+, +waba_already_connected+, +waba_mismatch+ (the
   # WhatsApp Business Account chosen in the Facebook step doesn't hold the
   # verified number), +registration_timeout+ (activation hadn't finished
@@ -80,7 +81,6 @@ module Sendly
   # +verification_start_failed+ (WhatsApp couldn't start verifying an added
   # number), +verification_failed+ (too many wrong codes) or
   # +verification_expired+ (a verifying session left untouched for an hour).
-  # If the connection fails, the $19 fee is refunded automatically.
   #
   # While the status is +"verifying"+, +verification_method+ (+"sms"+ or
   # +"voice"+) and +verification_attempts_remaining+ are set, and on
@@ -90,7 +90,7 @@ module Sendly
   # 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 +whatsapp_verification_unavailable+ is not counted, so the same
+  # with 503 +whatsapp_verification_unavailable+ is not counted, so the same
   # unchecked code can come back, and submitting it again with
   # {WhatsAppSignupResource#verify} is safe. All three are nil in any other
   # status.
@@ -533,34 +533,31 @@ module Sendly
 
     # 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 {#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. Requires
+    # existing signup (same +connect_url+). Requires
     # a live API key with the +whatsapp:write+ scope (a test key gets 403
     # +whatsapp_requires_live_key+) 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.
+    # +registration_timeout+.
     #
     # To add a number to a WhatsApp Business Account this workspace has
     # already connected, pass its +business_account_id+ (as shown on
     # {WhatsAppSender#business_account_id}). There is no Facebook step and no
-    # +connect_url+: the same $19 fee is charged, Meta sends the number a
+    # +connect_url+: it is free too, Meta sends the number a
     # 6-digit code by text or voice call, and the session is +"verifying"+
     # until you submit the code with {#verify}. Calling again for a number
-    # that is verifying returns the same session without charging again or
-    # sending a second code; a verifying session older than 3 hours is
-    # expired (and refunded) and a new one is started.
+    # that is verifying returns the same session without sending a second
+    # code; a verifying session older than 3 hours is expired and a new one
+    # is started.
     #
     # @param phone_number [String] The number to connect, in E.164 format.
     #   Must be an active number in your workspace.
@@ -575,20 +572,20 @@ module Sendly
     #   +business_account_id+.
     # @return [WhatsAppSignupSession]
     # @raise [Sendly::ServerError] +whatsapp_unavailable+ (503) while
-    #   WhatsApp connections are unavailable. Nothing is charged. Only
+    #   WhatsApp connections are unavailable. Only
     #   signup returns it, with +retryAfter+ 3600 in the body
     #   (+e.response_body["retryAfter"]+) and a +Retry-After: 3600+ header.
     #   The client retries it like any 5xx before raising.
     # @raise [Sendly::RateLimitError] +whatsapp_signup_limit_reached+ (429)
-    #   after 5 failed, charged signups in 24 hours. Not retried; try again
-    #   the next day.
+    #   after 5 failed signups (or 20 cancelled) in 24 hours. Not retried;
+    #   try again the next day.
     # @raise [Sendly::NotFoundError] +whatsapp_business_account_not_found+
     #   (404) when +business_account_id+ isn't connected in this workspace
     #   with an active number.
     # @raise [Sendly::ValidationError] +display_name_required+ (400) when no
     #   display name is given and the account has none to reuse, and
     #   +whatsapp_verification_start_failed+ (422) when WhatsApp refused to
-    #   verify the number: final, the session failed and the fee is refunded.
+    #   verify the number: final, the session failed.
     # @raise [Sendly::APIError] 409 +whatsapp_signup_in_progress+ (a Facebook
     #   connection for the number is in flight; +e.response_body["id"]+ is
     #   that session), 409 +whatsapp_verification_in_progress+ (a Facebook
@@ -597,14 +594,14 @@ module Sendly
     #   still being added, so try again in a moment) or 409
     #   +whatsapp_already_enabled+.
     # @raise [Sendly::InsufficientCreditsError] 402 +payment_method_required+
-    #   or +payment_failed+ when the $19 fee can't be charged.
-    # @raise [Sendly::ServerError] +whatsapp_verification_start_failed+ (502)
-    #   when WhatsApp couldn't start verifying the number: the session failed
-    #   and its fee is refunded, so start again. With +business_account_id+,
-    #   a 5xx is raised at once and never retried by the client, because
-    #   each retry would start a new charged session (a timeout or dropped
-    #   connection is never retried either). Without it the client retries a
-    #   5xx before raising, as before.
+    #   or +payment_failed+: not returned while connecting a number is free.
+    # @raise [Sendly::ServerError] +whatsapp_verification_start_failed+ (503)
+    #   when WhatsApp couldn't start verifying the number: the session failed,
+    #   so start again. With +business_account_id+, a 5xx is raised at once
+    #   and never retried by the client, because each retry would start a
+    #   new session (a timeout or dropped connection is never retried
+    #   either). Without it the client retries a 5xx before raising, as
+    #   before.
     #
     # @example
     #   signup = client.whatsapp.signup.create(phone_number: "+15559876543")
@@ -649,14 +646,14 @@ module Sendly
     #   (422) for a wrong code, with the attempts left in
     #   +e.response_body["attemptsRemaining"]+
     # @raise [Sendly::APIError] 409 +whatsapp_verification_failed+ after 5
-    #   wrong codes (the session failed, the fee is refunded and
+    #   wrong codes (the session failed and
     #   +whatsapp_account.failed+ fires), 409 +whatsapp_verification_busy+
     #   while another code for the number is being checked (try again), or
     #   409 +signup_not_active+ when the signup isn't waiting for a code or is
     #   older than 3 hours
     # @raise [Sendly::NotFoundError] +signup_not_found+ (404)
-    # @raise [Sendly::ServerError] 502 +whatsapp_verification_unavailable+
-    #   (WhatsApp couldn't check the code; the attempt isn't counted) or 502
+    # @raise [Sendly::ServerError] 503 +whatsapp_verification_unavailable+
+    #   (WhatsApp couldn't check the code; the attempt isn't counted) or 503
     #   +whatsapp_activation_pending+ (the code was accepted but connecting
     #   the number didn't finish; check back shortly with {#get}). A 5xx, a
     #   timeout or a dropped connection is raised at once and never retried
@@ -695,7 +692,7 @@ module Sendly
     #   waiting for a code or is older than 3 hours
     # @raise [Sendly::NotFoundError] +signup_not_found+ (404)
     # @raise [Sendly::ServerError] +whatsapp_verification_resend_failed+
-    #   (502) when WhatsApp couldn't be reached. The client retries a 5xx
+    #   (503) when WhatsApp couldn't be reached. The client retries a 5xx
     #   before raising.
     #
     # @example
@@ -847,7 +844,7 @@ module Sendly
     # @raise [Sendly::APIError] +whatsapp_profile_photo_too_large+ with
     #   +status_code+ 413 when the photo is over 5 MB
     # @raise [Sendly::NotFoundError] +whatsapp_sender_not_connected+ (404)
-    # @raise [Sendly::ServerError] +whatsapp_profile_update_failed+ (502)
+    # @raise [Sendly::ServerError] +whatsapp_profile_update_failed+ (503)
     #   when WhatsApp refused the image or couldn't be reached. A 5xx, a
     #   timeout or a dropped connection is raised at once and never retried
     #   by the client; check the image is
@@ -876,7 +873,7 @@ module Sendly
     # @return [WhatsAppSenderProfile] The profile, normally with
     #   +profile_photo_url+ nil
     # @raise [Sendly::NotFoundError] +whatsapp_sender_not_connected+ (404)
-    # @raise [Sendly::ServerError] +whatsapp_profile_update_failed+ (502).
+    # @raise [Sendly::ServerError] +whatsapp_profile_update_failed+ (503).
     #   The client retries a 5xx before raising.
     #
     # @example
@@ -899,7 +896,7 @@ module Sendly
     # @return [WhatsAppConversationalComponents]
     # @raise [Sendly::NotFoundError] +whatsapp_sender_not_connected+ (404)
     # @raise [Sendly::ServerError]
-    #   +whatsapp_conversational_components_fetch_failed+ (502). The client
+    #   +whatsapp_conversational_components_fetch_failed+ (503). The client
     #   retries a 5xx before raising.
     #
     # @example
@@ -933,7 +930,7 @@ module Sendly
     #   +invalid_request+ (400) with a message naming the problem
     # @raise [Sendly::NotFoundError] +whatsapp_sender_not_connected+ (404)
     # @raise [Sendly::ServerError]
-    #   +whatsapp_conversational_components_update_failed+ (502). The client
+    #   +whatsapp_conversational_components_update_failed+ (503). The client
     #   retries a 5xx before raising.
     #
     # @example
@@ -974,7 +971,7 @@ module Sendly
     #   when Meta refused: calling needs the account at the 2,000
     #   recipients a day messaging limit and an approved display name
     # @raise [Sendly::NotFoundError] +whatsapp_sender_not_connected+ (404)
-    # @raise [Sendly::ServerError] +whatsapp_calling_update_failed+ (502).
+    # @raise [Sendly::ServerError] +whatsapp_calling_update_failed+ (503).
     #   The client retries a 5xx before raising.
     #
     # @example
@@ -1153,7 +1150,7 @@ module Sendly
   # 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). The first
+  # Connecting a number is free (no setup or monthly fee). The first
   # number always ends with a human step: {WhatsAppSignupResource#create}
   # returns a +connect_url+ that a person must open in a browser and log in
   # with Facebook to link their WhatsApp Business Account. More numbers can
@@ -1195,7 +1192,7 @@ module Sendly
   # every method on this resource gets 404 +not_found+.
   #
   # @example Connect a number, create a template, then send
-  #   # 1. Connect ($19 one-time; a human must open the connect URL)
+  #   # 1. Connect (free; a human must open the connect URL)
   #   signup = client.whatsapp.signup.create(phone_number: "+15559876543")
   #   puts "Have your user open: #{signup.connect_url}"
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Sendly
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday