sendly 4.5.1 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e684d2e1e6cb9addd168326d6874152b070b68ab599ba9370eca565a8a70d3ce
4
- data.tar.gz: 13ddbe1ae8aed4e2683515a8a7de05f135c037dd12984974a92e173158cf2843
3
+ metadata.gz: cd8bd2432a03d19a38e0dc47c461f4dbad4c9a4b013ab9e96b7607f8b35b36e2
4
+ data.tar.gz: 79ef91d98be989137f035607ffadc5aed78eaa5eea57a2b688330506ebf046d3
5
5
  SHA512:
6
- metadata.gz: dab32a1714f5fbe937f3d109d03b4e634311ac890c7f3126dc98653eaa88631ddb2ba6591697f5be9b59595530e5e85d1932b951e645675b79e89b677adbc2db
7
- data.tar.gz: 53bf4c50b966f79ca3221292ffd2095e6d21007e50421fbd0aa6e7f4c3067060c63ec6ff0524fe87ceeee62690cd83aaafd0bceb83534658d5243677e44d91b1
6
+ metadata.gz: 651ea09da682da2609e22a51be6fe5fff359f6d1fa25cb41ef4e1626b9a815e8c2e1ef617968226293a9f4b36d625bf26d03ba84c0c2acc2d439fd35a2c3c65d
7
+ data.tar.gz: 59f52da8b5c0db3ed04db7325ab90af35cfa014a5277aa160bd22e746de9d9a04793606573b936b1cb8229a2bb8839f0cf88c50b9ef8e77770ef5f869b1fe20b
data/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # sendly (Ruby)
2
2
 
3
+ ## 4.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - **`SuggestRepliesResponse` gains `disabled`, `disabled?` and `reason`.** When the workspace's enterprise account turned AI suggestions off, `conversations.suggest_replies` returns no suggestions, `disabled?` is true and `reason` is `"enterprise_policy"`. `to_h` includes both only then.
8
+ - **`Message#batch_id`** is the batch that sent the message, read from `batchId` or `batch_id`; nil unless it is a batch message. `to_h` includes it when present.
9
+ - **Preview a template.** `templates.preview(id, variables: { code: "123456" })` posts to `/templates/:id/preview` and returns the new `Sendly::TemplatePreview` (`template_id`, `original_text`, `rendered_text`, `character_count`, `segment_count`, and `to_h`). It renders one of your templates, or any preset, and sends nothing; without `variables`, each variable takes its fallback. An id that is neither yours nor a preset raises `Sendly::NotFoundError`.
10
+ - **Preview a webhook recovery.** `webhooks.recovery_preview(id, since:, until_:, event_types:)` reads `GET /webhooks/:id/recovery-preview` and returns the new `Sendly::WebhookRecoveryPreview` (`circuit_state`, `circuit_opened_at`, `failure_count`, `audit_failures`, `missing_from_messages`, `histogram`, `samples`, `window_suggestion`, `since`, `until`, `circuit_open?` and `raw`): what `redeliver` and `backfill` would send for the window, without sending anything. Nested values are Hashes with symbol keys, times are `Time`, and `event_types` goes as one comma-separated value. The window is at most 7 days.
11
+ - **Short codes.** The new `client.short_codes` resource: `list` (`GET /short_codes`) returns an Array of `Sendly::ShortCode` (`id`, `short_code`, `country_code`, `status`, `review_status`, `use_case`, `created_at`, `billing`, `active?`), and `application` has `get`, `update(**answers)` (`PUT /short_codes/application`), `check(**answers)` (`POST /short_codes/application/preflight`) and `submit(accept_terms: true, **answers)` (`POST /short_codes/application/submit`). `get`, `update` and `submit` return `Sendly::ShortCodeApplicationView` (`application` as `Sendly::ShortCodeApplication`, `documents` as `Sendly::ShortCodeDocument`, `editable?`, `lock_message`, and `prefill`, `quote`, `billing`, `verification`, `carriers` and `payment` as Hashes with snake_case Symbol keys); `check` returns `Sendly::ShortCodePreflight` (`ok?`, `issues` as `Sendly::ShortCodeIssue`, `missing_documents`). Answers take snake_case or camelCase keys. `update` and `submit` take `idempotency_key:`. Submitting charges the one-time $999 setup fee.
12
+ - **Idempotency keys on WhatsApp signup and template create.** `whatsapp.signup.create` (both the Facebook signup and adding a number by code) and `whatsapp.templates.create` take `idempotency_key:`, sent as the `Idempotency-Key` header; a repeat with the same key within 24 hours returns the first answer instead of starting another charged signup or creating the template again. Without it the client still generates one per call, as before.
13
+ - **`messages.schedule(timezone:)`.** Sends `timezone`, a label stored with the scheduled message and returned as sent (`"UTC"` when left out). It does not change how `scheduled_at` is read, so give `scheduled_at` an offset or `Z`.
14
+ - **`enterprise.upload_verification_document(content_type:)`.** The API accepts only PNG, JPEG, GIF, WEBP and PDF, and reads the type from the part's content type, which the SDK takes from the file's extension. Pass `content_type:` for a file without an extension or with a different one; a blank value or one with a line break raises `ArgumentError` before anything is sent.
15
+ - **`conversations.list(label:)`** keeps only conversations with that label id; `conversations.each(label:)` passes it on.
16
+ - **`enterprise.workspaces.list` takes the API's filters:** `limit:` (up to 100), `page:`, `search:`, `status:`, `verification:` (`"unverified"` keeps workspaces without one), `sort:` (`"created_desc"`, `"created_asc"`, `"name_asc"`, `"name_desc"`, `"credits_desc"` or `"credits_asc"`), `compact:` and `tags:` (an Array or String, sent comma-separated). Calling it with no arguments sends the same request as before.
17
+
18
+ ### Patch Changes
19
+
20
+ - `whatsapp.templates.update` documents how to remove parts of a template: `header: ""` or `footer: ""` removes the header or footer, and `buttons: []` removes every button. The SDK already sent these; only `nil` is left out.
21
+ - **`Webhook#metadata` is always a Hash.** The API returns a webhook's metadata as it was stored, which can be an array, string, number or boolean; `webhooks.list` and `webhooks.get` passed such a value through, so `metadata` (and `to_h[:metadata]`) could be something other than the documented Hash. It now reads as `{}`, as `null` already did.
22
+
3
23
  ## 4.5.0
