@zavudev/sdk 0.51.0 → 0.53.0

package/src/resources/senders/agent/agent.ts

@@ -138,6 +138,12 @@ export class AgentResource extends APIResource {
   /**
    * Get statistics for an AI agent including invocations, tokens, and costs.
    *
+   * Covers the messaging channels only. Voice calls are not counted here: a call is
+   * a multi-turn conversation rather than one inbound message and one reply, so it
+   * is recorded as a call, not an execution. An agent that only answers phone calls
+   * reports zeros on every field. Use `GET /v1/calls` for voice activity, duration,
+   * and cost.
+   *
    * @example
    * ```ts
    * const agentStats = await client.senders.agent.stats(
@@ -201,6 +207,12 @@ export interface Agent {
    */
   maxTokens?: number | null;
 
+  /**
+   * Senders this agent answers on. An agent can serve several; `senderId` remains
+   * the primary one, for compatibility.
+   */
+  senderIds?: Array<string>;
+
   stats?: Agent.Stats;
 
   /**
@@ -217,6 +229,13 @@ export interface Agent {
    * Message types that trigger the agent.
    */
   triggerOnMessageTypes?: Array<string>;
+
+  /**
+   * Voice Agent configuration. When present and enabled, the agent can answer
+   * inbound phone calls and place outbound calls with Zavu's managed voice pipeline.
+   * Requires the Voice Agents feature to be enabled for your team.
+   */
+  voice?: Agent.Voice;
 }
 
 export namespace Agent {
@@ -230,6 +249,110 @@ export namespace Agent {
 
     totalTokensUsed?: number;
   }
+
+  /**
+   * Voice Agent configuration. When present and enabled, the agent can answer
+   * inbound phone calls and place outbound calls with Zavu's managed voice pipeline.
+   * Requires the Voice Agents feature to be enabled for your team.
+   */
+  export interface Voice {
+    /**
+     * Whether the agent handles voice calls. When false, the sender's number is not
+     * answered by the voice agent and outbound calls are rejected.
+     */
+    enabled: boolean;
+
+    /**
+     * Opening line the agent speaks when the call connects. If omitted, the agent
+     * waits for the caller to speak first.
+     */
+    greeting?: string;
+
+    /**
+     * Greeting per language, keyed by language code. Used when the caller's language
+     * differs from the one `greeting` is written in.
+     */
+    greetings?: { [key: string]: string };
+
+    /**
+     * Whether the caller can interrupt the agent while it is speaking (barge-in). When
+     * true, the agent stops talking as soon as the caller starts.
+     */
+    interruptible?: boolean;
+
+    /**
+     * BCP-47 language code used for both speech recognition and speech synthesis (e.g.
+     * `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
+     */
+    language?: string;
+
+    /**
+     * Hard limit on call length in minutes. The call ends automatically when reached.
+     */
+    maxCallDurationMinutes?: number;
+
+    /**
+     * How long the agent waits during silence before ending the call.
+     */
+    maxIdleSeconds?: number;
+
+    /**
+     * Model that runs the conversation, co-located in the voice network for lowest
+     * latency. Independent of the model used for text messaging. Derived from the
+     * agent's text model when omitted.
+     */
+    model?: string;
+
+    /**
+     * Whether the call audio is recorded.
+     */
+    recordCalls?: boolean;
+
+    /**
+     * Speech-recognition model. Uses the default when omitted.
+     */
+    sttModel?: string;
+
+    /**
+     * Speech-recognition provider. Uses the default when omitted.
+     */
+    sttProvider?: string;
+
+    /**
+     * E.164 phone number the agent can transfer the call to. When set, the agent is
+     * given a transfer tool it can use to hand the call to a human.
+     */
+    transferPhoneNumber?: string;
+
+    /**
+     * Speech-synthesis provider. Uses the default when omitted.
+     */
+    ttsProvider?: string;
+
+    /**
+     * Identifier of the synthesized voice that speaks. Choose from the voices
+     * available in the dashboard. Uses a neutral default when omitted.
+     */
+    ttsVoiceId?: string;
+
+    /**
+     * What the agent does when an answering machine or voicemail is detected on an
+     * outbound call.
+     */
+    voicemailAction?: 'hangup' | 'leave_message';
+
+    /**
+     * Message spoken when `voicemailAction` is `leave_message`. Falls back to
+     * `greeting` when omitted.
+     */
+    voicemailMessage?: string;
+
+    /**
+     * Speech rate. 1.0 is natural. Only honoured by voices that support rate control;
+     * ignored by the others.
+     */
+    voiceSpeed?: number;
+  }
 }
 
 export interface AgentExecution {
@@ -259,9 +382,25 @@ export interface AgentExecution {
 
   inboundMessageId?: string;
 
+  /**
+   * Knowledge-base chunks retrieved for this answer. Zero on an agent that has
+   * documents attached means the reply was not grounded in them, which is otherwise
+   * indistinguishable from a correct answer in this record. Absent on executions
+   * recorded before this field existed, which is not the same as zero.
+   */
+  knowledgeChunksUsed?: number | null;
+
   responseMessageId?: string | null;
 
   responseText?: string | null;
+
+  /**
+   * Tools the agent called while producing this reply. Zero on an agent that has
+   * tools configured means it answered without calling any — the case where a reply
+   * says it will look something up and nothing ever reaches your endpoint. Absent on
+   * executions recorded before this field existed, which is not the same as zero.
+   */
+  toolCalls?: number | null;
 }
 
 /**
@@ -326,6 +465,119 @@ export interface AgentCreateParams {
   triggerOnChannels?: Array<string>;
 
   triggerOnMessageTypes?: Array<string>;
+
+  /**
+   * Voice Agent configuration. Enable this to let the agent answer and place phone
+   * calls with Zavu's managed voice pipeline. Requires the Voice Agents feature to
+   * be enabled for your team.
+   */
+  voice?: AgentCreateParams.Voice;
+}
+
+export namespace AgentCreateParams {
+  /**
+   * Voice Agent configuration. Enable this to let the agent answer and place phone
+   * calls with Zavu's managed voice pipeline. Requires the Voice Agents feature to
+   * be enabled for your team.
+   */
+  export interface Voice {
+    /**
+     * Whether the agent handles voice calls. When false, the sender's number is not
+     * answered by the voice agent and outbound calls are rejected.
+     */
+    enabled: boolean;
+
+    /**
+     * Opening line the agent speaks when the call connects. If omitted, the agent
+     * waits for the caller to speak first.
+     */
+    greeting?: string;
+
+    /**
+     * Greeting per language, keyed by language code. Used when the caller's language
+     * differs from the one `greeting` is written in.
+     */
+    greetings?: { [key: string]: string };
+
+    /**
+     * Whether the caller can interrupt the agent while it is speaking (barge-in). When
+     * true, the agent stops talking as soon as the caller starts.
+     */
+    interruptible?: boolean;
+
+    /**
+     * BCP-47 language code used for both speech recognition and speech synthesis (e.g.
+     * `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
+     */
+    language?: string;
+
+    /**
+     * Hard limit on call length in minutes. The call ends automatically when reached.
+     */
+    maxCallDurationMinutes?: number;
+
+    /**
+     * How long the agent waits during silence before ending the call.
+     */
+    maxIdleSeconds?: number;
+
+    /**
+     * Model that runs the conversation, co-located in the voice network for lowest
+     * latency. Independent of the model used for text messaging. Derived from the
+     * agent's text model when omitted.
+     */
+    model?: string;
+
+    /**
+     * Whether the call audio is recorded.
+     */
+    recordCalls?: boolean;
+
+    /**
+     * Speech-recognition model. Uses the default when omitted.
+     */
+    sttModel?: string;
+
+    /**
+     * Speech-recognition provider. Uses the default when omitted.
+     */
+    sttProvider?: string;
+
+    /**
+     * E.164 phone number the agent can transfer the call to. When set, the agent is
+     * given a transfer tool it can use to hand the call to a human.
+     */
+    transferPhoneNumber?: string;
+
+    /**
+     * Speech-synthesis provider. Uses the default when omitted.
+     */
+    ttsProvider?: string;
+
+    /**
+     * Identifier of the synthesized voice that speaks. Choose from the voices
+     * available in the dashboard. Uses a neutral default when omitted.
+     */
+    ttsVoiceId?: string;
+
+    /**
+     * What the agent does when an answering machine or voicemail is detected on an
+     * outbound call.
+     */
+    voicemailAction?: 'hangup' | 'leave_message';
+
+    /**
+     * Message spoken when `voicemailAction` is `leave_message`. Falls back to
+     * `greeting` when omitted.
+     */
+    voicemailMessage?: string;
+
+    /**
+     * Speech rate. 1.0 is natural. Only honoured by voices that support rate control;
+     * ignored by the others.
+     */
+    voiceSpeed?: number;
+  }
 }
 
 export interface AgentUpdateParams {
@@ -355,6 +607,119 @@ export interface AgentUpdateParams {
   triggerOnChannels?: Array<string>;
 
   triggerOnMessageTypes?: Array<string>;
+
+  /**
+   * Voice Agent configuration. Patch this object to enable voice, change the
+   * greeting, or adjust call limits. Requires the Voice Agents feature to be enabled
+   * for your team.
+   */
+  voice?: AgentUpdateParams.Voice;
+}
+
+export namespace AgentUpdateParams {
+  /**
+   * Voice Agent configuration. Patch this object to enable voice, change the
+   * greeting, or adjust call limits. Requires the Voice Agents feature to be enabled
+   * for your team.
+   */
+  export interface Voice {
+    /**
+     * Whether the agent handles voice calls. When false, the sender's number is not
+     * answered by the voice agent and outbound calls are rejected.
+     */
+    enabled: boolean;
+
+    /**
+     * Opening line the agent speaks when the call connects. If omitted, the agent
+     * waits for the caller to speak first.
+     */
+    greeting?: string;
+
+    /**
+     * Greeting per language, keyed by language code. Used when the caller's language
+     * differs from the one `greeting` is written in.
+     */
+    greetings?: { [key: string]: string };
+
+    /**
+     * Whether the caller can interrupt the agent while it is speaking (barge-in). When
+     * true, the agent stops talking as soon as the caller starts.
+     */
+    interruptible?: boolean;
+
+    /**
+     * BCP-47 language code used for both speech recognition and speech synthesis (e.g.
+     * `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
+     */
+    language?: string;
+
+    /**
+     * Hard limit on call length in minutes. The call ends automatically when reached.
+     */
+    maxCallDurationMinutes?: number;
+
+    /**
+     * How long the agent waits during silence before ending the call.
+     */
+    maxIdleSeconds?: number;
+
+    /**
+     * Model that runs the conversation, co-located in the voice network for lowest
+     * latency. Independent of the model used for text messaging. Derived from the
+     * agent's text model when omitted.
+     */
+    model?: string;
+
+    /**
+     * Whether the call audio is recorded.
+     */
+    recordCalls?: boolean;
+
+    /**
+     * Speech-recognition model. Uses the default when omitted.
+     */
+    sttModel?: string;
+
+    /**
+     * Speech-recognition provider. Uses the default when omitted.
+     */
+    sttProvider?: string;
+
+    /**
+     * E.164 phone number the agent can transfer the call to. When set, the agent is
+     * given a transfer tool it can use to hand the call to a human.
+     */
+    transferPhoneNumber?: string;
+
+    /**
+     * Speech-synthesis provider. Uses the default when omitted.
+     */
+    ttsProvider?: string;
+
+    /**
+     * Identifier of the synthesized voice that speaks. Choose from the voices
+     * available in the dashboard. Uses a neutral default when omitted.
+     */
+    ttsVoiceId?: string;
+
+    /**
+     * What the agent does when an answering machine or voicemail is detected on an
+     * outbound call.
+     */
+    voicemailAction?: 'hangup' | 'leave_message';
+
+    /**
+     * Message spoken when `voicemailAction` is `leave_message`. Falls back to
+     * `greeting` when omitted.
+     */
+    voicemailMessage?: string;
+
+    /**
+     * Speech rate. 1.0 is natural. Only honoured by voices that support rate control;
+     * ignored by the others.
+     */
+    voiceSpeed?: number;
+  }
 }
 
 AgentResource.Executions = Executions;

package/src/resources/senders/agent/executions.ts

@@ -34,6 +34,11 @@ export class Executions extends APIResource {
   /**
    * List recent agent executions with pagination.
    *
+   * An execution is one inbound message answered by the agent, so this covers the
+   * messaging channels only. Voice calls are never listed here regardless of how
+   * many the agent handled. Use `GET /v1/calls` (and `GET /v1/calls/{callId}` for
+   * the transcript) for voice.
+   *
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.

package/src/resources/senders/agent/tools.ts

@@ -118,7 +118,16 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Test a tool by triggering its webhook with test parameters.
+   * Run a tool with the parameters you supply and return what it answered.
+   *
+   * The call is synchronous: the response carries the tool's status, body, and
+   * duration, so a green result is evidence the tool ran rather than evidence it was
+   * accepted. Each run is also recorded and readable afterwards via
+   * `GET /v1/senders/{senderId}/agent/tools/{toolId}/test-runs`.
+   *
+   * A tool that answers with an error is reported as a run with `success: false` —
+   * the endpoint itself still returns 200. This fires the tool's real webhook, so a
+   * test has whatever side effects the tool has.
    *
    * @example
    * ```ts
@@ -194,7 +203,54 @@ export interface ToolUpdateResponse {
 }
 
 export interface ToolTestResponse {
-  scheduled: boolean;
+  /**
+   * One run of a tool triggered from the test endpoint. Recorded so a test is
+   * verifiable after the fact rather than only visible in the response.
+   */
+  run: ToolTestResponse.Run;
+}
+
+export namespace ToolTestResponse {
+  /**
+   * One run of a tool triggered from the test endpoint. Recorded so a test is
+   * verifiable after the fact rather than only visible in the response.
+   */
+  export interface Run {
+    id: string;
+
+    createdAt: string;
+
+    durationMs: number;
+
+    /**
+     * Whether the tool returned without error. A tool that answered with a non-2xx
+     * status is a failed run, not an error of this endpoint.
+     */
+    success: boolean;
+
+    toolId: string;
+
+    /**
+     * Why the run failed, when it did.
+     */
+    error?: string | null;
+
+    /**
+     * The parameters the tool was called with.
+     */
+    params?: { [key: string]: unknown };
+
+    /**
+     * The tool's response body, truncated.
+     */
+    response?: string | null;
+
+    /**
+     * HTTP status the tool's webhook returned. Absent for tools that do not go over
+     * HTTP.
+     */
+    statusCode?: number | null;
+  }
 }
 
 export interface ToolCreateParams {

package/src/resources/senders/senders.ts

@@ -195,6 +195,14 @@ export interface Sender {
    */
   phoneNumber: string;
 
+  /**
+   * Channels this sender can actually send on right now, computed from its
+   * configuration. Empty means the sender cannot send or receive anything yet: a
+   * phoneNumber alone does not enable SMS or voice. Check this rather than inferring
+   * capability from phoneNumber or emailAddress.
+   */
+  channels?: Array<string>;
+
   createdAt?: string;
 
   /**
@@ -354,7 +362,32 @@ export interface SenderWebhook {
  * **Partner events:**
  *
  * - `invitation.status_changed`: A partner invitation status changed (pending,
- *   in_progress, completed, cancelled)
+ *   in_progress, completed, cancelled, failed). `data` carries `invitationId`,
+ *   `clientName`, `clientEmail`, `connectionType` (`whatsapp_waba` or
+ *   `messenger`), `previousStatus`, and `currentStatus`. On `completed` it also
+ *   carries `senderId` and `connectedAccount` (`channel`, `id`, `name`) — the
+ *   WhatsApp number or Facebook Page that was linked. On `failed` it carries
+ *   `failureReason`; the invitation link stays usable, so a client can retry it.
+ *
+ * **Voice Agent events:** For every voice event, `data` carries `callId`,
+ * `direction`, `from`, `to`, `status`, `durationSeconds`, `endReason`, and
+ * `transcriptAvailable`. The terminal events (`call.completed`, `call.failed`)
+ * additionally carry `cost` — what the call was billed, in USD, combining
+ * telephony and the managed voice pipeline — and `currency`. They are dispatched
+ * after the call is charged, so `cost` is populated rather than zero; telephony
+ * can still be settling on an outbound call, in which case
+ * `GET /v1/calls/{callId}` holds the reconciled figure.
+ *
+ * - `call.initiated`: An outbound call was created and is dialing, or an inbound
+ *   call was received. `data.status` = `ringing`
+ * - `call.answered`: The call was answered and the voice agent is connected.
+ *   `data.status` = `in_progress`
+ * - `call.completed`: The call ended after a conversation. `data.status` =
+ *   `completed`; `durationSeconds` and `endReason` describe how it ended, and
+ *   `transcriptAvailable` indicates whether a transcript can be fetched.
+ * - `call.failed`: The call could not be completed (busy, no answer, canceled, or
+ *   an error). `data.status` is the terminal status and `endReason` explains the
+ *   cause.
  *
  * **Custom domain events:**
  *
@@ -368,6 +401,7 @@ export type WebhookEvent =
   | 'message.sent'
   | 'message.delivered'
   | 'message.read'
+  | 'message.status'
   | 'message.failed'
   | 'message.inbound'
   | 'message.unsupported'
@@ -375,6 +409,10 @@ export type WebhookEvent =
   | 'conversation.new'
   | 'template.status_changed'
   | 'invitation.status_changed'
+  | 'call.initiated'
+  | 'call.answered'
+  | 'call.completed'
+  | 'call.failed'
   | 'domain.verified'
   | 'domain.failed';
 
@@ -502,8 +540,26 @@ export interface SenderCreateParams {
   emailReceivingEnabled?: boolean;
 
   /**
-   * Phone number in E.164 format. Required for phone-based channels (SMS, WhatsApp).
-   * Omit for an email-only sender.
+   * Enable the one-way SMS channel (`sms_oneway`). Needs nothing else — no phone
+   * number, no credential — so it is the fastest way to get a sender that can send.
+   * Recipients cannot reply. Confirm with `sms_oneway` in the `channels` array on
+   * the response.
+   */
+  enableSmsOneway?: boolean;
+
+  /**
+   * Let this sender place and answer phone calls. Requires `phoneNumber`; enabling
+   * it without one returns 400. Check the `channels` array on the response to
+   * confirm `voice` is on.
+   */
+  enableVoice?: boolean;
+
+  /**
+   * Phone number in E.164 format, and it must be a number your project already owns
+   * (see `GET /v1/phone-numbers`). The number is routed to the sender as part of
+   * this call, which is what turns the SMS channel on. Passing a number the project
+   * does not own, or one already attached to another sender, returns 400 rather than
+   * creating a sender that cannot send. Omit for an email-only sender.
    */
   phoneNumber?: string;
 
@@ -550,6 +606,20 @@ export interface SenderUpdateParams {
    */
   emailReceivingEnabled?: boolean;
 
+  /**
+   * Turn the one-way SMS channel on or off. Enabling needs nothing else and takes
+   * effect immediately; disabling removes the channel from the sender. Confirm with
+   * the `channels` array on the response.
+   */
+  enableSmsOneway?: boolean;
+
+  /**
+   * Turn the voice channel on or off. The sender must already have a phone number
+   * provisioned for calls; enabling it otherwise returns 400 instead of storing a
+   * flag that changes nothing. Confirm with the `channels` array on the response.
+   */
+  enableVoice?: boolean;
+
   name?: string;
 
   setAsDefault?: boolean;

package/src/resources/templates.ts

@@ -210,7 +210,7 @@ export namespace Template {
 
     text?: string;
 
-    type?: 'quick_reply' | 'url' | 'phone' | 'otp';
+    type?: 'quick_reply' | 'url' | 'phone' | 'otp' | 'request_contact_info';
 
     url?: string;
   }
@@ -306,9 +306,12 @@ export interface TemplateCreateParams {
 
 export namespace TemplateCreateParams {
   export interface Button {
-    text: string;
-
-    type: 'quick_reply' | 'url' | 'phone' | 'otp';
+    /**
+     * `request_contact_info` renders a fixed **Share Contact Info** button that asks
+     * the recipient to share their phone number — useful when a contact adopted a
+     * WhatsApp username and you only know their BSUID. It takes no other fields.
+     */
+    type: 'quick_reply' | 'url' | 'phone' | 'otp' | 'request_contact_info';
 
     /**
      * Sample value Meta uses to review templates with a dynamic URL button.
@@ -335,6 +338,12 @@ export namespace TemplateCreateParams {
      */
     signatureHash?: string;
 
+    /**
+     * Button label. Required for every type except `request_contact_info`, whose label
+     * is fixed by WhatsApp.
+     */
+    text?: string;
+
     /**
      * Button destination. Use `{{1}}` exactly once for a dynamic URL (e.g.
      * `https://example.com/orders/{{1}}`); WhatsApp only accepts the strict `{{1}}`

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.51.0'; // x-release-please-version
+export const VERSION = '0.53.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.51.0";
+export declare const VERSION = "0.53.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.51.0";
+export declare const VERSION = "0.53.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.51.0'; // x-release-please-version
+exports.VERSION = '0.53.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.51.0'; // x-release-please-version
+export const VERSION = '0.53.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map