@sentdm/sentdm 0.45.0 → 0.47.0

package/src/resources/channels/voice.ts

@@ -10,7 +10,7 @@ import { path } from '../../internal/utils/path';
 /**
  * The senders you send from, one per channel.
  *
- * **SMS is a list of markets**, each keyed by `(country, number_type)` — a customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is addressed by the pair rather than by country alone. **WhatsApp and RCS are single**: a customer has one business account and one agent. **Voice is per number**: each number you hold can carry phone calls on its own (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do with its calls, one of them is the default line for calls placed from your app, and voice tokens are minted under `POST /v3/channels/voice/tokens`. Read your voice numbers with `GET /v3/channels/voice` and change one with `PATCH /v3/channels/voice/{number}`.
+ * **SMS is a list of markets**, each keyed by `(country, number_type)` — a customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is addressed by the pair rather than by country alone. **WhatsApp and RCS are single**: a customer has one business account and one agent. **Voice is per number**: each number you hold can carry phone calls on its own (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do with its calls, one of them is the default line for calls placed from your app, and voice tokens are minted with `POST /v3/voice/tokens`. Read your voice numbers with `GET /v3/channels/voice` and change one with `PATCH /v3/channels/voice/{number}`.
  *
  * ## Compliance lives on the market
  *
@@ -35,6 +35,16 @@ export class Voice extends APIResource {
    * question the way you verify a webhook. `POST /v3/channels/voice/{number}/test`
    * sends a test question and reports the verdict.
    *
+   * Send `agent_id` instead of `callback_url`, or with it, to have one of your voice
+   * agents (`GET /v3/voice/agents`) answer calls to the number. The agent wins over
+   * the callback URL for calls to the number; calls your app places from it still
+   * follow your app. `routes_to` in the response says which answers, and reads
+   * `agent_pending` while the number is still being moved to the agent. Calls follow
+   * the move within about an hour, as the provider applies it on its own clock.
+   * While numbers cannot be bound to agents, a request with `agent_id` is refused
+   * with `502` before any number is obtained or anything is written; send
+   * `callback_url` instead.
+   *
    * Your first voice number becomes the line app-originated calls are placed from
    * when a voice token names no number; send `default_for_app_calls: true` to give
    * that role to another number. A number you turned off earlier is turned back on,
@@ -109,18 +119,27 @@ export class Voice extends APIResource {
    *
    * ## What it changes
    *
-   * | Body                                          | Effect                                                                                                                                                     |
-   * | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   * | `"status": "ACTIVE"`                          | turns calls on again for a number you turned off; the callback URL and the secret it had are kept                                                          |
-   * | `"status": "INACTIVE"`                        | turns calls off; the callback URL and the secret stay on the number                                                                                        |
-   * | `"default_for_app_calls": true`               | makes this the line app-originated calls are placed from when a voice token names no number                                                                |
-   * | `"callback_url": "https://example.com/voice"` | replaces where Sent asks what to do with each call on the number; the signing secret is kept, and a number that was waiting for its first URL is turned on |
-   * | key omitted                                   | left exactly as it is                                                                                                                                      |
+   * | Body                                          | Effect                                                                                                                                                                                                                                                                                                                                                                                                     |
+   * | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   * | `"status": "ACTIVE"`                          | turns calls on again for a number you turned off; the callback URL and the secret it had are kept                                                                                                                                                                                                                                                                                                          |
+   * | `"status": "INACTIVE"`                        | turns calls off; the callback URL and the secret stay on the number                                                                                                                                                                                                                                                                                                                                        |
+   * | `"default_for_app_calls": true`               | makes this the line app-originated calls are placed from when a voice token names no number                                                                                                                                                                                                                                                                                                                |
+   * | `"callback_url": "https://example.com/voice"` | replaces where Sent asks what to do with each call on the number; the signing secret and the status are kept                                                                                                                                                                                                                                                                                               |
+   * | `"agent_id": "agent_…"`                       | one of your voice agents answers calls to the number, within about an hour of the change (the provider applies the move on its own clock, and `routes_to` reads `agent` as soon as it has recorded it); it wins over `callback_url` for calls to the number, and calls your app places from it still follow your app. `routes_to` reads `agent_pending` while the number is still being moved to the agent |
+   * | `"agent_id": null`                            | unbinds the agent, so `callback_url` answers calls to the number again                                                                                                                                                                                                                                                                                                                                     |
+   * | key omitted                                   | left exactly as it is                                                                                                                                                                                                                                                                                                                                                                                      |
    *
    * `status` is matched ignoring case. Any combination is accepted:
    * `status: "ACTIVE"` with `default_for_app_calls: true` turns a number on as the
-   * new default, and a `callback_url` sent with either status is written too. A body
-   * that names none of the three is refused.
+   * new default, and a `callback_url` sent with either status is written too.
+   * `agent_id` is applied first, so a refusal to move the number to or from the
+   * agent leaves everything as it was, and the `409` and `400` refusals below are
+   * decided before anything is written, so they leave everything as it was too. A
+   * body that names none of them is refused.
+   *
+   * A number can be on without a callback URL: calls placed from your app then
+   * connect straight to the number or user they dial, and calls to the number are
+   * declined.
    *
    * ## What it will refuse
    *
@@ -135,13 +154,12 @@ export class Voice extends APIResource {
    * **Making an inactive number the default is `400`.** Send `status: "ACTIVE"` in
    * the same call.
    *
-   * A number added without a `callback_url` is `INACTIVE` for that one reason, so
-   * sending it a `callback_url` turns it on by itself, and it becomes your default
-   * line if you have no other active voice number. A number you turned off while it
-   * had a URL stays off.
+   * **A number you never turned voice on for is `404`**, and so is an `agent_id`
+   * that is not one of your agents. Add the number with `POST /v3/channels/voice`.
    *
-   * **A number you never turned voice on for is `404`.** Add it with
-   * `POST /v3/channels/voice`.
+   * **`502` means the number could not be moved to or from the agent**, or an
+   * `agent_id` was sent while numbers cannot be bound to agents; nothing was
+   * written.
    *
    * The number is the E.164 value in the path with the plus sign URL-encoded
    * (`%2B`).
@@ -153,7 +171,7 @@ export class Voice extends APIResource {
    * @example
    * ```ts
    * const apiResponseOfVoiceNumber =
-   *   await client.channels.voice.update('+12125550100');
+   *   await client.channels.voice.update('number');
    * ```
    */
   update(
@@ -206,35 +224,6 @@ export class Voice extends APIResource {
     });
   }
 
