@sentdm/sentdm 0.46.0 → 0.48.0

package/src/resources/voice/calls/calls.ts

@@ -26,14 +26,18 @@ import { path } from '../../../internal/utils/path';
  * `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent asks what to do with each call on it, and `POST /v3/voice/tokens` mints a short-lived token that lets a user of your app place and receive calls as that number. When a call arrives or a caller presses a key, a signed question is POSTed to the callback URL and the answer decides the call; `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need before a real call reaches it, and `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret. The call events themselves (`call.completed` and the rest) arrive through your webhooks.
  *
  * Every call is a record under `/v3/voice/calls`: read it, list its recordings once one is ready, hang it up, start or stop recording, and add, mute or remove conference participants while it is live. A leg to a phone number runs for at most what your balance affords at the destination's rate.
+ *
+ * **Voice agents.** `POST /v3/voice/agents` creates an agent that answers calls through the Sent Voice Gateway: `session_type` says whether Sent carries the call as text (speech recognised and spoken for the agent) or as audio, `websocket_url` is where the gateway dials the agent for each call (leave it out and the agent dials in with your API key), and `tools`, `transfer_targets`, `fallback` and `limits` say what it may do on a call. The agent's `signing_secret` is shown on create and on `POST /v3/voice/agents/{id}/rotate-secret` only. Voices and languages for text sessions come from `GET /v3/voice/voices`. A number takes calls to an agent once it is bound to it on `/v3/channels/voice`.
  */
 export class Calls extends APIResource {
   participants: ParticipantsAPI.Participants = new ParticipantsAPI.Participants(this._client);
 
   /**
-   * Retrieves one of your calls by id: the parties, the owning number, the current
-   * status with its failure reason, duration, price, recording availability, and a
-   * timeline of when the call entered each status.
+   * Retrieves one of your calls by id: the parties, the owning number, the phone
+   * number the call was connected to and the caller id it showed, the current status
+   * with its failure reason, duration, price with the billed legs and what each
+   * cost, recording availability, and a timeline of when the call entered each
+   * status.
    *
    * @example
    * ```ts
