@zavudev/sdk 0.50.0 → 0.52.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,6 +382,14 @@ 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;
@@ -326,6 +457,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 +599,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/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;
 
   /**
@@ -320,22 +328,21 @@ export interface SenderWebhook {
  *
  * **Inbound events:**
  *
- * - `message.inbound`: New message received from a contact. Reactions are
- *   delivered as `message.inbound` with `messageType='reaction'`. When the contact
- *   replied to (quoted) an earlier message, `data.content` carries the reply
- *   context: `replyToMessageId`, `replyToProviderMessageId`, `replyToFrom`,
- *   `replyToText`, and `replyToMessageType`. `data.providerTimestamp` is the
- *   provider's original receive time in Unix milliseconds (the moment the channel
- *   received the message from the contact — WhatsApp, Telegram, Instagram,
- *   Messenger; `null` for SMS and email). Compare it against the top-level
- *   `timestamp` (when Zavu dispatched the webhook) to detect and ignore delayed
- *   deliveries.
- * - `message.status`: A contact posted a WhatsApp status/story (currently WhatsApp
- *   Alternative only). It is NOT a conversation message and never enters the inbox
- *   — it is delivered only if you subscribe to `message.status`. `data` carries
- *   `from` (the author in E.164), `messageType` (`text`, `image`, `video`,
- *   `audio`), `text` (caption/text when present), `mimetype` (for media stories),
- *   and `providerTimestamp`. Media bytes are not included.
+ * - `message.inbound`: New message received from a contact. `data.conversationId`
+ *   is the inbox thread id (deep-link with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`); it is
+ *   `null` while the conversation row is still being created (the first message of
+ *   a brand-new thread, or several near-simultaneous first messages), where
+ *   `conversation.new` carries the id instead — `GET /v1/messages/{messageId}`
+ *   always has it. Reactions are delivered as `message.inbound` with
+ *   `messageType='reaction'`. When the contact replied to (quoted) an earlier
+ *   message, `data.content` carries the reply context: `replyToMessageId`,
+ *   `replyToProviderMessageId`, `replyToFrom`, `replyToText`, and
+ *   `replyToMessageType`. `data.providerTimestamp` is the provider's original
+ *   receive time in Unix milliseconds (the moment the channel received the message
+ *   from the contact — WhatsApp, Telegram, Instagram, Messenger; `null` for SMS
+ *   and email). Compare it against the top-level `timestamp` (when Zavu dispatched
+ *   the webhook) to detect and ignore delayed deliveries.
  * - `message.unsupported`: Received a message type that is not supported
  *
  * **Broadcast events:**
@@ -345,13 +352,42 @@ export interface SenderWebhook {
  *
  * **Other events:**
  *
- * - `conversation.new`: New conversation started with a contact
+ * - `conversation.new`: New conversation started with a contact. `data` carries
+ *   `conversationId` (the inbox thread id — deep-link with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), the
+ *   `phoneNumber` or `email` key, `channel`, `firstMessageId`, `firstMessageText`,
+ *   and `profileName`.
  * - `template.status_changed`: WhatsApp template approval status changed
  *
  * **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:**
  *
@@ -365,14 +401,18 @@ export type WebhookEvent =
   | 'message.sent'
   | 'message.delivered'
   | 'message.read'
+  | 'message.status'
   | 'message.failed'
   | 'message.inbound'
-  | 'message.status'
   | 'message.unsupported'
   | 'broadcast.status_changed'
   | 'conversation.new'
   | 'template.status_changed'
   | 'invitation.status_changed'
+  | 'call.initiated'
+  | 'call.answered'
+  | 'call.completed'
+  | 'call.failed'
   | 'domain.verified'
   | 'domain.failed';
 
@@ -500,8 +540,18 @@ export interface SenderCreateParams {
   emailReceivingEnabled?: boolean;
 
   /**
-   * Phone number in E.164 format. Required for phone-based channels (SMS, WhatsApp).
-   * Omit for an email-only sender.
+   * 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;
 
@@ -548,6 +598,13 @@ export interface SenderUpdateParams {
    */
   emailReceivingEnabled?: 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.50.0'; // x-release-please-version
+export const VERSION = '0.52.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.50.0";
+export declare const VERSION = "0.52.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.50.0'; // x-release-please-version
+exports.VERSION = '0.52.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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