-  /**
-   * Mints a short-lived token for one of your app users. Call this from your backend
-   * and return the token to your app, which passes it to the voice client SDK to
-   * register. The identity is bound to the given number, or to your default app-call
-   * number when omitted, and calls placed by that identity are routed through the
-   * bound number. Minting again re-binds the identity, so an identity can move
-   * between numbers.
-   *
-   * @example
-   * ```ts
-   * const apiResponseOfVoiceToken =
-   *   await client.channels.voice.createToken();
-   * ```
-   */
-  createToken(params: VoiceCreateTokenParams, options?: RequestOptions): APIPromise<APIResponseOfVoiceToken> {
-    const { 'Idempotency-Key': idempotencyKey, 'x-profile-id': xProfileID, ...body } = params;
-    return this._client.post('/v3/channels/voice/tokens', {
-      body,
-      ...options,
-      headers: buildHeaders([
-        {
-          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
-          ...(xProfileID != null ? { 'x-profile-id': xProfileID } : undefined),
-        },
-        options?.headers,
-      ]),
-    });
-  }
-
   /**
    * Generates a new signing secret for the questions Sent sends to this number's
    * callback URL and returns it. The previous secret stops signing immediately, so
@@ -434,31 +423,6 @@ export interface APIResponseOfVoiceSecret {
   success?: boolean;
 }
 
-/**
- * Standard API response envelope for all v3 endpoints
- */
-export interface APIResponseOfVoiceToken {
-  /**
-   * A short-lived token your app passes to the voice client SDK to register
-   */
-  data?: VoiceToken | null;
-
-  /**
-   * Error information
-   */
-  error?: WebhooksAPI.ErrorDetail | null;
-
-  /**
-   * Request and response metadata
-   */
-  meta?: WebhooksAPI.APIMeta;
-
-  /**
-   * Indicates whether the request was successful
-   */
-  success?: boolean;
-}
-
 /**
  * The verdict of a test question sent to your callback URL
  */