4
24
 
5
25
  ### Patch Changes
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- sendly (4.5.1)
4
+ sendly (4.7.0)
5
5
  faraday (~> 2.0)
6
6
  faraday-retry (~> 2.0)
7
7
 
data/README.md CHANGED
@@ -184,6 +184,16 @@ scheduled = client.messages.schedule(
184
184
  puts scheduled["id"]
185
185
  puts scheduled["scheduledAt"]
186
186
 
187
+ # timezone is a label stored with the message and returned as sent ("UTC"
188
+ # when left out). It does not change how scheduled_at is read, so give
189
+ # scheduled_at an offset or Z.
190
+ client.messages.schedule(
191
+ to: "+15125550123",
192
+ text: "Doors open at 9!",
193
+ scheduled_at: "2026-11-20T09:00:00-05:00",
194
+ timezone: "America/New_York"
195
+ )
196
+
187
197
  # List scheduled messages (returns a Hash with "data" array)
188
198
  result = client.messages.list_scheduled
189
199
  result["data"].each { |msg| puts "#{msg['id']}: #{msg['scheduledAt']}" }
@@ -423,6 +433,10 @@ circuit is still open, so reset first:
423
433
  ```ruby
424
434
  client.webhooks.reset_circuit("whk_xxx")
425
435
 
436
+ # See what a recovery would send, without sending anything
437
+ preview = client.webhooks.recovery_preview("whk_xxx", since: (Time.now.utc - 86_400).iso8601)
438
+ puts preview.audit_failures[:total], preview.missing_from_messages[:total]
439
+
426
440
  # Re-fire deliveries we recorded but could not deliver
427
441
  client.webhooks.redeliver("whk_xxx",
428
442
  since: (Time.now.utc - 86_400).iso8601,
@@ -771,6 +785,10 @@ client.templates.publish(template.id)
771
785
  copy = client.templates.clone(template.id, name: "Order shipped (v2)")
772
786
  client.templates.delete(template.id)
773
787
 
788
+ # Render a template, or any preset, with values. Nothing is sent.
789
+ preview = client.templates.preview("tpl_preset_otp", variables: { code: "123456" })
790
+ puts "#{preview.rendered_text} (#{preview.segment_count} segments)"
791
+
774
792
  # Generate a template with AI
775
793
  generated = client.templates.generate(description: "A friendly appointment reminder")
776
794
  puts generated.text
@@ -784,6 +802,7 @@ Two-way messaging threads with your contacts.
784
802
  ```ruby
785
803
  # List conversations (Enumerable)
786
804
  conversations = client.conversations.list(status: "active")
805
+ vip = client.conversations.list(label: "lbl_xxx") # only conversations with this label id
787
806
  conversations.each { |c| puts "#{c.phone_number}: #{c.last_message_text}" }
788
807
 
789
808
  # Get one, optionally with its messages
@@ -1015,10 +1034,54 @@ client.ten_dlc.list_assignments[:assignments].each { |a| puts "#{a.phone_number}
1015
1034
 
1016
1035
  ## Short Codes
1017
1036
 
1018
- **This SDK has no short-code resource.** There is no `client.short_codes`;
1019
- short-code applications are handled in the dashboard, or over REST. What
1020
- the SDK does carry is the four lifecycle events, as constants you can
1021
- subscribe to and branch on:
1037
+ A short code is a 5 or 6 digit US sender. Getting one is an application,
1038
+ not a purchase: you fill it in, Sendly reviews it, the carrier forms are
1039
+ signed, Sendly files it, and each carrier certifies the code. Reads need
1040
+ the `short_codes:read` scope and writes `short_codes:write`.
1041
+
1042
+ ```ruby
1043
+ # Every application and code, newest first (drafts and rejected ones too)
1044
+ client.short_codes.list.select(&:active?).each { |code| puts code.short_code }
1045
+
1046
+ # The application, with the documents it needs, the quote and billing
1047
+ view = client.short_codes.application.get
1048
+ puts view.lock_message unless view.editable?
1049
+ puts view.quote[:setup_usd] # 999
1050
+ puts view.billing[:setup_fee][:status] # "unpaid"
1051
+
1052
+ # Save answers (snake_case or camelCase keys); the first save creates it
1053
+ client.short_codes.application.update(
1054
+ use_case: "Delivery alerts for Acme orders",
1055
+ message_frequency: "4 messages per month",
1056
+ sample_messages: ["Acme: your order shipped. Reply STOP to opt out."]
1057
+ )
1058
+
1059
+ # Check against the carrier rules without saving anything
1060
+ check = client.short_codes.application.check
1061
+ check.issues.each { |issue| puts "#{issue.path}: #{issue.message}" } unless check.ok?
1062
+
1063
+ # Submit: charges the one-time $999 setup fee to the card on file, and
1064
+ # accepts the monthly lease from go-live and the 3-month minimum
1065
+ result = client.short_codes.application.submit(
1066
+ accept_terms: true,
1067
+ idempotency_key: "short-code-submit-1"
1068
+ )
1069
+ puts result.application.review_status # "awaiting_review"
1070
+ puts result.payment # { status: "paid", charged: true }
1071
+ ```
1072
+
1073
+ `update` and `submit` accept `idempotency_key:`; a repeat with the same key
1074
+ returns the first answer. Submitting twice is safe anyway: the second call
1075
+ reports `already_submitted?` and charges nothing. Nested values (`prefill`,
1076
+ `quote`, `billing`, `verification`, `carriers`, `payment`) are Hashes with
1077
+ snake_case Symbol keys. Submit raises `Sendly::APIError` 403
1078
+ `verification_required` until the business is verified,
1079
+ `Sendly::ValidationError` 422 `short_code_invalid_application` naming every
1080
+ field, and `Sendly::InsufficientCreditsError` 402 when the fee can't be
1081
+ charged (`e.response_body["checkoutUrl"]` is the payment page when the bank
1082
+ needs to confirm it).
1083
+
1084
+ The four lifecycle events are constants you can subscribe to and branch on:
1022
1085
 
1023
1086
  ```ruby
1024
1087
  client.webhooks.create(
@@ -1044,33 +1107,6 @@ These are lifecycle events, so `event.message` is `nil` and you read
1044
1107
  `data.object` through `event.data` or `event.raw_object`, as with every
1045
1108
  other non-message event.
1046
1109
 
1047
- To drive an application from code meanwhile, call the REST endpoints
1048
- directly with an API key holding the `short_codes:read` /
1049
- `short_codes:write` scopes:
1050
-
1051
- | Method | Path | Scope |
1052
- |--------|------|-------|
1053
- | `GET` | `/api/v1/short_codes` | `short_codes:read` |
1054
- | `POST` | `/api/v1/short_codes/requests` | `short_codes:write` |
1055
- | `GET` | `/api/v1/short_codes/application` | `short_codes:read` |
1056
- | `PUT` | `/api/v1/short_codes/application` | `short_codes:write` |
1057
- | `POST` | `/api/v1/short_codes/application/preflight` | `short_codes:read` |
1058
- | `POST` | `/api/v1/short_codes/application/submit` | `short_codes:write` |
1059
-
1060
- The client's own HTTP
1061
- methods reach them without a dedicated resource — paths are relative to the
1062
- `/api/v1` base:
1063
-
1064
- ```ruby
1065
- application = client.get("/short_codes/application")
1066
- ```
1067
-
1068
- The write endpoints take the application form's fields as their body. This
1069
- SDK does not model them, so check the API reference for the shape rather
1070
- than guessing: `client.put` and `client.post` pass a Hash through as JSON
1071
- unchanged (`client.delete` takes no body), and every `client.post` carries an
1072
- `Idempotency-Key` as usual.
1073
-
1074
1110
  ## Business Entity Upgrade
1075
1111
 
1076
1112
  `client.business_upgrade` runs the toll-free entity upgrade: when you form
@@ -1193,8 +1229,10 @@ gives its slot back. Note: Meta
1193
1229
  has paused marketing template delivery to US (+1) numbers.
1194
1230
 
1195
1231
  ```ruby
1196
- # 1. Connect a number ($9.99 one-time; a human must open the connect URL)
1197
- signup = client.whatsapp.signup.create(phone_number: "+15125550123")
1232
+ # 1. Connect a number ($9.99 one-time; a human must open the connect URL).
1233
+ # Pass idempotency_key: so a repeat after a restart returns the same signup.
1234
+ signup = client.whatsapp.signup.create(phone_number: "+15125550123",
1235
+ idempotency_key: "connect-+15125550123")
1198
1236
  puts "Have your user open: #{signup.connect_url}"
1199
1237
 
1200
1238
  # 2. Poll until active. After the Facebook step the signup is "registering"
@@ -1275,7 +1313,8 @@ template = client.whatsapp.templates.create(
1275
1313
  category: "UTILITY",
1276
1314
  header: "Order update", # fixed text only: a header with {{n}} is refused
1277
1315
  body: "Hi {{1}}, your order {{2}} has shipped!",
1278
- examples: { "1" => "Sam", "2" => "#4821" }
1316
+ examples: { "1" => "Sam", "2" => "#4821" },
1317
+ idempotency_key: "tpl-order-shipped" # optional: a repeat returns the first answer
1279
1318
  )
1280
1319
  puts template.status # "PENDING"
1281
1320
 
@@ -1283,6 +1322,8 @@ puts template.status # "PENDING"
1283
1322
  client.whatsapp.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
1284
1323
  client.whatsapp.templates.update(template.id, body: "Hi {{1}}, order {{2}} is on its way!",
1285
1324
  examples: { "1" => "Sam", "2" => "#4821" })
1325
+ # "" removes the header or footer, [] removes every button
1326
+ client.whatsapp.templates.update(template.id, footer: "", buttons: [])
1286
1327
  client.whatsapp.templates.delete(template.id)
1287
1328
 
1288
1329
  # 4. Send — free-form inside an open 24h window, template anytime. The window
@@ -1660,7 +1701,7 @@ client.messages.send(
1660
1701
  ## Voice Calls
1661
1702
 
1662
1703
  Place phone calls that one of your AI agents handles, list and inspect
1663
- calls, end a call early, and download recordings. Agents are created with
1704
+ calls, transfer a caller, end a call early, and download recordings. Agents are created with
1664
1705
  `client.voice.agents` or in the dashboard under Calls, then Agents; the
1665
1706
  number you call from must have voice switched on and an emergency address
1666
1707
  registered before it can place outbound calls (see
@@ -1676,8 +1717,8 @@ from = client.numbers.list[:numbers].find(&:voice_enabled?)&.phone_number
1676
1717
  Calls are prepaid from your credit balance per started minute: 2 credits a
1677
1718
  minute outbound, plus 8 a minute while an AI agent is on the call (10 in
1678
1719
  total for an API-placed call). Unanswered calls cost nothing. Destinations
1679
- are US and Canadian numbers. Reads need the `calls:read` scope; `create`
1680
- and `hangup` need `calls:write` and a live key.
1720
+ are US and Canadian numbers. Reads need the `calls:read` scope; `create`,
1721
+ `transfer` and `hangup` need `calls:write` and a live key.
1681
1722
 
1682
1723
  > **Rolling out.** Voice is enabled workspace by workspace. Until it is on
1683
1724
  > for yours, every `client.calls` and `client.voice` method raises
@@ -1710,6 +1751,15 @@ page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits"
1710
1751
  puts page.total
1711
1752
  puts page.has_more?
1712
1753
 
1754
+ # Only calls answered by one kind of agent (Sendly::Call::AGENT_KINDS)
1755
+ client.calls.list(agent_kind: "websocket")
1756
+
1757
+ # Transfer the caller on an incoming phone call. Without `to:`, the agent's
1758
+ # transfer number (tools.transfer_to) is used.
1759
+ incoming = client.calls.list(direction: "inbound", status: "active").first
1760
+ incoming = client.calls.transfer(incoming.id, to: "+15125550142")
1761
+ puts incoming.transfer.status # "pending", then "completed" or "failed"
1762
+
1713
1763
  # End a call. Ringing -> "cancelled", active -> "completed"; a call that
1714
1764
  # has already ended comes back unchanged.
1715
1765
  client.calls.hangup(call.id)
@@ -1736,9 +1786,26 @@ number), 409 for `agent_disabled`, `no_voice_number` and `lines_busy` (retry
1736
1786
  shortly), or 403 for `live_key_required` and a key missing the scope; and
1737
1787
  `Sendly::ServerError` (a sibling of `APIError`, not a subclass) for 503
1738
1788
  `voice_unavailable` / `agents_unavailable` and 500 `voice_internal_error`.
1739
- The full list is `Sendly::Call::ERROR_CODES`; the hangup vocabulary is
1789
+ `create` also answers 409 `agent_kind_unsupported` when the agent's `kind`
1790
+ is `"sip"` or `"websocket"`, which answer incoming calls only. The full list
1791
+ is `Sendly::Call::ERROR_CODES`; the hangup vocabulary is
1740
1792
  `Sendly::Call::HANGUP_CLASSES`.
1741
1793
 
1794
+ Each call carries `agent_kind` (the kind of agent that answered, or nil),
1795
+ `agent_fallback?` (true when your own agent could not be reached, so Sendly
1796
+ said a short line and transferred the caller or took a message) and
1797
+ `transfer` (nil, or a `Sendly::CallTransfer` with `to`, `status` and
1798
+ `failure_reason`). A transfer answers at once with `transfer.status`
1799
+ `"pending"`; once the caller is handed over the call ends `"completed"` with
1800
+ `hangup_class` `"transferred"`, and a failed transfer leaves the caller on
1801
+ the call. Transfer refusals: `Sendly::ValidationError` for
1802
+ `invalid_request` and `transfer_to_required` (no `to:` and the agent has no
1803
+ transfer number), `Sendly::InsufficientCreditsError` when no credits are
1804
+ left, and `Sendly::APIError` with `status_code` 403 for
1805
+ `outbound_not_enabled` (a number other than the agent's needs calling out
1806
+ switched on) or 409 for `call_not_active`, `call_not_transferable` (not an
1807
+ incoming phone call) and `transfer_in_progress`.
1808
+
1742
1809
  `call.channel` is where the call took place: `"phone"`, `"whatsapp"` (a
1743
1810
  WhatsApp call, for example one placed from the dashboard) or `"browser"`
1744
1811
  (`Sendly::Call::CHANNELS`); a value this SDK predates comes through unchanged.
@@ -1831,6 +1898,77 @@ contact support. When it says the address couldn't be registered or
1831
1898
  emergency calling couldn't be switched on, try again later. Every API error
1832
1899
  keeps the parsed body on `e.response_body`.
1833
1900
 
1901
+ ### Bring your own agent
1902
+
1903
+ An agent's `kind` says who writes the replies: `"sendly"` (the default,
1904
+ from the agent's `instructions`), `"custom_llm"` (Sendly listens and speaks,
1905
+ and your chat completions endpoint writes each reply), `"sip"` (Sendly
1906
+ connects the caller to your SIP address) or `"websocket"` (Sendly streams
1907
+ the call audio to your `wss://` server). Your own agents need the
1908
+ workspace's bring-your-own-agent feature, which support switches on
1909
+ (`Sendly::APIError` 403 `byo_agents_not_enabled` otherwise).
1910
+
1911
+ ```ruby
1912
+ agent = client.voice.agents.create(
1913
+ name: "Support line",
1914
+ kind: "websocket",
1915
+ connection: { url: "wss://agent.example.com/calls", auth_token: "tok_123" }
1916
+ )
1917
+ secret = agent.signing_secret # save it now; it is never shown again
1918
+ puts agent.connection.url, agent.connection.has_auth_token, agent.has_signing_secret?
1919
+
1920
+ # Same kind: the connection is merged, so only what you pass changes
1921
+ client.voice.agents.update(agent.id, connection: { custom_parameters: { "tenant" => "acme" } })
1922
+
1923
+ # A new signing secret; the old one stops working at once
1924
+ secret = client.voice.agents.update(agent.id, rotate_signing_secret: true).signing_secret
1925
+ ```
1926
+
1927
+ `connection:` takes snake_case or camelCase keys: `base_url`, `model`,
1928
+ `api_key` and `headers` for `"custom_llm"`; `uri`, `transport`,
1929
+ `media_encryption`, `username`, `password` and `headers` for `"sip"`; `url`,
1930
+ `audio_format`, `auth_token` and `custom_parameters` for `"websocket"`. A
1931
+ secret you leave out keeps its saved value and `nil` removes it. Secrets are
1932
+ never returned: `agent.connection` (a `Sendly::VoiceAgentConnection`) reports
1933
+ `has_api_key`, `has_password` or `has_auth_token` instead. Sendly signs every
1934
+ request to your agent with the signing secret
1935
+ (`X-Sendly-Signature: t=<unix>,v1=<hex HMAC-SHA256>`); `signing_secret` is
1936
+ set only on the create or update response that made it. A connection that
1937
+ breaks a rule raises `Sendly::ValidationError` with a message like
1938
+ `connection.url: <reason>`.
1939
+
1940
+ #### Test an agent's connection
1941
+
1942
+ `client.voice.agents.test` reaches your own agent the way a call would,
1943
+ without placing one: `"custom_llm"` gets a signed, streamed chat completion
1944
+ with a test message, `"websocket"` gets a signed connection with a `start`
1945
+ carrying `test: true`, half a second of silence and a `stop`, and `"sip"` gets
1946
+ an `OPTIONS` request. Pass `kind:`, `connection:` or `instructions:` to test
1947
+ settings before saving them; nothing is saved.
1948
+
1949
+ ```ruby
1950
+ result = client.voice.agents.test(agent.id)
1951
+ puts "#{result.outcome}: #{result.message}" unless result.ok?
1952
+ result.steps.each { |step| puts "#{step.step} #{step.ok?} #{step.detail}" }
1953
+
1954
+ # Try a new SIP address before saving it
1955
+ client.voice.agents.test(
1956
+ agent.id,
1957
+ kind: "sip",
1958
+ connection: { uri: "sip:+15125550100@sip.example.com", transport: "tls" }
1959
+ )
1960
+ ```
1961
+
1962
+ A failed test is still a successful request, so check `ok?`. `outcome` is one
1963
+ of `Sendly::VoiceAgentTest::OUTCOMES` (`ok`, `blocked_destination`,
1964
+ `unreachable`, `timeout`, `tls_failed`, `auth_required`, `auth_failed`,
1965
+ `not_found`, `rejected`, `bad_reply`), and each step one of
1966
+ `Sendly::VoiceAgentTestStep::STEPS` (`address`, `connect`, `login`, `reply`);
1967
+ a value this SDK predates comes through unchanged. The result also carries
1968
+ `status` (the HTTP or SIP status, or `nil`), `latency_ms` and `signed?`. It
1969
+ needs the `calls:write` scope and a live key, sends no Idempotency-Key, and a
1970
+ workspace can run 10 tests a minute (`Sendly::RateLimitError` after that).
1971
+
1834
1972
  ## Error Handling
1835
1973
 
1836
1974
  ```ruby
@@ -2057,6 +2195,10 @@ Three provisioning modes:
2057
2195
  ```ruby
2058
2196
  ws = client.enterprise.workspaces.create(name: "Acme Insurance")
2059
2197
  list = client.enterprise.workspaces.list
2198
+ # Filters: limit (up to 100), page, search, status, verification ("unverified"),
2199
+ # sort ("created_desc", "name_asc", "credits_desc", ...), compact, tags
2200
+ unverified = client.enterprise.workspaces.list(verification: "unverified", sort: "name_asc",
2201
+ tags: ["tag_vip"], limit: 100)
2060
2202
  detail = client.enterprise.workspaces.get("ws_xxx")
2061
2203
  client.enterprise.workspaces.delete("ws_xxx")
2062
2204
  ```
@@ -2109,6 +2251,8 @@ client.enterprise.workspaces.inherit_verification("ws_other", source_workspace_i
2109
2251
  purchase_new_number: true)
2110
2252
  client.enterprise.workspaces.get_verification("ws_xxx")
2111
2253
  client.enterprise.upload_verification_document("./CP-575.pdf", workspace_id: "ws_xxx")
2254
+ # The type comes from the extension; pass content_type: for a file without one
2255
+ client.enterprise.upload_verification_document("./ein-letter", content_type: "application/pdf")
2112
2256
 
2113
2257
  # Hosted opt-in pages, and a generated business page
2114
2258
  client.enterprise.workspaces.list_opt_in_pages("ws_xxx")
@@ -20,6 +20,43 @@ module Sendly
20
20
  end
21
21
  end
22
22
 
23
+ # The latest transfer on a call. +to+ is the E.164 number the caller is
24
+ # transferred to. +status+ is "pending" while that number rings,
25
+ # "completed" once the caller was handed over and "failed" when the
26
+ # transfer did not go through and the caller is still on the call (see
27
+ # {STATUSES}). +failure_reason+ is +nil+ unless +status+ is "failed", then
28
+ # one of {FAILURE_REASONS} ("unknown" when no definite answer came back).
29
+ # A value this SDK predates comes through unchanged.
30
+ class CallTransfer
31
+ STATUSES = %w[pending completed failed].freeze
32
+ FAILURE_REASONS = %w[busy no_answer declined unavailable unknown].freeze
33
+
34
+ attr_reader :to, :status, :failure_reason
35
+
36
+ def initialize(data)
37
+ data ||= {}
38
+ @to = data["to"]
39
+ @status = data["status"]
40
+ @failure_reason = data["failureReason"] || data["failure_reason"]
41
+ end
42
+
43
+ def pending?
44
+ status == "pending"
45
+ end
46
+
47
+ def completed?
48
+ status == "completed"
49
+ end
50
+
51
+ def failed?
52
+ status == "failed"
53
+ end
54
+
55
+ def to_h
56
+ { to: to, status: status, failure_reason: failure_reason }.compact
57
+ end
58
+ end
59
+
23
60
  # A phone call placed or received by one of your workspace's numbers.
24
61
  #
25
62
  # +kind+ is "pstn" for a phone call and "internal" for a browser-to-browser
@@ -37,9 +74,15 @@ module Sendly
37
74
  # phone call is charged per started minute, "settled" once it has ended,
38
75
  # and "unbilled" for calls that are never charged. +hangup_class+ says why
39
76
  # the call ended (see {HANGUP_CLASSES}); anything unrecognised arrives as
40
- # "ended". +metadata+ is the string map attached on create (+{}+ when
41
- # none). +transcript+ is only present on {CallsResource#get} for
42
- # agent-handled calls and is +nil+ otherwise.
77
+ # "ended". +agent_kind+ is the kind of agent that answered ("sendly",
78
+ # "custom_llm", "sip" or "websocket", see {AGENT_KINDS}), or +nil+ when no
79
+ # agent handled the call. +agent_fallback+ is true when your own agent
80
+ # could not be reached (or dropped), so Sendly said a short line and
81
+ # transferred the caller or took a message. +transfer+ is the latest
82
+ # {CallTransfer}, or +nil+ when the call was never transferred.
83
+ # +metadata+ is the string map attached on create (+{}+ when none).
84
+ # +transcript+ is only present on {CallsResource#get} for agent-handled
85
+ # calls and is +nil+ otherwise.
43
86
  class Call
44
87
  STATUSES = %w[ringing active completed no_answer busy cancelled declined failed suspended].freeze
45
88
  LIVE_STATUSES = %w[ringing active].freeze
@@ -49,6 +92,7 @@ module Sendly
49
92
  HANDLED_BY = %w[agent dashboard].freeze
50
93
  BILLING_STATES = %w[metered settled unbilled].freeze
51
94
  RECORDING_STATUSES = %w[recording ready failed].freeze
95
+ AGENT_KINDS = %w[sendly custom_llm sip websocket].freeze
52
96
  HANGUP_CLASSES = %w[
53
97
  normal caller_hung_up callee_hung_up caller_left peer_left agent_ended
54
98
  agent_agent_hangup agent_caller_left
@@ -57,6 +101,7 @@ module Sendly
57
101
  max_duration credits_exhausted media_aborted peer_connection_lost room_closed agent_left
58
102
  transferred voicemail voicemail_unavailable
59
103
  setup_failed agent_dispatch_failed agent_api_unreachable agent_already_ended
104
+ agent_remote_hangup agent_byo_failed
60
105
  ended
61
106
  ].freeze
62
107
  ERROR_CODES = %w[
@@ -67,13 +112,16 @@ module Sendly
67
112
  insufficient_credits invalid_number rate_limit_exceeded forbidden
68
113
  invalid_request insufficient_permissions agent_in_use agent_limit invalid_voice_mode
69
114
  invalid_address e911_not_applicable voice_attach_failed carrier_refused
70
- from_number_not_supported
115
+ from_number_not_supported byo_agents_not_enabled agent_kind_unsupported
116
+ transfer_to_required outbound_not_enabled call_not_active call_not_transferable
117
+ transfer_in_progress
71
118
  ].freeze
72
119
 
73
120
  attr_reader :id, :object, :kind, :direction, :status, :handled_by, :agent_id,
74
121
  :from, :to, :caller_name, :callee_name, :started_at, :answered_at,
75
122
  :ended_at, :duration_secs, :credits_charged, :billing, :hangup_class,
76
- :recording_status, :metadata, :transcript, :channel
123
+ :recording_status, :metadata, :transcript, :channel, :agent_kind,
124
+ :agent_fallback, :transfer
77
125
 
78
126
  # @return [Hash] The raw parsed response
79
127
  attr_reader :raw
@@ -101,6 +149,10 @@ module Sendly
101
149
  @billing = data["billing"]
102
150
  @hangup_class = data["hangupClass"] || data["hangup_class"]
103
151
  @recording_status = data["recordingStatus"] || data["recording_status"]
152
+ @agent_kind = data["agentKind"] || data["agent_kind"]
153
+ @agent_fallback = data.key?("agentFallback") ? data["agentFallback"] : data["agent_fallback"]
154
+ transfer = data["transfer"]
155
+ @transfer = transfer.is_a?(Hash) ? CallTransfer.new(transfer) : nil
104
156
  @metadata = data["metadata"] || {}
105
157
  lines = data["transcript"]
106
158
  @transcript = lines.is_a?(Array) ? lines.map { |l| CallTranscriptLine.new(l) } : nil
@@ -132,6 +184,12 @@ module Sendly
132
184
  direction == "outbound"
133
185
  end
134
186
 
187
+ # @return [Boolean] Whether your own agent could not be reached, so
188
+ # Sendly said a short line and transferred the caller or took a message
189
+ def agent_fallback?
190
+ agent_fallback == true
191
+ end
192
+
135
193
  def to_h
136
194
  {
137
195
  id: id, object: object, kind: kind, channel: channel, direction: direction, status: status,
@@ -139,7 +197,8 @@ module Sendly
139
197
  caller_name: caller_name, callee_name: callee_name, started_at: started_at,
140
198
  answered_at: answered_at, ended_at: ended_at, duration_secs: duration_secs,
141
199
  credits_charged: credits_charged, billing: billing, hangup_class: hangup_class,
142
- recording_status: recording_status, metadata: metadata,
200
+ recording_status: recording_status, agent_kind: agent_kind,
201
+ agent_fallback: agent_fallback, transfer: transfer&.to_h, metadata: metadata,
143
202
  transcript: transcript&.map(&:to_h)
144
203
  }.compact
145
204
  end
@@ -222,7 +281,7 @@ module Sendly
222
281
  end
223
282
 
224
283
  # Calls resource: place phone calls handled by your AI agents, list and
225
- # inspect calls, end a call and fetch recordings.
284
+ # inspect calls, transfer a caller, end a call and fetch recordings.
226
285
  #
227
286
  # A call placed over the API is answered by one of your AI agents
228
287
  # (create them with {VoiceAgentsResource#create} or in the dashboard
@@ -240,12 +299,14 @@ module Sendly
240
299
  # +voice_not_enabled+, +outbound_calls_not_enabled+, +agent_not_found+,
241
300
  # +number_not_found+ and +call_not_found+; {Sendly::ValidationError} for
242
301
  # +invalid_number+, +destination_not_supported+, +agent_required+,
243
- # +invalid_metadata+, +from_number_required+ and
244
- # +from_number_not_supported+; {Sendly::InsufficientCreditsError} for
302
+ # +invalid_metadata+, +from_number_required+, +from_number_not_supported+
303
+ # and +transfer_to_required+; {Sendly::InsufficientCreditsError} for
245
304
  # +insufficient_credits+; {Sendly::RateLimitError} for +daily_call_limit+ and
246
305
  # +rate_limit_exceeded+; {Sendly::APIError} with the HTTP status for
247
306
  # +e911_required+ (428), +agent_disabled+ / +no_voice_number+ /
248
- # +lines_busy+ (409) and +live_key_required+ / +forbidden+ (403); and
307
+ # +lines_busy+ / +agent_kind_unsupported+ / +call_not_active+ /
308
+ # +call_not_transferable+ / +transfer_in_progress+ (409) and
309
+ # +live_key_required+ / +forbidden+ / +outbound_not_enabled+ (403); and
249
310
  # {Sendly::ServerError} (not an +APIError+) for +voice_unavailable+ /
250
311
  # +agents_unavailable+ (503) and +voice_internal_error+ (500). The full
251
312
  # list is {Call::ERROR_CODES}.
@@ -295,7 +356,9 @@ module Sendly
295
356
  # @raise [Sendly::APIError] HTTP 428 +e911_required+ (register an
296
357
  # emergency address for the number first with
297
358
  # {VoiceNumbersResource#register_emergency_address}), 409 +agent_disabled+ /
298
- # +no_voice_number+ / +lines_busy+, 403 +live_key_required+
359
+ # +no_voice_number+ / +lines_busy+ / +agent_kind_unsupported+ (the
360
+ # agent's +kind+ is "sip" or "websocket", which answer incoming calls
361
+ # only; "custom_llm" agents can place calls), 403 +live_key_required+
299
362
  # @raise [Sendly::RateLimitError] HTTP 429 +daily_call_limit+ / +rate_limit_exceeded+
300
363
  # @raise [Sendly::ServerError] HTTP 503 +voice_unavailable+ /
301
364
  # +agents_unavailable+ (calling is not switched on for this deployment),
@@ -332,6 +395,9 @@ module Sendly
332
395
  # @param direction [String, nil] "inbound" or "outbound"
333
396
  # @param kind [String, nil] "pstn" or "internal"
334
397
  # @param agent_id [String, nil] Only calls handled by this agent
398
+ # @param agent_kind [String, nil] Only calls answered by this kind of
399
+ # agent, one of {Call::AGENT_KINDS}. Calls from before agent kinds
400
+ # existed count as "sendly".
335
401
  # @param to [String, nil] Exact E.164 match on the called number
336
402
  # @param from [String, nil] Exact E.164 match on the calling number
337
403
  # @return [Sendly::CallList] The page and its pagination
@@ -343,7 +409,7 @@ module Sendly
343
409
  # page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits" }
344
410
  # puts page.has_more?
345
411
  def list(limit: nil, offset: nil, status: nil, direction: nil, kind: nil,
346
- agent_id: nil, to: nil, from: nil)
412
+ agent_id: nil, agent_kind: nil, to: nil, from: nil)
347
413
  params = {}
348
414
  params[:limit] = limit unless limit.nil?
349
415
  params[:offset] = offset unless offset.nil?
@@ -351,6 +417,7 @@ module Sendly
351
417
  params[:direction] = direction unless direction.nil?
352
418
  params[:kind] = kind unless kind.nil?
353
419
  params[:agentId] = agent_id unless agent_id.nil?
420
+ params[:agentKind] = agent_kind unless agent_kind.nil?
354
421
  params[:to] = to unless to.nil?
355
422
  params[:from] = from unless from.nil?
356
423
 
@@ -395,6 +462,49 @@ module Sendly
395
462
  Call.new(response)
396
463
  end
397
464
 
465
+ # Transfer the caller on an incoming phone call to another number,
466
+ # whatever kind of agent is on the call. Returns at once with
467
+ # +transfer.status+ "pending"; the outcome shows on {#get}
468
+ # (+transfer.status+) and, once the caller is handed over, the call ends
469
+ # +completed+ with +hangup_class+ "transferred" (also in the
470
+ # +call.completed+ webhook). A failed transfer leaves the caller on the
471
+ # call. Requires the +calls:write+ scope and a live key.
472
+ #
473
+ # @param id [String] Call identifier
474
+ # @param to [String, nil] The number to transfer the caller to, in E.164
475
+ # format: US or Canadian, not premium-rate, not the number the caller
476
+ # dialled and not a number the agent answers. Left out (not sent), the
477
+ # agent's transfer number (+tools.transfer_to+) is used. Any other
478
+ # number needs calling out switched on for the workspace.
479
+ # @param idempotency_key [String, nil] Idempotency key for this operation
480
+ # @return [Sendly::Call] The call, with +transfer.status+ "pending"
481
+ # @raise [Sendly::ValidationError] If +id+ is missing, or HTTP 400
482
+ # +invalid_request+ (+to+ is malformed, outside the US and Canada,
483
+ # premium-rate, the dialled number or a number the agent answers) or
484
+ # +transfer_to_required+ (no +to+ and the agent has no transfer number)
485
+ # @raise [Sendly::InsufficientCreditsError] HTTP 402 when the workspace
486
+ # has no credits left
487
+ # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+
488
+ # @raise [Sendly::APIError] HTTP 403 +outbound_not_enabled+ (+to+ is not
489
+ # the agent's transfer number and calling out is not switched on), 409
490
+ # +call_not_active+ (the call is not in progress) /
491
+ # +call_not_transferable+ (not an incoming phone call) /
492
+ # +transfer_in_progress+ (a transfer is already under way, or the call
493
+ # has had 3 transfer attempts)
494
+ # @raise [Sendly::ServerError] HTTP 500 +voice_internal_error+
495
+ #
496
+ # @example
497
+ # call = client.calls.transfer(call.id, to: "+15555550142")
498
+ # puts call.transfer.status # "pending"
499
+ def transfer(id, to: nil, idempotency_key: nil)
500
+ encoded_id = encode_id!(id)
501
+ body = {}
502
+ body[:to] = to unless to.nil?
503
+
504
+ response = @client.post("/calls/#{encoded_id}/transfer", body, idempotency_key: idempotency_key)
505
+ Call.new(response)
506
+ end
507
+
398
508
  # Fetch the recording of a call. +url+ is a signed link valid for five
399
509
  # minutes and is only set once the recording is +ready?+; fetch again
400
510
  # for a fresh link. Requires the +calls:read+ scope.
data/lib/sendly/client.rb CHANGED
@@ -192,6 +192,17 @@ module Sendly
192
192
  @rcs ||= RcsResource.new(self)
193
193
  end
194
194
 
195
+ # Access the Short Codes resource (apply for a US short code and track it)
196
+ #
197
+ # @return [Sendly::ShortCodesResource]
198
+ #
199
+ # @example
200
+ # view = client.short_codes.application.get
201
+ # client.short_codes.application.submit(accept_terms: true)
202
+ def short_codes
203
+ @short_codes ||= ShortCodesResource.new(self)
204
+ end
205
+
195
206
  # Access the Calls resource (phone calls handled by your AI agents)
196
207
  #
197
208
  # @return [Sendly::CallsResource]