sendly 3.40.0__tar.gz → 4.1.0__tar.gz

{sendly-3.40.0 → sendly-4.1.0}/CHANGELOG.md

@@ -1,5 +1,170 @@
 # sendly (Python)
 
+## 4.1.0
+
+### Minor Changes
+
+- **Voice calls: `client.calls`.** `create(to, agent_id, from_=..., context=..., metadata=...)` places a phone call that one of your workspace's AI agents handles; `list(...)`, `get(id)`, `hangup(id)` and `recording(id)` follow it, end it early and fetch the recording. Sync and async clients. Reads need the `calls:read` scope, writes `calls:write` and a live API key; until voice is enabled for your workspace the routes answer 404 `voice_not_enabled`.
+- `voice_enabled` and `voice_mode` on owned numbers.
+
+### Patch Changes
+
+- `MessageStatus` gains `RECEIVED` and `UNDELIVERED`. `messages.list()` returns inbound rows by default and their status is `received`, which the strict enum rejected, so listing failed for any workspace with inbound traffic. Any status this version does not know now maps to `MessageStatus.UNKNOWN` instead of raising.
+
+## 4.0.0
+
+**Upgrading from 3.40.0:** that release already contained the breaking changes below, published by mistake as a minor version. 4.0.0 carries them under the correct major. Relative to 3.40.0, the only new changes are under **Security**.
+
+Webhook events are no longer decoded as messages. Every SDK used to force a webhook's
+`data.object` into a message-shaped type. That is correct for `message.*` and wrong for
+every lifecycle event — `rcs_*`, `whatsapp_*`, `call.*`, `brand.*`, `campaign.*`,
+`assignment.*`, `number.*`, `port*`, `contact*`, `conversation.*`, `draft.*`,
+`verification.*` — which carry a different object entirely. This release exposes the payload
+as it arrived and makes the wrong read fail instead of returning a plausible-looking zero.
+
+### Breaking Changes
+
+- **`event.data` is now `None` for every event that is not a `message.*` event.** It used to
+  be a fully-populated `WebhookMessageData` whatever arrived, assembled by reading message
+  field names off a payload that never carried them. Parsing an `rcs_agent.live` event
+  returned `id=''`, `status=''`, `to=''`, `from_=''`, `segments=1`, `credits_used=0`,
+  `direction='outbound'` — every one of those invented by the SDK — and **raised no error**.
+  A handler that logged `event.data.credits_used` recorded a `0` that meant nothing, and a
+  handler that branched on `event.data.status` took the empty-string branch forever.
+
+  Reading a message field off a lifecycle event now raises
+  `AttributeError: 'NoneType' object has no attribute 'id'`. **That is the point of this
+  release, not an accident.** The read was always wrong; it is now loud instead of silent,
+  so you find every affected call site the first time such an event arrives rather than
+  trusting a zero indefinitely.
+
+  Your code today, on any non-`message.*` event:
+
+  ```python
+  event = Webhooks.parse_event(payload, signature, WEBHOOK_SECRET, timestamp=timestamp)
+
+  if event.type == 'rcs_agent.live':
+      agent_id = event.data.id        # was always '' - the payload has no `id` at all
+      stage = event.data.status       # was always ''
+  ```
+
+  After upgrading, that raises. Read the payload off `event.object`, which carries
+  `data.object` verbatim:
+
+  ```python
+  event = Webhooks.parse_event(payload, signature, WEBHOOK_SECRET, timestamp=timestamp)
+
+  if event.type == 'rcs_agent.live':
+      agent_id = event.object['agent_id']
+      stage = event.object['stage']
+  ```
+
+  The edit is mechanical: on a lifecycle event, every `event.data.<field>` becomes
+  `event.object['<key>']`, with the key spelled the way the API sends it rather than the way
+  `WebhookMessageData` spelled it. There was no `event.object` before this release, so no
+  correct version of this code existed to migrate from — check what your handler assumed
+  rather than translating it field for field.
+
+  If a handler touches `event.data` in several branches, guard the message-only path once.
+  `if event.data is not None:` both narrows the type for a checker and marks the branch:
+
+  ```python
+  if event.data is not None:
+      record_delivery(event.data.id, event.data.status)
+  else:
+      handle_lifecycle(event.type, event.object)
+  ```
+
+  `message.*` handlers otherwise need no change: `event.data` is still the message view
+  there.
+
+- **`contact.auto_flagged` reported the wrong id, and code keyed on it acted on the wrong
+  record.** The payload is a contact — `{id, phone_number, invalid_reason, source,
+  message_id, error_code}` — so the old decode put the *contact* id in `event.data.id`, and
+  `event.data.message_id` (an alias for `id`) returned that same contact id. The message
+  that actually failed was unreachable. If you wrote `mark_bounced(event.data.id)`, it has
+  been handing a contact id to something that expects a message id:
+
+  ```python
+  # before - `event.data.id` is the CONTACT id, `event.data.message_id` is the same value
+  if event.type == 'contact.auto_flagged':
+      mark_bounced(event.data.id)
+
+  # after - the two ids are distinct and never swapped
+  if event.type == 'contact.auto_flagged':
+      flag_contact(event.object['id'])
+      mark_bounced(event.object['message_id'])
+  ```
+
+  Audit anything this handler wrote before you upgrade; the bad writes are already on disk.
+
+- **`message.opt_in` and `message.opt_out` also return `event.data is None`.** They share the
+  `message.` prefix but carry an opt-out record (`phone_number`, `keyword`, `from_number`,
+  `timestamp`), not a message, so the old decode produced an all-default message here too.
+  Read them from `event.object`. Use `is_message_event(event.type)` rather than testing the
+  prefix yourself — it knows about these two.
+
+- **`WebhookEventType` is an enum, not a `Literal` union.** `sendly.webhooks` used to define
+  its own `Literal[...]` of event-type strings, drifting from the `WebhookEventType` enum in
+  `sendly.types`. There is now one definition: `sendly.webhooks.WebhookEventType` re-exports
+  the enum, and `sendly.webhooks.WEBHOOK_EVENT_TYPES` is the tuple of its values. Runtime
+  comparisons are unaffected (it is a `str` enum, so `event.type == 'message.delivered'` and
+  `event.type == WebhookEventType.MESSAGE_DELIVERED` are both `True`), but an annotation like
+  `event_type: WebhookEventType = 'message.delivered'` no longer type-checks. Use
+  `WebhookEventType.MESSAGE_DELIVERED`, or annotate as `str`.
+
+- **`message.queued` and `message.undelivered` are gone.** The API has never emitted either
+  one and rejects both with a `400` on subscribe, so any `events` list containing them was
+  subscribing to nothing and any handler branch on them was dead. They are no longer in
+  `WebhookEventType` or `WEBHOOK_EVENT_TYPES`; `WebhookEventType.MESSAGE_QUEUED` now raises
+  `AttributeError`. Delete them from your `webhooks.create()` / `webhooks.update()` calls.
+  `'queued'` and `'undelivered'` are still valid message *statuses* on `event.data.status` —
+  only the event types were removed.
+
+- **`WebhookMessageData` fields no longer carry invented defaults.** Every field is now
+  `Optional` and defaults to `None`. On a `message.*` payload that omitted a key you used to
+  get `''` for `id` / `status` / `to` / `from_`, `1` for `segments`, `0` for `credits_used`
+  and `'outbound'` for `direction`; you now get `None`, so an absent value is
+  distinguishable from a real one. Code that did `if not event.data.to:` still works; code
+  that did `event.data.to.startswith('+')` or `event.data.segments + 1` unguarded will now
+  raise on a sparse payload. `WebhookVerificationData` lost its invented defaults the same
+  way (`delivery_status='queued'`, `attempts=0`, `max_attempts=3` are all `None` now).
+
+### Minor Changes
+
+- **`event.object`** — `data.object` exactly as it arrived, on every event type. Keys are
+  verbatim (`camelCase` stays `camelCase`), JSON `null` stays `None`, and nothing the payload
+  did not carry is added. `event.raw_object` is an alias for it.
+- **`event.object_as(cls)`** — decode the payload into a shape of your own: a dataclass, a
+  pydantic v2 model, or `dict`. `event.object_as()` with no argument returns a plain dict
+  copy. Only keys the payload actually carried are passed through, so a field it did not send
+  keeps its default rather than being invented, and a trailing underscore maps a reserved
+  word (`from_` reads `from`).
+- **`is_message_event(event_type)`** — whether an event type carries a message-shaped
+  `data.object`. Takes a `WebhookEventType` or a raw string, including one this SDK version
+  has never heard of.
+- **`WebhookVerificationData`** — a ready-made shape for `verification.*` payloads.
+  `parse_event()` does not produce it for you; pass it to
+  `event.object_as(WebhookVerificationData)` when you want it.
+- **An event type this SDK version does not know is delivered, not rejected.** `event.type`
+  keeps the raw string and `event.object` still carries the payload, so a new event released
+  after this version reaches your handler.
+- `WebhookEventType` gains the types that were missing everywhere: `conversation.*`,
+  `draft.*`, `rcs_brand.*`, `rcs_agent.*`, `whatsapp_account.*`, `whatsapp_template.*` and
+  `call.*`. There was previously no typed way to subscribe to RCS, WhatsApp or voice events.
+
+### Patch Changes
+
+- A `data.object` that is not a JSON object now fails with a message that says so —
+  `Failed to parse webhook payload: Invalid event structure: data.object must be an object,
+  got str` — instead of surfacing an internal `'str' object has no attribute 'get'`. It
+  raised before too; only the message changed.
+
+
+### Security
+
+- **Path parameters are percent-encoded.** Every id you pass is now encoded (`urllib.parse.quote(..., safe="")`) before it goes into the request path. An id containing `/`, `?` or `#` used to change which endpoint the request reached: an id of `../../account/keys` left its collection and hit another endpoint carrying your API key. Ordinary ids are sent byte-for-byte as before.
+
 ## 3.38.0
 
 ### Minor Changes