@@ -59,9 +63,12 @@ export class Calls extends APIResource {
 
   /**
    * Retrieves a paginated list of your calls, most recent first. Filter by
-   * direction, status, the owning number, and the time the call started (from and to
-   * are inclusive). Use the call webhooks for real-time updates; this list is for
-   * looking calls up afterwards.
+   * direction, status, the owning number, the mode (inapp, or agent for calls your
+   * voice agents answered), the agent that answered, and the time the call started
+   * (from and to are inclusive). Each call carries the phone number it was connected
+   * to, the caller id it showed, and the billed legs with what each cost. Use the
+   * call webhooks for real-time updates; this list is for looking calls up
+   * afterwards.
    *
    * @example
    * ```ts
@@ -90,8 +97,8 @@ export class Calls extends APIResource {
    * Ends one of your live calls. The call then ends the way any other call does once
    * the disconnect is reported: an answered call as COMPLETED with call.completed, a
    * call still ringing as NO_ANSWER, REJECTED or FAILED with call.failed. A call
-   * that has already ended answers 409, and so does a call with no phone leg, such
-   * as one between two app users.
+   * that has already ended answers 409, as do a call with no phone leg, such as one
+   * between two app users, and a call one of your voice agents answers.
    *
    * @example
    * ```ts
@@ -151,9 +158,9 @@ export class Calls extends APIResource {
   /**
    * Starts or stops recording one of your live calls. Use start to begin recording
    * mid-call, or stop to end a recording, whether it was started here or by a
-   * connect answer with record set. A call that has already ended answers 409, and
-   * so does a call with no phone leg, such as one between two app users, which can't
-   * be recorded.
+   * connect answer with record set. A call that has already ended answers 409, as do
+   * a call with no phone leg, such as one between two app users, and a call one of
+   * your voice agents answers, neither of which can be recorded this way.
    *
    * @example
    * ```ts
@@ -266,12 +273,32 @@ export interface Call {
    */
   id?: string;
 
+  /**
+   * The voice agent that answered the call, such as
+   * agent_9f2ab000-0000-4000-8000-000000000001. Null for an inapp call
+   */
+  agent_id?: string | null;
+
   /**
    * When the call was answered (UTC). Null until then, and always null for a call
    * between two of your app users
    */
   answered_at?: string | null;
 
+  /**
+   * The caller id shown on the phone leg, in E.164 format: the one your answer
+   * chose, or the owning number when it chose none. Null for a call with no phone
+   * leg
+   */
+  caller_id_used?: string | null;
+
+  /**
+   * The phone number the call was connected to, in E.164 format: the number your
+   * answer dialed, or the fallback number a call to one of your voice agents
+   * reached. Null when the call was not connected to a phone number
+   */
+  connected_number?: string | null;
+
   /**
    * outbound for a call placed from your app, inbound for a call to one of your
    * numbers
@@ -290,9 +317,9 @@ export interface Call {
 
   /**
    * Why the call did not complete: callback_timeout, invalid_answer,
-   * insufficient_balance, destination_blocked, callback_not_configured, rejected or
-   * no_answer. Null while the call is live, when it completed, and when it failed
-   * without a recorded reason
+   * insufficient_balance, destination_blocked, callback_not_configured, rejected,
+   * no_answer, or for an agent call agent_busy or agent_unreachable. Null while the
+   * call is live, when it completed, and when it failed without a recorded reason
    */
   failure_reason?: string | null;
 
@@ -301,9 +328,18 @@ export interface Call {
    */
   from?: CallParty;
 
+  /**
+   * The legs the price covers, one entry per billed leg, each with its own cost: a
+   * call your answer connected to a phone number ran the caller's leg to your number
+   * and the leg to the connected number at once, and both are billed. Null until the
+   * call has been priced
+   */
+  legs?: Array<Call.Leg> | null;
+
   /**
    * The calling mode: inapp for a call between people in your app and phone numbers,
-   * routed by your number's callback URL
+   * routed by your number's callback URL; agent for a call one of your voice agents
+   * answered
    */
   mode?: string;
 
@@ -345,6 +381,41 @@ export interface Call {
   to?: CallParty;
 }
 
+export namespace Call {
+  /**
+   * One leg of a call the price covers
+   */
+  export interface Leg {
+    /**
+     * The whole minutes the leg was billed for
+     */
+    billed_minutes?: number;
+
+    /**
+     * What the leg cost, in the same unit as the call's price
+     */
+    cost?: number;
+
+    /**
+     * The currency of the cost: USD
+     */
+    currency?: string;
+
+    /**
+     * inbound for the caller's leg to your number, outbound for a leg placed on your
+     * behalf
+     */
+    direction?: string;
+
+    /**
+     * The phone number the leg reached, in E.164 format: your number for the inbound
+     * leg, the number dialed for an outbound one. Null for a leg to one of your app
+     * users or a room
+     */
+    number?: string | null;
+  }
+}
+
 /**
  * One end of a call
  */
@@ -434,6 +505,12 @@ export interface CallRetrieveParams {
 }
 
 export interface CallListParams extends CallsPageParams {
+  /**
+   * Query param: Optional filter on the voice agent that answered the call, such as
+   * agent_9f2ab000-0000-4000-8000-000000000001
+   */
+  agent_id?: string | null;
+
   /**
    * Query param: Optional direction filter: outbound for calls placed from your app,
    * inbound for calls to one of your numbers
@@ -445,6 +522,12 @@ export interface CallListParams extends CallsPageParams {
    */
   from?: string | null;
 
+  /**
+   * Query param: Optional mode filter: inapp for calls routed by your number's
+   * callback URL, agent for calls one of your voice agents answered
+   */
+  mode?: string | null;
+
   /**
    * Query param: Optional filter on the number that owns the call, one of your
    * voice-enabled numbers in E.164 format

package/src/resources/voice/calls/participants.ts

@@ -14,6 +14,8 @@ import { path } from '../../../internal/utils/path';
  * `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent asks what to do with each call on it, and `POST /v3/voice/tokens` mints a short-lived token that lets a user of your app place and receive calls as that number. When a call arrives or a caller presses a key, a signed question is POSTed to the callback URL and the answer decides the call; `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need before a real call reaches it, and `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret. The call events themselves (`call.completed` and the rest) arrive through your webhooks.
  *
  * Every call is a record under `/v3/voice/calls`: read it, list its recordings once one is ready, hang it up, start or stop recording, and add, mute or remove conference participants while it is live. A leg to a phone number runs for at most what your balance affords at the destination's rate.
+ *
+ * **Voice agents.** `POST /v3/voice/agents` creates an agent that answers calls through the Sent Voice Gateway: `session_type` says whether Sent carries the call as text (speech recognised and spoken for the agent) or as audio, `websocket_url` is where the gateway dials the agent for each call (leave it out and the agent dials in with your API key), and `tools`, `transfer_targets`, `fallback` and `limits` say what it may do on a call. The agent's `signing_secret` is shown on create and on `POST /v3/voice/agents/{id}/rotate-secret` only. Voices and languages for text sessions come from `GET /v3/voice/voices`. A number takes calls to an agent once it is bound to it on `/v3/channels/voice`.
  */
 export class Participants extends APIResource {
   /**

package/src/resources/voice/catalogue.ts

@@ -0,0 +1,118 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as WebhooksAPI from '../webhooks';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+
+/**
+ * Phone calls from the numbers you hold, driven by your own callback URL.
+ *
+ * `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent asks what to do with each call on it, and `POST /v3/voice/tokens` mints a short-lived token that lets a user of your app place and receive calls as that number. When a call arrives or a caller presses a key, a signed question is POSTed to the callback URL and the answer decides the call; `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need before a real call reaches it, and `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret. The call events themselves (`call.completed` and the rest) arrive through your webhooks.
+ *
+ * Every call is a record under `/v3/voice/calls`: read it, list its recordings once one is ready, hang it up, start or stop recording, and add, mute or remove conference participants while it is live. A leg to a phone number runs for at most what your balance affords at the destination's rate.
+ *
+ * **Voice agents.** `POST /v3/voice/agents` creates an agent that answers calls through the Sent Voice Gateway: `session_type` says whether Sent carries the call as text (speech recognised and spoken for the agent) or as audio, `websocket_url` is where the gateway dials the agent for each call (leave it out and the agent dials in with your API key), and `tools`, `transfer_targets`, `fallback` and `limits` say what it may do on a call. The agent's `signing_secret` is shown on create and on `POST /v3/voice/agents/{id}/rotate-secret` only. Voices and languages for text sessions come from `GET /v3/voice/voices`. A number takes calls to an agent once it is bound to it on `/v3/channels/voice`.
+ */
+export class Catalogue extends APIResource {
+  /**
+   * The names a voice agent's `speech.voice` and `speech.language` accept, with the
+   * default marked. The list grows as voices are added; a name is never removed
+   * without notice.
+   *
+   * @example
+   * ```ts
+   * const apiResponseOfVoiceCatalogue =
+   *   await client.voice.catalogue.list();
+   * ```
+   */
+  list(
+    params: CatalogueListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<APIResponseOfVoiceCatalogue> {
+    const { 'x-profile-id': xProfileID } = params ?? {};
+    return this._client.get('/v3/voice/voices', {
+      ...options,
+      headers: buildHeaders([
+        { ...(xProfileID != null ? { 'x-profile-id': xProfileID } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface APIResponseOfVoiceCatalogue {
+  /**
+   * The voices and languages a text-session agent may name in its speech settings:
+   * what GET /v3/voice/voices and the admin GET /voice/voices answer, in one shape.
+   */
+  data?: VoiceCatalogue | null;
+
+  /**
+   * Error information
+   */
+  error?: WebhooksAPI.ErrorDetail | null;
+
+  /**
+   * Request and response metadata
+   */
+  meta?: WebhooksAPI.APIMeta;
+
+  /**
+   * Indicates whether the request was successful
+   */
+  success?: boolean;
+}
+
+/**
+ * The voices and languages a text-session agent may name in its speech settings:
+ * what GET /v3/voice/voices and the admin GET /voice/voices answer, in one shape.
+ */
+export interface VoiceCatalogue {
+  /**
+   * BCP 47 tags accepted as speech.language.
+   */
+  languages?: Array<string>;
+
+  voices?: Array<VoiceCatalogueVoice>;
+}
+
+export interface VoiceCatalogueVoice {
+  /**
+   * Whether this is the voice used when an agent names none.
+   */
+  default?: boolean;
+
+  description?: string;
+
+  /**
+   * The language the voice speaks.
+   */
+  language?: string;
+
+  /**
+   * The value to send as speech.voice.
+   */
+  name?: string;
+}
+
+export interface CatalogueListParams {
+  /**
+   * 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 declare namespace Catalogue {
+  export {
+    type APIResponseOfVoiceCatalogue as APIResponseOfVoiceCatalogue,
+    type VoiceCatalogue as VoiceCatalogue,
+    type VoiceCatalogueVoice as VoiceCatalogueVoice,
+    type CatalogueListParams as CatalogueListParams,
+  };
+}

package/src/resources/voice/index.ts

@@ -1,5 +1,31 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Agents,
+  type APIResponseOfVoiceAgent,
+  type APIResponseOfVoiceAgentSecret,
+  type APIResponseOfVoiceAgentsList,
+  type VoiceAgent,
+  type VoiceAgentAudio,
+  type VoiceAgentAudioSpec,
+  type VoiceAgentLimits,
+  type VoiceAgentLimitsSpec,
+  type VoiceAgentParty,
+  type VoiceAgentPartySpec,
+  type VoiceAgentSecret,
+  type VoiceAgentSpeech,
+  type VoiceAgentSpeechSpec,
+  type VoiceAgentTranscripts,
+  type VoiceAgentTranscriptsSpec,
+  type VoiceAgentsList,
+  type AgentCreateParams,
+  type AgentRetrieveParams,
+  type AgentUpdateParams,
+  type AgentListParams,
+  type AgentDeleteParams,
+  type AgentRotateSecretParams,
+  type VoiceAgentsVoiceAgentsPage,
+} from './agents';
 export {
   Calls,
   type APIResponseOfCall,
@@ -18,5 +44,12 @@ export {
   type CallRecordParams,
   type CallsCallsPage,
 } from './calls/index';
+export {
+  Catalogue,
+  type APIResponseOfVoiceCatalogue,
+  type VoiceCatalogue,
+  type VoiceCatalogueVoice,
+  type CatalogueListParams,
+} from './catalogue';
 export { Tokens, type APIResponseOfVoiceToken, type VoiceToken, type TokenCreateParams } from './tokens';
 export { Voice } from './voice';

package/src/resources/voice/tokens.ts

@@ -12,6 +12,8 @@ import { RequestOptions } from '../../internal/request-options';
  * `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent asks what to do with each call on it, and `POST /v3/voice/tokens` mints a short-lived token that lets a user of your app place and receive calls as that number. When a call arrives or a caller presses a key, a signed question is POSTed to the callback URL and the answer decides the call; `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need before a real call reaches it, and `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret. The call events themselves (`call.completed` and the rest) arrive through your webhooks.
  *
  * Every call is a record under `/v3/voice/calls`: read it, list its recordings once one is ready, hang it up, start or stop recording, and add, mute or remove conference participants while it is live. A leg to a phone number runs for at most what your balance affords at the destination's rate.
+ *
+ * **Voice agents.** `POST /v3/voice/agents` creates an agent that answers calls through the Sent Voice Gateway: `session_type` says whether Sent carries the call as text (speech recognised and spoken for the agent) or as audio, `websocket_url` is where the gateway dials the agent for each call (leave it out and the agent dials in with your API key), and `tools`, `transfer_targets`, `fallback` and `limits` say what it may do on a call. The agent's `signing_secret` is shown on create and on `POST /v3/voice/agents/{id}/rotate-secret` only. Voices and languages for text sessions come from `GET /v3/voice/voices`. A number takes calls to an agent once it is bound to it on `/v3/channels/voice`.
  */
 export class Tokens extends APIResource {
   /**

package/src/resources/voice/voice.ts

@@ -1,6 +1,41 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as AgentsAPI from './agents';
+import {
+  APIResponseOfVoiceAgent,
+  APIResponseOfVoiceAgentSecret,
+  APIResponseOfVoiceAgentsList,
+  AgentCreateParams,
+  AgentDeleteParams,
+  AgentListParams,
+  AgentRetrieveParams,
+  AgentRotateSecretParams,
+  AgentUpdateParams,
+  Agents,
+  VoiceAgent,
+  VoiceAgentAudio,
+  VoiceAgentAudioSpec,
+  VoiceAgentLimits,
+  VoiceAgentLimitsSpec,
+  VoiceAgentParty,
+  VoiceAgentPartySpec,
+  VoiceAgentSecret,
+  VoiceAgentSpeech,
+  VoiceAgentSpeechSpec,
+  VoiceAgentTranscripts,
+  VoiceAgentTranscriptsSpec,
+  VoiceAgentsList,
+  VoiceAgentsVoiceAgentsPage,
+} from './agents';
+import * as CatalogueAPI from './catalogue';
+import {
+  APIResponseOfVoiceCatalogue,
+  Catalogue,
+  CatalogueListParams,
+  VoiceCatalogue,
+  VoiceCatalogueVoice,
+} from './catalogue';
 import * as TokensAPI from './tokens';
 import { APIResponseOfVoiceToken, TokenCreateParams, Tokens, VoiceToken } from './tokens';
 import * as CallsAPI from './calls/calls';
@@ -26,10 +61,14 @@ import {
 export class Voice extends APIResource {
   calls: CallsAPI.Calls = new CallsAPI.Calls(this._client);
   tokens: TokensAPI.Tokens = new TokensAPI.Tokens(this._client);
+  agents: AgentsAPI.Agents = new AgentsAPI.Agents(this._client);
+  catalogue: CatalogueAPI.Catalogue = new CatalogueAPI.Catalogue(this._client);
 }
 
 Voice.Calls = Calls;
 Voice.Tokens = Tokens;
+Voice.Agents = Agents;
+Voice.Catalogue = Catalogue;
 
 export declare namespace Voice {
   export {
@@ -57,4 +96,39 @@ export declare namespace Voice {
     type VoiceToken as VoiceToken,
     type TokenCreateParams as TokenCreateParams,
   };
+
+  export {
+    Agents as Agents,
+    type APIResponseOfVoiceAgent as APIResponseOfVoiceAgent,
+    type APIResponseOfVoiceAgentSecret as APIResponseOfVoiceAgentSecret,
+    type APIResponseOfVoiceAgentsList as APIResponseOfVoiceAgentsList,
+    type VoiceAgent as VoiceAgent,
+    type VoiceAgentAudio as VoiceAgentAudio,
+    type VoiceAgentAudioSpec as VoiceAgentAudioSpec,
+    type VoiceAgentLimits as VoiceAgentLimits,
+    type VoiceAgentLimitsSpec as VoiceAgentLimitsSpec,
+    type VoiceAgentParty as VoiceAgentParty,
+    type VoiceAgentPartySpec as VoiceAgentPartySpec,
+    type VoiceAgentSecret as VoiceAgentSecret,
+    type VoiceAgentSpeech as VoiceAgentSpeech,
+    type VoiceAgentSpeechSpec as VoiceAgentSpeechSpec,
+    type VoiceAgentTranscripts as VoiceAgentTranscripts,
+    type VoiceAgentTranscriptsSpec as VoiceAgentTranscriptsSpec,
+    type VoiceAgentsList as VoiceAgentsList,
+    type VoiceAgentsVoiceAgentsPage as VoiceAgentsVoiceAgentsPage,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentRetrieveParams as AgentRetrieveParams,
+    type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
+    type AgentDeleteParams as AgentDeleteParams,
+    type AgentRotateSecretParams as AgentRotateSecretParams,
+  };
+
+  export {
+    Catalogue as Catalogue,
+    type APIResponseOfVoiceCatalogue as APIResponseOfVoiceCatalogue,
+    type VoiceCatalogue as VoiceCatalogue,
+    type VoiceCatalogueVoice as VoiceCatalogueVoice,
+    type CatalogueListParams as CatalogueListParams,
+  };
 }