@@ -558,6 +522,14 @@ export interface VoiceCallbackTestResponseInfo {
  * One number the profile carries phone calls on.
  */
 export interface VoiceNumber {
+  /**
+   * The voice agent calls to this number go to, such as
+   * agent_9f2ab000-0000-4000-8000-000000000001. It wins over callback_url for calls
+   * to the number; calls your app places from the number still follow your app. Null
+   * when no agent answers the number.
+   */
+  agent_id?: string | null;
+
   /**
    * Where Sent asks what to do with each call on this number: a signed question is
    * POSTed here when a call arrives or a caller presses a key, and the answer
@@ -580,6 +552,14 @@ export interface VoiceNumber {
    */
   number?: string;
 
+  /**
+   * Who answers calls to this number: agent, the voice agent in agent_id;
+   * agent_pending, that agent once the number has finished moving to it, with calls
+   * possibly unanswered until then; callback, your callback_url; or none, in which
+   * case calls to it are declined.
+   */
+  routes_to?: string;
+
   /**
    * ACTIVE while the number carries calls, INACTIVE once it was turned off. Nothing
    * provisions: a number the customer holds can carry calls the moment voice is
@@ -614,49 +594,33 @@ export interface VoiceSecret {
   callback_secret?: string;
 }
 
-/**
- * A short-lived token your app passes to the voice client SDK to register
- */
-export interface VoiceToken {
-  /**
-   * The signed token. Hand it to the client SDK unchanged.
-   */
-  token?: string;
-
-  /**
-   * When the token expires (UTC)
-   */
-  expires_at?: string;
-
+export interface VoiceCreateParams {
   /**
-   * The identity the token was minted for
+   * Body param: One of your voice agents (GET /v3/voice/agents), such as
+   * agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to this number. It
+   * wins over callback_url for calls to the number, and both may be sent; calls your
+   * app places from the number still follow your app. Send it instead of
+   * callback_url for a number only an agent answers.
    */
-  identity?: string;
+  agent_id?: string | null;
 
   /**
-   * The phone number this identity is now bound to, in E.164 format
+   * Body param: The US area code a new number should be in, as 212. Only for a
+   * request that leaves number out — sending both says two different things about
+   * which number to use, and is refused. Omit it too and the number comes from
+   * anywhere in the country.
    */
-  number?: string;
-}
+  area_code?: string | null;
 
-export interface VoiceCreateParams {
   /**
    * Body param: Where Sent asks what to do with each call on this number: an
    * absolute HTTP or HTTPS URL on a public host. A signed question is POSTed here
    * when a call arrives or a caller presses a key, and the answer decides the call.
    * Every question is signed with the callback_secret the response returns, the same
    * way your webhooks are signed. Turning the number on again with a different URL
-   * replaces it and keeps the secret.
+   * replaces it and keeps the secret. Required unless agent_id is sent.
    */
-  callback_url: string;
-
-  /**
-   * Body param: The US area code a new number should be in, as 212. Only for a
-   * request that leaves number out — sending both says two different things about
-   * which number to use, and is refused. Omit it too and the number comes from
-   * anywhere in the country.
-   */
-  area_code?: string | null;
+  callback_url?: string | null;
 
   /**
    * Body param: Make this the line app-originated calls are placed from when a voice
@@ -702,6 +666,15 @@ export interface VoiceRetrieveParams {
 }
 
 export interface VoiceUpdateParams {
+  /**
+   * Body param: One of your voice agents, such as
+   * agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to the number, or
+   * null to unbind it so the callback URL answers them again. The agent wins over
+   * callback_url for calls to the number; calls your app places from it still follow
+   * your app.
+   */
+  agent_id?: string | null;
+
   /**
    * Body param: A new callback URL for the number, active or not: an absolute HTTP
    * or HTTPS URL on a public host, where Sent asks what to do with each call. The
@@ -753,46 +726,6 @@ export interface VoiceListParams {
   'x-profile-id'?: string;
 }
 
-export interface VoiceCreateTokenParams {
-  /**
-   * Body param: Your identifier for the app user, such as an agent or account id.
-   * Letters, digits, hyphens and underscores only, up to 200 characters.
-   */
-  identity?: string;
-
-  /**
-   * Body param: One of your voice-enabled phone numbers in E.164 format. Calls
-   * placed by this identity are routed through that number. Omit to use your default
-   * app-call number.
-   */
-  number?: string | null;
-
-  /**
-   * Body param: Sandbox flag - when true, the operation is simulated without side
-   * effects Useful for testing integrations without actual execution
-   */
-  sandbox?: boolean;
-
-  /**
-   * Body param: Token lifetime in seconds. Defaults to 600 and cannot exceed 3600.
-   */
-  ttl?: number | null;
-
-  /**
-   * Header param: Unique key to ensure idempotent request processing. Must be 1-255
-   * alphanumeric characters, hyphens, or underscores. Responses are cached for 24
-   * hours per key per customer.
-   */
-  'Idempotency-Key'?: string;
-
-  /**
-   * Header param: Profile UUID to scope the request to a child profile. Only
-   * organization API keys can use this header. The profile must belong to the
-   * calling organization.
-   */
-  'x-profile-id'?: string;
-}
-
 export interface VoiceRotateSecretParams {
   /**
    * Body param: Sandbox flag - when true, the operation is simulated without side
@@ -844,7 +777,6 @@ export declare namespace Voice {
     type APIResponseOfVoiceNumber as APIResponseOfVoiceNumber,
     type APIResponseOfVoiceNumberCreated as APIResponseOfVoiceNumberCreated,
     type APIResponseOfVoiceSecret as APIResponseOfVoiceSecret,
-    type APIResponseOfVoiceToken as APIResponseOfVoiceToken,
     type VoiceCallbackTest as VoiceCallbackTest,
     type VoiceCallbackTestErrorInfo as VoiceCallbackTestErrorInfo,
     type VoiceCallbackTestRequestInfo as VoiceCallbackTestRequestInfo,
@@ -852,12 +784,10 @@ export declare namespace Voice {
     type VoiceNumber as VoiceNumber,
     type VoiceNumberCreated as VoiceNumberCreated,
     type VoiceSecret as VoiceSecret,
-    type VoiceToken as VoiceToken,
     type VoiceCreateParams as VoiceCreateParams,
     type VoiceRetrieveParams as VoiceRetrieveParams,
     type VoiceUpdateParams as VoiceUpdateParams,
     type VoiceListParams as VoiceListParams,
-    type VoiceCreateTokenParams as VoiceCreateTokenParams,
     type VoiceRotateSecretParams as VoiceRotateSecretParams,
     type VoiceTestParams as VoiceTestParams,
   };

package/src/resources/index.ts

@@ -1,23 +1,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export {
-  Calls,
-  type APIResponseOfCall,
-  type APIResponseOfCallRecordings,
-  type APIResponseOfCallsList,
-  type Call,
-  type CallParty,
-  type CallRecording,
-  type CallRecordings,
-  type CallTimelineEntry,
-  type CallsList,
-  type CallRetrieveParams,
-  type CallListParams,
-  type CallHangupParams,
-  type CallListRecordingsParams,
-  type CallRecordParams,
-  type CallsCallsPage,
-} from './calls/calls';
 export { Channels } from './channels/channels';
 export {
   Contacts,
@@ -105,6 +87,7 @@ export {
   type UserRemoveParams,
   type UserUpdateRoleParams,
 } from './users';
+export { Voice } from './voice/voice';
 export {
   Webhooks,
   type APIMeta,

package/src/resources/messages.ts

@@ -646,6 +646,11 @@ export interface MessageSendParams {
    * itself is unchanged: the same rules are scored and ranked the same way, with
    * routes pinned to numbers you did not list removed from the running.
    *
+   * Each channel's list is independent: an sms list does not restrict MMS. To choose
+   * the numbers a message may go out from as MMS, name them under mms. MMS sends
+   * from your SMS numbers, so an mms list may name any of your active SMS numbers
+   * whose market carries MMS — the ones listed under mms in your channels.
+   *
    * Every number must be an active sender on your account. The request itself is
    * still accepted (202) if one is not — like every other send-time rule, that is
    * decided per message, so each affected message is recorded BLOCKED with error
@@ -663,7 +668,9 @@ export interface MessageSendParams {
    *
    * Their presence is also what makes a message eligible for MMS on an auto-detect
    * send: a message with nothing attached is delivered as SMS, because an MMS with
-   * no media is a more expensive text message.
+   * no media is a more expensive text message. For the same reason a send that names
+   * mms in channel with nothing attached, here or on the template, is refused with
+   * a 400.
    *
    * The recipient's carrier fetches each URL after the send is accepted, so it must
    * stay publicly reachable — a link that expires, or one behind auth, arrives as a

package/src/resources/profiles/campaigns.ts

@@ -53,8 +53,9 @@ export class Campaigns extends APIResource {
    * which models a profile's markets, compliance, brand, campaigns and billing
    * explicitly.
    *
-   * Updates an existing campaign under the brand of the specified profile. Cannot
-   * update campaigns that have already been submitted to TCR.
+   * Updates an existing campaign under the brand of the specified profile. Once the
+   * campaign has been submitted to TCR its volume can no longer move between low
+   * volume (under 2,000 messages a day) and high volume.
    *
    * @deprecated
    */

package/src/resources/templates.ts

@@ -255,17 +255,18 @@ export interface Template {
 
   /**
    * The channels this template's definition can render on, in canonical order: sms,
-   * whatsapp, rcs.
+   * whatsapp, rcs, mms.
    *
    * Derived from the definition's body, mirroring each channel's send-time fallback
    * chain, so a channel is listed only when a real body would be produced for it:
    * SMS reads sms ?? multiChannel, WhatsApp reads whatsapp ?? multiChannel, and RCS
-   * reads rcs ?? multiChannel ?? sms. A multiChannel body therefore reports all
-   * three, and the extra SMS fallback on RCS is why an sms/whatsapp pair reports RCS
-   * too.
+   * and MMS read rcs ?? multiChannel ?? sms and mms ?? multiChannel ?? sms. A
+   * multiChannel body therefore reports all four, and the extra SMS fallback is why
+   * an sms/whatsapp pair reports RCS and MMS too.
    *
    * This says what the content can render on, not what may be sent: sending also
-   * needs the template approved for that channel.
+   * needs the template approved for that channel, and MMS needs an attachment, from
+   * media_urls or the template's mms body.
    */
   channels?: Array<string> | null;
 
@@ -323,10 +324,10 @@ export interface TemplateBody {
    * MMS-specific content — subject, text and attachments.
    *
    * Like Rcs, an override that cannot stand on its own: a template still needs a
-   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
-   * Rcs, it has no fallback at send time — MMS with no media is a more expensive
-   * SMS, so a template without this slot is deliberately not MMS-capable and never
-   * produces an MMS route candidate.
+   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Without
+   * this slot MMS renders the shared or SMS body, so it is only needed for
+   * MMS-specific copy, a subject or attachments. When present it replaces that body
+   * on MMS rather than adding to it.
    */
   mms?: TemplateBody.Mms | null;
 
@@ -358,10 +359,10 @@ export namespace TemplateBody {
    * MMS-specific content — subject, text and attachments.
    *
    * Like Rcs, an override that cannot stand on its own: a template still needs a
-   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
-   * Rcs, it has no fallback at send time — MMS with no media is a more expensive
-   * SMS, so a template without this slot is deliberately not MMS-capable and never
-   * produces an MMS route candidate.
+   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Without
+   * this slot MMS renders the shared or SMS body, so it is only needed for
+   * MMS-specific copy, a subject or attachments. When present it replaces that body
+   * on MMS rather than adding to it.
    */
   export interface Mms extends TemplatesAPI.TemplateBodyContent {
     /**