{sendly-3.40.0 → sendly-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendly
-Version: 3.40.0
+Version: 4.1.0
 Summary: Official Sendly Python SDK for SMS messaging
 Project-URL: Homepage, https://sendly.live
 Project-URL: Documentation, https://sendly.live/docs
@@ -379,7 +379,7 @@ client.webhooks.delete('whk_xxx')
 ### Verifying Webhook Signatures
 
 ```python
-from sendly import Webhooks
+from sendly import Webhooks, WebhookSignatureError
 
 WEBHOOK_SECRET = 'your_webhook_secret'
 
@@ -392,16 +392,19 @@ def handle_webhook():
 
     try:
         event = Webhooks.parse_event(payload, signature, WEBHOOK_SECRET, timestamp=timestamp)
-
-        if event.type == 'message.delivered':
-            print(f'Message {event.data.id} delivered')
-        elif event.type == 'message.failed':
-            print(f'Message {event.data.id} failed: {event.data.error_code}')
-
-        return 'OK', 200
-    except Exception as e:
+    except WebhookSignatureError as e:
         print(f'Invalid signature: {e}')
         return 'Invalid signature', 400
+
+    if event.type == 'message.delivered':
+        print(f'Message {event.data.id} delivered')
+    elif event.type == 'message.failed':
+        print(f'Message {event.data.id} failed: {event.data.error_code}')
+    elif event.type == 'rcs_agent.live':
+        # A lifecycle event: event.data is None, the payload is on event.object
+        print(f"Agent {event.object['agent_id']} is live")
+
+    return 'OK', 200
 ```
 
 ### Reading the Event Payload
@@ -414,11 +417,15 @@ nothing the payload did not carry is added.
 `message.*` event, because RCS, WhatsApp, voice (`call.*`), 10DLC
 (`brand.*` / `campaign.*` / `assignment.*`), `number.*`, `port*`, `contact*`,
 `conversation.*`, `draft.*` and `verification.*` payloads are not
-message-shaped.
+message-shaped. `message.opt_in` and `message.opt_out` are `None` too — they
+share the prefix but carry an opt-out record (`phone_number`, `keyword`,
+`from_number`, `timestamp`), not a message.
 
 ```python
 from dataclasses import dataclass
-from sendly import Webhooks
+from typing import Optional
+
+from sendly import Webhooks, is_message_event
 
 event = Webhooks.parse_event(payload, signature, WEBHOOK_SECRET, timestamp=timestamp)
 
@@ -429,6 +436,12 @@ else:
     # lifecycle event: read the raw object
     print(event.object)
 
+# is_message_event() answers the same question from an event type alone, before
+# you have an event in hand - filtering a subscription, routing a queue
+is_message_event('message.delivered')  # True
+is_message_event('rcs_agent.live')     # False
+is_message_event('message.opt_out')    # False - an opt-out record, not a message
+
 # A contact flagged by a send failure: `id` is the contact, `message_id` is
 # the message that failed. They are never swapped.
 if event.type == 'contact.auto_flagged':
@@ -441,22 +454,35 @@ if event.type == 'call.started':
     # for PSTN legs, so treat them as optional rather than assuming either.
     caller = event.object.get('from')
 
-# Or decode into a shape of your own (dataclass, pydantic model, or dict)
+# Or decode into a shape of your own (dataclass, pydantic model, or dict).
+# Only keys the payload actually carried are passed through, so a field it did
+# not send keeps its default instead of being invented. A trailing underscore
+# maps a reserved word: `from_` reads `from`.
 @dataclass
 class AgentLive:
-    agent_id: str = None
-    name: str = None
-    stage: str = None
+    agent_id: Optional[str] = None
+    name: Optional[str] = None
+    stage: Optional[str] = None
 
 if event.type == 'rcs_agent.live':
     agent = event.object_as(AgentLive)
     print(agent.agent_id, agent.stage)
 
-raw = event.object_as()  # plain dict copy
+raw = event.object_as()      # plain dict copy
+same = event.raw_object      # alias for event.object
 ```
 
+`verification.*` payloads have a ready-made shape — pass `WebhookVerificationData` to
+`event.object_as()` rather than writing your own.
+
 Event types live in one place, `sendly.types.WebhookEventType`; `sendly.WebhookEventType`
 re-exports that enum, and `sendly.webhooks.WEBHOOK_EVENT_TYPES` is the tuple of its values.
+An event type this SDK version has not heard of is still delivered rather than rejected:
+`event.type` keeps the raw string and `event.object` still carries the payload.
+
+`message.queued` and `message.undelivered` are not in that enum. The API has never emitted
+either one and rejects both with a `400` on subscribe, so 4.0.0 removed them. `'queued'` and
+`'undelivered'` remain valid message *statuses* on `event.data.status`.
 
 ## Account & Credits
 
@@ -887,6 +913,67 @@ Writes accept an `idempotency_key` like the other write methods; `submit()` and
 `request_launch()` replays return the original response without notifying the
 reviewers again.
 
+## Voice Calls
+
+Place phone calls that one of your AI agents handles, follow them while they
+ring and after they end, end them early, and download recordings. Requires an
+API key with the `calls:read` / `calls:write` scopes; placing and ending calls
+needs a live key. Voice is enabled workspace by workspace: until it is enabled
+for yours, every call method raises `SendlyError` with code `voice_not_enabled`
+(HTTP 404).
+
+Calls are prepaid from your balance per started minute: 2 credits a minute
+outbound plus 8 a minute while an AI agent is on the line (10 credits a minute
+for an agent-handled outbound call); unanswered calls cost nothing. The number
+you call from must be voice-enabled in the dashboard (Calls, then Settings),
+with an emergency address registered; `client.numbers.list()` shows each
+number's `voice_enabled` and `voice_mode`. Destinations are US and Canada.
+
+```python
+# Pick a voice-enabled number (optional when exactly one is voice-enabled)
+voice_numbers = [n for n in client.numbers.list().numbers if n.voice_enabled]
+
+# Place a call; the agent speaks first, using the context you pass
+call = client.calls.create(
+    to='+15555550123',
+    agent_id='3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b',
+    from_=voice_numbers[0].phone_number,
+    context='You are calling Jordan to confirm the 3pm appointment on Tuesday.',
+    metadata={'crmId': 'lead_8812'},
+)
+print(call.id, call.status)  # ... 'ringing'
+
+# Follow it: status moves ringing -> active -> completed (or no_answer, busy, ...)
+call = client.calls.get(call.id)
+print(call.status, call.duration_secs, call.credits_charged, call.hangup_class)
+for line in call.transcript or []:   # agent calls only; None on other calls
+    print(f'[{line.at_ms} ms] {line.speaker}: {line.text}')
+
+# List calls, newest first, with filters and paging
+page = client.calls.list(status='completed', direction='outbound', limit=20)
+for c in page.data:
+    print(c.id, c.to, c.duration_secs, c.credits_charged)
+if page.pagination.has_more:
+    page = client.calls.list(status='completed', direction='outbound', limit=20, offset=20)
+
+# End a call early (idempotent: an ended call is returned unchanged)
+client.calls.hangup(call.id)
+
+# Fetch the recording; the signed URL is valid for 5 minutes
+recording = client.calls.recording(call.id)
+if recording.status == 'ready':
+    print(recording.url, recording.expires_at, recording.content_type)  # audio/ogg
+```
+
+Refusals come back as `SendlyError` with a code that says what to do:
+`insufficient_credits` (raised as `InsufficientCreditsError`; top up),
+`e911_required` (register an emergency address for the number), `lines_busy`
+(retry with backoff), `daily_call_limit` (try again tomorrow),
+`agent_not_found` / `agent_disabled`, `from_number_required` / `no_voice_number`,
+`destination_not_supported`, `live_key_required`. Webhooks `call.started`,
+`call.completed` and `call.recording.ready` carry the same call object in
+snake_case, including `billing` and your `metadata`.
+
 ## Error Handling
 
 The SDK provides typed exception classes:
@@ -1181,6 +1268,28 @@ Submit the agent and its brand for review by Sendly, then the carrier network. `
 
 Ask for the launch review once the agent is in `testing` and has been tried on an invited device.
 
+### `client.calls`
+
+#### `create(to, agent_id, from_=None, context=None, metadata=None, idempotency_key=None) -> Call`
+
+Place a phone call handled by an AI agent (live key, `calls:write`). Returns the call while it is `ringing`; `from_` is required when more than one number is voice-enabled.
+
+#### `list(limit=None, offset=None, status=None, direction=None, kind=None, agent_id=None, to=None, from_=None) -> CallListResponse`
+
+List calls newest first; `pagination.has_more` says whether another page exists.
+
+#### `get(id) -> Call`
+
+Fetch one call. Agent-handled calls carry `transcript`; on other calls it is `None`.
+
+#### `hangup(id, idempotency_key=None) -> Call`
+
+End a call (live key, `calls:write`). `ringing` becomes `cancelled`, `active` becomes `completed`; an ended call is returned unchanged.
+
+#### `recording(id) -> CallRecording`
+
+Where to download the recording. `url` and `expires_at` are set only while `status` is `ready`; the link is valid for 5 minutes.
+
 ## Enterprise
 
 The Enterprise API lets you programmatically manage workspaces, verification, credits, and API keys for multi-tenant platforms. Requires an enterprise master key (`sk_live_v1_master_*`).

{sendly-3.40.0 → sendly-4.1.0}/README.md

@@ -344,7 +344,7 @@ client.webhooks.delete('whk_xxx')
 ### Verifying Webhook Signatures
 
 ```python
-from sendly import Webhooks
+from sendly import Webhooks, WebhookSignatureError
 
 WEBHOOK_SECRET = 'your_webhook_secret'
 
@@ -357,16 +357,19 @@ def handle_webhook():
 
     try:
         event = Webhooks.parse_event(payload, signature, WEBHOOK_SECRET, timestamp=timestamp)
-
-        if event.type == 'message.delivered':
-            print(f'Message {event.data.id} delivered')
-        elif event.type == 'message.failed':
-            print(f'Message {event.data.id} failed: {event.data.error_code}')
-
-        return 'OK', 200
-    except Exception as e:
+    except WebhookSignatureError as e:
         print(f'Invalid signature: {e}')
         return 'Invalid signature', 400
+
+    if event.type == 'message.delivered':
+        print(f'Message {event.data.id} delivered')
+    elif event.type == 'message.failed':
+        print(f'Message {event.data.id} failed: {event.data.error_code}')
+    elif event.type == 'rcs_agent.live':
+        # A lifecycle event: event.data is None, the payload is on event.object
+        print(f"Agent {event.object['agent_id']} is live")
+
+    return 'OK', 200
 ```
 
 ### Reading the Event Payload
@@ -379,11 +382,15 @@ nothing the payload did not carry is added.
 `message.*` event, because RCS, WhatsApp, voice (`call.*`), 10DLC
 (`brand.*` / `campaign.*` / `assignment.*`), `number.*`, `port*`, `contact*`,
 `conversation.*`, `draft.*` and `verification.*` payloads are not
-message-shaped.
+message-shaped. `message.opt_in` and `message.opt_out` are `None` too — they
+share the prefix but carry an opt-out record (`phone_number`, `keyword`,
+`from_number`, `timestamp`), not a message.
 
 ```python
 from dataclasses import dataclass
-from sendly import Webhooks
+from typing import Optional
+
+from sendly import Webhooks, is_message_event
 
 event = Webhooks.parse_event(payload, signature, WEBHOOK_SECRET, timestamp=timestamp)
 
@@ -394,6 +401,12 @@ else:
     # lifecycle event: read the raw object
     print(event.object)
 
+# is_message_event() answers the same question from an event type alone, before
+# you have an event in hand - filtering a subscription, routing a queue
+is_message_event('message.delivered')  # True
+is_message_event('rcs_agent.live')     # False
+is_message_event('message.opt_out')    # False - an opt-out record, not a message
+
 # A contact flagged by a send failure: `id` is the contact, `message_id` is
 # the message that failed. They are never swapped.
 if event.type == 'contact.auto_flagged':
@@ -406,22 +419,35 @@ if event.type == 'call.started':
     # for PSTN legs, so treat them as optional rather than assuming either.
     caller = event.object.get('from')
 
-# Or decode into a shape of your own (dataclass, pydantic model, or dict)
+# Or decode into a shape of your own (dataclass, pydantic model, or dict).
+# Only keys the payload actually carried are passed through, so a field it did
+# not send keeps its default instead of being invented. A trailing underscore
+# maps a reserved word: `from_` reads `from`.
 @dataclass
 class AgentLive:
-    agent_id: str = None
-    name: str = None
-    stage: str = None
+    agent_id: Optional[str] = None
+    name: Optional[str] = None
+    stage: Optional[str] = None
 
 if event.type == 'rcs_agent.live':
     agent = event.object_as(AgentLive)
     print(agent.agent_id, agent.stage)
 
-raw = event.object_as()  # plain dict copy
+raw = event.object_as()      # plain dict copy
+same = event.raw_object      # alias for event.object
 ```
 
+`verification.*` payloads have a ready-made shape — pass `WebhookVerificationData` to
+`event.object_as()` rather than writing your own.
+
 Event types live in one place, `sendly.types.WebhookEventType`; `sendly.WebhookEventType`
 re-exports that enum, and `sendly.webhooks.WEBHOOK_EVENT_TYPES` is the tuple of its values.
+An event type this SDK version has not heard of is still delivered rather than rejected:
+`event.type` keeps the raw string and `event.object` still carries the payload.
+
+`message.queued` and `message.undelivered` are not in that enum. The API has never emitted
+either one and rejects both with a `400` on subscribe, so 4.0.0 removed them. `'queued'` and
+`'undelivered'` remain valid message *statuses* on `event.data.status`.
 
 ## Account & Credits
 
@@ -852,6 +878,67 @@ Writes accept an `idempotency_key` like the other write methods; `submit()` and
 `request_launch()` replays return the original response without notifying the
 reviewers again.
 
+## Voice Calls
+
+Place phone calls that one of your AI agents handles, follow them while they
+ring and after they end, end them early, and download recordings. Requires an
+API key with the `calls:read` / `calls:write` scopes; placing and ending calls
+needs a live key. Voice is enabled workspace by workspace: until it is enabled
+for yours, every call method raises `SendlyError` with code `voice_not_enabled`
+(HTTP 404).
+
+Calls are prepaid from your balance per started minute: 2 credits a minute
+outbound plus 8 a minute while an AI agent is on the line (10 credits a minute
+for an agent-handled outbound call); unanswered calls cost nothing. The number
+you call from must be voice-enabled in the dashboard (Calls, then Settings),
+with an emergency address registered; `client.numbers.list()` shows each
+number's `voice_enabled` and `voice_mode`. Destinations are US and Canada.
+
+```python
+# Pick a voice-enabled number (optional when exactly one is voice-enabled)
+voice_numbers = [n for n in client.numbers.list().numbers if n.voice_enabled]
+
+# Place a call; the agent speaks first, using the context you pass
+call = client.calls.create(
+    to='+15555550123',
+    agent_id='3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b',
+    from_=voice_numbers[0].phone_number,
+    context='You are calling Jordan to confirm the 3pm appointment on Tuesday.',
+    metadata={'crmId': 'lead_8812'},
+)
+print(call.id, call.status)  # ... 'ringing'
+
+# Follow it: status moves ringing -> active -> completed (or no_answer, busy, ...)
+call = client.calls.get(call.id)
+print(call.status, call.duration_secs, call.credits_charged, call.hangup_class)
+for line in call.transcript or []:   # agent calls only; None on other calls
+    print(f'[{line.at_ms} ms] {line.speaker}: {line.text}')
+
+# List calls, newest first, with filters and paging
+page = client.calls.list(status='completed', direction='outbound', limit=20)
+for c in page.data:
+    print(c.id, c.to, c.duration_secs, c.credits_charged)
+if page.pagination.has_more:
+    page = client.calls.list(status='completed', direction='outbound', limit=20, offset=20)
+
+# End a call early (idempotent: an ended call is returned unchanged)
+client.calls.hangup(call.id)
+
+# Fetch the recording; the signed URL is valid for 5 minutes
+recording = client.calls.recording(call.id)
+if recording.status == 'ready':
+    print(recording.url, recording.expires_at, recording.content_type)  # audio/ogg
+```
+
+Refusals come back as `SendlyError` with a code that says what to do:
+`insufficient_credits` (raised as `InsufficientCreditsError`; top up),
+`e911_required` (register an emergency address for the number), `lines_busy`
+(retry with backoff), `daily_call_limit` (try again tomorrow),
+`agent_not_found` / `agent_disabled`, `from_number_required` / `no_voice_number`,
+`destination_not_supported`, `live_key_required`. Webhooks `call.started`,
+`call.completed` and `call.recording.ready` carry the same call object in
+snake_case, including `billing` and your `metadata`.
+
 ## Error Handling
 
 The SDK provides typed exception classes:
@@ -1146,6 +1233,28 @@ Submit the agent and its brand for review by Sendly, then the carrier network. `
 
 Ask for the launch review once the agent is in `testing` and has been tried on an invited device.
 
+### `client.calls`
+
+#### `create(to, agent_id, from_=None, context=None, metadata=None, idempotency_key=None) -> Call`
+
+Place a phone call handled by an AI agent (live key, `calls:write`). Returns the call while it is `ringing`; `from_` is required when more than one number is voice-enabled.
+
+#### `list(limit=None, offset=None, status=None, direction=None, kind=None, agent_id=None, to=None, from_=None) -> CallListResponse`
+
+List calls newest first; `pagination.has_more` says whether another page exists.
+
+#### `get(id) -> Call`
+
+Fetch one call. Agent-handled calls carry `transcript`; on other calls it is `None`.
+
+#### `hangup(id, idempotency_key=None) -> Call`
+
+End a call (live key, `calls:write`). `ringing` becomes `cancelled`, `active` becomes `completed`; an ended call is returned unchanged.
+
+#### `recording(id) -> CallRecording`
+
+Where to download the recording. `url` and `expires_at` are set only while `status` is `ready`; the link is valid for 5 minutes.
+
 ## Enterprise
 
 The Enterprise API lets you programmatically manage workspaces, verification, credits, and API keys for multi-tenant platforms. Requires an enterprise master key (`sk_live_v1_master_*`).

{sendly-3.40.0 → sendly-4.1.0}/pyproject.toml

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

{sendly-3.40.0 → sendly-4.1.0}/sendly/__init__.py

@@ -29,7 +29,7 @@ Async Example:
     >>> asyncio.run(main())
 """
 
-__version__ = "3.40.0"
+__version__ = "4.1.0"
 
 # Main clients
 from .client import AsyncSendly, Sendly
@@ -51,6 +51,7 @@ from .resources.business_upgrade import (
     AsyncBusinessUpgradeResource,
     BusinessUpgradeResource,
 )
+from .resources.calls import AsyncCallsResource, CallsResource
 from .resources.links import AsyncLinksResource, LinksResource
 from .resources.media import AsyncMediaResource, MediaResource
 from .resources.numbers import AsyncNumbersResource, NumbersResource
@@ -194,6 +195,20 @@ from .types import (
     RcsTestDeviceInput,
     RcsTestDeviceListResponse,
     RcsTesting,
+    # Voice call types
+    Call,
+    CallBilling,
+    CallDirection,
+    CallHandledBy,
+    CallKind,
+    CallListResponse,
+    CallPagination,
+    CallRecording,
+    CallRecordingStatus,
+    CallStatus,
+    CallTranscriptLine,
+    CreateCallRequest,
+    ListCallsOptions,
     OptInPage,
     PricingTier,
     QuotaSettings,
@@ -406,6 +421,20 @@ __all__ = [
     "RcsTestDeviceInput",
     "RcsTestDeviceListResponse",
     "RcsTesting",
+    # Voice call types
+    "Call",
+    "CallBilling",
+    "CallDirection",
+    "CallHandledBy",
+    "CallKind",
+    "CallListResponse",
+    "CallPagination",
+    "CallRecording",
+    "CallRecordingStatus",
+    "CallStatus",
+    "CallTranscriptLine",
+    "CreateCallRequest",
+    "ListCallsOptions",
     # Links resources
     "LinksResource",
     "AsyncLinksResource",
@@ -427,6 +456,9 @@ __all__ = [
     # RCS resources
     "RcsResource",
     "AsyncRcsResource",
+    # Voice call resources
+    "CallsResource",
+    "AsyncCallsResource",
     # Errors
     "SendlyError",
     "AuthenticationError",