@zavudev/sdk 0.59.1 → 0.60.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.60.1 (unreleased)
+
+### Documentation
+
+* **calls:** `VoiceCall.cost` and the `call.completed` / `call.failed` webhook
+  descriptions say the cost can grow after the call ends: a premium model's
+  tokens are charged between 30 minutes and 24 hours later.
+
+## 0.60.0 (unreleased)
+
+### Features
+
+* **v2/contacts:** `Contact.whatsapp` (`ContactWhatsapp`: `bsuid`, `username`),
+  regenerated from the spec, which already returned it.
+
+### Documentation
+
+* **10dlc:** `TenDlcBrandCreateRequest.ein` is required to submit every entity
+  type except `SOLE_PROPRIETOR`, and a sole proprietor's `phone` must be a
+  mobile number. The `submit` `400` names the missing EIN.
+* **webhooks:** `message.inbound` and `contact.identity_linked` descriptions
+  regenerated from the spec (BSUID, `contactId`, `conversationId`).
+
 ## 0.59.1 (unreleased)
 
 ### Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zavudev/sdk",
-  "version": "0.59.1",
+  "version": "0.60.1",
   "description": "The official TypeScript library for the Zavudev API",
   "author": "Zavudev <hi@zavu.dev>",
   "types": "./index.d.ts",

package/src/types.ts

@@ -926,11 +926,16 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  * **Inbound events:**
  * - `message.inbound`: New message received from a contact. `data.conversationId`,
  *   the inbox thread id (deep-link with
- *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is sent on
- *   **email** messages only, and is `null` there on the first message of a
- *   brand-new thread. On every other channel it is absent: read it from `GET
- *   /v1/messages/{messageId}`, which always has it, or from `conversation.new` for
- *   a new contact. Reactions are delivered as `message.inbound` with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is always
+ *   set: the webhook is sent once the message has been filed in its thread, so the
+ *   first message of a new thread carries the same id as `conversation.new`.
+ *   `data.contactId` is the Zavu contact, and unlike `data.from` it does not
+ *   change when a WhatsApp contact's identifier switches from a business-scoped
+ *   user ID (BSUID) to a phone number, unless the switch reveals two contacts for
+ *   one person; they are then merged and `contact.identity_linked` names the one
+ *   that went away in `mergedContactId`. On WhatsApp, `data.whatsapp` carries the
+ *   contact's `bsuid` and `username` when known. Reactions carry none of these
+ *   three. 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
@@ -956,6 +961,21 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), the
  *   `phoneNumber` or `email` key, `channel`, `firstMessageId`, `firstMessageText`,
  *   and `profileName`.
+ * - `contact.identity_linked`: A WhatsApp contact known by BSUID was tied to a
+ *   phone number, a contact known by phone received a BSUID, or a contact changed
+ *   their number. `data` carries `contactId`, `bsuid`, `phoneNumber` and `reason`:
+ *   `provider_reported` (WhatsApp sent the phone and the BSUID together on an
+ *   inbound message), `contact_shared` (the contact shared their phone number in
+ *   reply to a `request_contact_info` message), `phone_changed` (the contact
+ *   changed their number; `previousPhoneNumber` carries the old one, and `bsuid`
+ *   is `null` when WhatsApp never reported one for the contact), or
+ *   `bsuid_changed` (WhatsApp reported a new BSUID for the same number).
+ *   `contactId` is the contact that remains if two were merged, and
+ *   `mergedContactId` the one folded into it. `previousBsuid` is a BSUID you may
+ *   have stored that no longer identifies the contact. Sent once per link, not on
+ *   every message. `data.from` on `message.inbound` is the phone only when
+ *   WhatsApp includes it, so it can still be the BSUID afterwards; key on
+ *   `contactId`.
  * - `template.status_changed`: WhatsApp template approval status changed. `data`
  *   carries `templateId`, `name`, `previousStatus`, `currentStatus`,
  *   `rejectionReason`, and `category` — the category Meta currently bills the
@@ -986,9 +1006,10 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  * 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.
+ * `cost` is populated rather than zero. It can still grow afterwards: telephony
+ * can be settling on an outbound call, and on an agent that runs a premium model
+ * the model's tokens are charged between 30 minutes and 24 hours after the call
+ * ends. `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.
@@ -1017,6 +1038,7 @@ export type WebhookEvent =
   | 'message.unsupported'
   | 'broadcast.status_changed'
   | 'conversation.new'
+  | 'contact.identity_linked'
   | 'template.status_changed'
   | 'invitation.status_changed'
   | 'call.initiated'
@@ -1067,14 +1089,29 @@ export interface WebhookMessageData {
   messageType?: MessageType;
   /**
    * ID of the conversation (inbox thread) this message belongs to. Sent on
-   * `message.inbound` for **email** messages only; on SMS, WhatsApp, Telegram,
-   * Instagram and Messenger it is absent. Use it to deep-link to the dashboard
-   * inbox: `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. On
-   * email it is `null` on the first message of a brand-new thread. In every case,
-   * fetch it via `GET /v1/messages/{messageId}`, whose `conversationId` is always
-   * populated, or take it from the `conversation.new` event for a new contact.
+   * `message.inbound` on every channel, except for reactions. Use it to deep-link to
+   * the dashboard inbox:
+   * `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. The webhook
+   * is sent once the message has been filed in its thread, so this is always the
+   * thread the message is in: on the first message of a new thread it is the id
+   * `conversation.new` carries, and on the WhatsApp message that ties a BSUID to a
+   * phone number it is the thread that remains once the two are joined.
    */
   conversationId?: string | null;
+  /**
+   * ID of the Zavu contact that sent the message. Sent on `message.inbound` on every
+   * channel, except for reactions. It does not change when a WhatsApp contact's
+   * `from` switches from a business-scoped user ID (BSUID) to a phone number, so use
+   * it, not `from`, as your key for the person. `null` only when no contact could be
+   * resolved.
+   */
+  contactId?: string | null;
+  /**
+   * WhatsApp identity of the sender. Present on WhatsApp `message.inbound` when Zavu
+   * knows the sender's business-scoped user ID (BSUID), and absent otherwise. Same
+   * shape as `whatsapp` on a contact or a conversation.
+   */
+  whatsapp?: WebhookMessageDataWhatsapp;
   /**
    * Text body or media caption. Present on `message.inbound` when the message has
    * text.
@@ -1102,6 +1139,16 @@ export interface WebhookMessageData {
   referral?: AdReferral;
 }
 
+export interface WebhookMessageDataWhatsapp {
+  /**
+   * Business-scoped user ID. Stable for the person on your WhatsApp Business
+   * Account, whether or not `from` is a phone number.
+   */
+  bsuid: string;
+  /** The WhatsApp username, when the sender has one and Meta reported it. */
+  username?: string;
+}
+
 /** Webhook configuration for the sender. */
 export interface SenderWebhook {
   /** HTTPS URL that will receive webhook events. */
@@ -1374,6 +1421,13 @@ export interface Contact {
   countryCode?: string;
   /** Contact's WhatsApp profile name. Only available for WhatsApp contacts. */
   profileName?: string | null;
+  /**
+   * WhatsApp identity. Present when Zavu has a business-scoped user ID (BSUID) for
+   * the contact, and absent otherwise. A contact with a username can be reached
+   * under its BSUID, its phone number, or both; they are the same contact. Look one
+   * up by BSUID with the `bsuid` query parameter of the list endpoint.
+   */
+  whatsapp?: ContactWhatsapp;
   /** List of available messaging channels for this contact. */
   availableChannels: Array<string>;
   /** Preferred channel for this contact. */
@@ -1387,6 +1441,13 @@ export interface Contact {
   updatedAt?: string;
 }
 
+export interface ContactWhatsapp {
+  /** Business-scoped user ID. Can be used as `to` when sending. */
+  bsuid: string;
+  /** The WhatsApp username, when Meta reported one. */
+  username?: string;
+}
+
 export type ContactDefaultChannel =
   | 'sms'
   | 'whatsapp'
@@ -3112,12 +3173,19 @@ export interface TenDlcBrandCreateRequest {
   displayName: string;
   /** Legal company name. */
   companyName?: string;
-  /** Employer Identification Number (format: XX-XXXXXXX). */
+  /**
+   * Employer Identification Number (format: XX-XXXXXXX). Required to submit every
+   * entity type except `SOLE_PROPRIETOR`: a brand without it can be created as a
+   * draft, and `POST /v1/10dlc/brands/{brandId}/submit` refuses it with `400`.
+   */
   ein?: string;
   firstName?: string;
   lastName?: string;
   email: string;
-  /** Contact phone in E.164 format. */
+  /**
+   * Contact phone in E.164 format. For a `SOLE_PROPRIETOR`, a mobile number: the
+   * carrier texts a verification code to it.
+   */
   phone: string;
   street: string;
   city: string;
@@ -3635,7 +3703,9 @@ export interface VoiceCall {
   transcript?: Array<VoiceCallTurn>;
   /**
    * Total cost of the call in USD, combining the managed voice pipeline per-minute
-   * charge and telephony. Available once the call has ended.
+   * charge, telephony, and, on an agent that runs a premium model, that model's
+   * tokens. Available once the call has ended. Tokens are charged between 30 minutes
+   * and 24 hours after the call ends, so the figure can grow until then.
    */
   cost?: number | null;
   /** Arbitrary metadata you attached when creating the call. */
@@ -4767,6 +4837,13 @@ export interface ContactsListParams {
    * start a new pagination run when the search term changes.
    */
   search?: string;
+  /**
+   * Exact WhatsApp business-scoped user ID (e.g. `CO.13491208655302741918`). Returns
+   * the contact that holds it, or an empty list. Combines with `phoneNumber` and
+   * `tag` as a filter, and cannot be combined with `search` (400). A value that is
+   * not shaped like a BSUID returns 400.
+   */
+  bsuid?: string;
   /**
    * Tag name. Repeatable: `?tag=vip&tag=chile` returns contacts carrying **every**
    * tag given, not any of them — the same rule the dashboard filter applies.

package/src/v2/types.ts

@@ -652,6 +652,13 @@ export interface Contact {
   countryCode?: string;
   /** Contact's WhatsApp profile name. Only available for WhatsApp contacts. */
   profileName?: string | null;
+  /**
+   * WhatsApp identity. Present when Zavu has a business-scoped user ID (BSUID) for
+   * the contact, and absent otherwise. A contact with a username can be reached
+   * under its BSUID, its phone number, or both; they are the same contact. Look one
+   * up by BSUID with the `bsuid` query parameter of the list endpoint.
+   */
+  whatsapp?: ContactWhatsapp;
   /** List of available messaging channels for this contact. */
   availableChannels: Array<string>;
   /** Preferred channel for this contact. */
@@ -665,6 +672,13 @@ export interface Contact {
   updatedAt?: string;
 }
 
+export interface ContactWhatsapp {
+  /** Business-scoped user ID. Can be used as `to` when sending. */
+  bsuid: string;
+  /** The WhatsApp username, when Meta reported one. */
+  username?: string;
+}
+
 export type ContactDefaultChannel =
   | 'sms'
   | 'whatsapp'
@@ -1684,11 +1698,16 @@ export interface TemplateSubmitRequest {
  * **Inbound events:**
  * - `message.inbound`: New message received from a contact. `data.conversationId`,
  *   the inbox thread id (deep-link with
- *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is sent on
- *   **email** messages only, and is `null` there on the first message of a
- *   brand-new thread. On every other channel it is absent: read it from `GET
- *   /v2/messages/{messageId}`, which always has it, or from `conversation.new` for
- *   a new contact. Reactions are delivered as `message.inbound` with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is always
+ *   set: the webhook is sent once the message has been filed in its thread, so the
+ *   first message of a new thread carries the same id as `conversation.new`.
+ *   `data.contactId` is the Zavu contact, and unlike `data.from` it does not
+ *   change when a WhatsApp contact's identifier switches from a business-scoped
+ *   user ID (BSUID) to a phone number, unless the switch reveals two contacts for
+ *   one person; they are then merged and `contact.identity_linked` names the one
+ *   that went away in `mergedContactId`. On WhatsApp, `data.whatsapp` carries the
+ *   contact's `bsuid` and `username` when known. Reactions carry none of these
+ *   three. 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
@@ -1714,6 +1733,21 @@ export interface TemplateSubmitRequest {
  *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), the
  *   `phoneNumber` or `email` key, `channel`, `firstMessageId`, `firstMessageText`,
  *   and `profileName`.
+ * - `contact.identity_linked`: A WhatsApp contact known by BSUID was tied to a
+ *   phone number, a contact known by phone received a BSUID, or a contact changed
+ *   their number. `data` carries `contactId`, `bsuid`, `phoneNumber` and `reason`:
+ *   `provider_reported` (WhatsApp sent the phone and the BSUID together on an
+ *   inbound message), `contact_shared` (the contact shared their phone number in
+ *   reply to a `request_contact_info` message), `phone_changed` (the contact
+ *   changed their number; `previousPhoneNumber` carries the old one, and `bsuid`
+ *   is `null` when WhatsApp never reported one for the contact), or
+ *   `bsuid_changed` (WhatsApp reported a new BSUID for the same number).
+ *   `contactId` is the contact that remains if two were merged, and
+ *   `mergedContactId` the one folded into it. `previousBsuid` is a BSUID you may
+ *   have stored that no longer identifies the contact. Sent once per link, not on
+ *   every message. `data.from` on `message.inbound` is the phone only when
+ *   WhatsApp includes it, so it can still be the BSUID afterwards; key on
+ *   `contactId`.
  * - `template.status_changed`: WhatsApp template approval status changed. `data`
  *   carries `templateId`, `name`, `previousStatus`, `currentStatus`,
  *   `rejectionReason`, and `category` — the category Meta currently bills the
@@ -1743,9 +1777,10 @@ export interface TemplateSubmitRequest {
  * 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.
+ * `cost` is populated rather than zero. It can still grow afterwards: telephony
+ * can be settling on an outbound call, and on an agent that runs a premium model
+ * the model's tokens are charged between 30 minutes and 24 hours after the call
+ * ends. `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.
@@ -1773,6 +1808,7 @@ export type WebhookEvent =
   | 'message.unsupported'
   | 'broadcast.status_changed'
   | 'conversation.new'
+  | 'contact.identity_linked'
   | 'template.status_changed'
   | 'invitation.status_changed'
   | 'call.initiated'
@@ -1805,14 +1841,29 @@ export interface WebhookMessageData {
   messageType?: MessageType;
   /**
    * ID of the conversation (inbox thread) this message belongs to. Sent on
-   * `message.inbound` for **email** messages only; on SMS, WhatsApp, Telegram,
-   * Instagram and Messenger it is absent. Use it to deep-link to the dashboard
-   * inbox: `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. On
-   * email it is `null` on the first message of a brand-new thread. In every case,
-   * fetch it via `GET /v2/messages/{messageId}`, whose `conversationId` is always
-   * populated, or take it from the `conversation.new` event for a new contact.
+   * `message.inbound` on every channel, except for reactions. Use it to deep-link to
+   * the dashboard inbox:
+   * `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. The webhook
+   * is sent once the message has been filed in its thread, so this is always the
+   * thread the message is in: on the first message of a new thread it is the id
+   * `conversation.new` carries, and on the WhatsApp message that ties a BSUID to a
+   * phone number it is the thread that remains once the two are joined.
    */
   conversationId?: string | null;
+  /**
+   * ID of the Zavu contact that sent the message. Sent on `message.inbound` on every
+   * channel, except for reactions. It does not change when a WhatsApp contact's
+   * `from` switches from a business-scoped user ID (BSUID) to a phone number, so use
+   * it, not `from`, as your key for the person. `null` only when no contact could be
+   * resolved.
+   */
+  contactId?: string | null;
+  /**
+   * WhatsApp identity of the sender. Present on WhatsApp `message.inbound` when Zavu
+   * knows the sender's business-scoped user ID (BSUID), and absent otherwise. Same
+   * shape as `whatsapp` on a contact or a conversation.
+   */
+  whatsapp?: WebhookMessageDataWhatsapp;
   /**
    * Text body or media caption. Present on `message.inbound` when the message has
    * text.
@@ -1840,6 +1891,16 @@ export interface WebhookMessageData {
   referral?: AdReferral;
 }
 
+export interface WebhookMessageDataWhatsapp {
+  /**
+   * Business-scoped user ID. Stable for the person on your WhatsApp Business
+   * Account, whether or not `from` is a phone number.
+   */
+  bsuid: string;
+  /** The WhatsApp username, when the sender has one and Meta reported it. */
+  username?: string;
+}
+
 /**
  * What a `POST` to your /v2 webhook carries. Signed like every Zavu webhook
  * (`X-Zavu-Signature`, with the webhook's `signatureVersion`); the event name is
@@ -2323,6 +2384,13 @@ export interface ConversationsListMessagesParams {
 /** Params for `contacts.list`. */
 export interface ContactsListParams {
   search?: string;
+  /**
+   * Exact WhatsApp business-scoped user ID (e.g. `CO.13491208655302741918`). Returns
+   * the contact that holds it, or an empty list. Combines with `phoneNumber` and
+   * `tag` as a filter, and cannot be combined with `search` (400). A value that is
+   * not shaped like a BSUID returns 400.
+   */
+  bsuid?: string;
   tag?: Array<string>;
   /** @defaultValue `50` */
   limit?: number;

package/src/version.ts

@@ -1,3 +1,3 @@
 // Generated by zavu-codegen from apps/docs/openapi.json. Do not edit: run `bun run codegen`.
 
-export const VERSION = '0.59.1'; // x-release-please-version
+export const VERSION = '0.60.1'; // x-release-please-version

package/types.d.mts

@@ -844,11 +844,16 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  * **Inbound events:**
  * - `message.inbound`: New message received from a contact. `data.conversationId`,
  *   the inbox thread id (deep-link with
- *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is sent on
- *   **email** messages only, and is `null` there on the first message of a
- *   brand-new thread. On every other channel it is absent: read it from `GET
- *   /v1/messages/{messageId}`, which always has it, or from `conversation.new` for
- *   a new contact. Reactions are delivered as `message.inbound` with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is always
+ *   set: the webhook is sent once the message has been filed in its thread, so the
+ *   first message of a new thread carries the same id as `conversation.new`.
+ *   `data.contactId` is the Zavu contact, and unlike `data.from` it does not
+ *   change when a WhatsApp contact's identifier switches from a business-scoped
+ *   user ID (BSUID) to a phone number, unless the switch reveals two contacts for
+ *   one person; they are then merged and `contact.identity_linked` names the one
+ *   that went away in `mergedContactId`. On WhatsApp, `data.whatsapp` carries the
+ *   contact's `bsuid` and `username` when known. Reactions carry none of these
+ *   three. 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
@@ -874,6 +879,21 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), the
  *   `phoneNumber` or `email` key, `channel`, `firstMessageId`, `firstMessageText`,
  *   and `profileName`.
+ * - `contact.identity_linked`: A WhatsApp contact known by BSUID was tied to a
+ *   phone number, a contact known by phone received a BSUID, or a contact changed
+ *   their number. `data` carries `contactId`, `bsuid`, `phoneNumber` and `reason`:
+ *   `provider_reported` (WhatsApp sent the phone and the BSUID together on an
+ *   inbound message), `contact_shared` (the contact shared their phone number in
+ *   reply to a `request_contact_info` message), `phone_changed` (the contact
+ *   changed their number; `previousPhoneNumber` carries the old one, and `bsuid`
+ *   is `null` when WhatsApp never reported one for the contact), or
+ *   `bsuid_changed` (WhatsApp reported a new BSUID for the same number).
+ *   `contactId` is the contact that remains if two were merged, and
+ *   `mergedContactId` the one folded into it. `previousBsuid` is a BSUID you may
+ *   have stored that no longer identifies the contact. Sent once per link, not on
+ *   every message. `data.from` on `message.inbound` is the phone only when
+ *   WhatsApp includes it, so it can still be the BSUID afterwards; key on
+ *   `contactId`.
  * - `template.status_changed`: WhatsApp template approval status changed. `data`
  *   carries `templateId`, `name`, `previousStatus`, `currentStatus`,
  *   `rejectionReason`, and `category` — the category Meta currently bills the
@@ -904,9 +924,10 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  * 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.
+ * `cost` is populated rather than zero. It can still grow afterwards: telephony
+ * can be settling on an outbound call, and on an agent that runs a premium model
+ * the model's tokens are charged between 30 minutes and 24 hours after the call
+ * ends. `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.
@@ -924,7 +945,7 @@ export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
  * - `domain.failed`: A custom email domain failed verification or is partially
  *   verified
  */
-export type WebhookEvent = 'message.queued' | 'message.sent' | 'message.delivered' | 'message.read' | 'message.status' | 'message.failed' | 'message.inbound' | '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';
+export type WebhookEvent = 'message.queued' | 'message.sent' | 'message.delivered' | 'message.read' | 'message.status' | 'message.failed' | 'message.inbound' | 'message.unsupported' | 'broadcast.status_changed' | 'conversation.new' | 'contact.identity_linked' | 'template.status_changed' | 'invitation.status_changed' | 'call.initiated' | 'call.answered' | 'call.completed' | 'call.failed' | 'domain.verified' | 'domain.failed';
 /** Webhook payload structure sent to your endpoint. */
 export interface WebhookPayload {
     /** Unique event identifier. */
@@ -967,14 +988,29 @@ export interface WebhookMessageData {
     messageType?: MessageType;
     /**
      * ID of the conversation (inbox thread) this message belongs to. Sent on
-     * `message.inbound` for **email** messages only; on SMS, WhatsApp, Telegram,
-     * Instagram and Messenger it is absent. Use it to deep-link to the dashboard
-     * inbox: `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. On
-     * email it is `null` on the first message of a brand-new thread. In every case,
-     * fetch it via `GET /v1/messages/{messageId}`, whose `conversationId` is always
-     * populated, or take it from the `conversation.new` event for a new contact.
+     * `message.inbound` on every channel, except for reactions. Use it to deep-link to
+     * the dashboard inbox:
+     * `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. The webhook
+     * is sent once the message has been filed in its thread, so this is always the
+     * thread the message is in: on the first message of a new thread it is the id
+     * `conversation.new` carries, and on the WhatsApp message that ties a BSUID to a
+     * phone number it is the thread that remains once the two are joined.
      */
     conversationId?: string | null;
+    /**
+     * ID of the Zavu contact that sent the message. Sent on `message.inbound` on every
+     * channel, except for reactions. It does not change when a WhatsApp contact's
+     * `from` switches from a business-scoped user ID (BSUID) to a phone number, so use
+     * it, not `from`, as your key for the person. `null` only when no contact could be
+     * resolved.
+     */
+    contactId?: string | null;
+    /**
+     * WhatsApp identity of the sender. Present on WhatsApp `message.inbound` when Zavu
+     * knows the sender's business-scoped user ID (BSUID), and absent otherwise. Same
+     * shape as `whatsapp` on a contact or a conversation.
+     */
+    whatsapp?: WebhookMessageDataWhatsapp;
     /**
      * Text body or media caption. Present on `message.inbound` when the message has
      * text.
@@ -1001,6 +1037,15 @@ export interface WebhookMessageData {
      */
     referral?: AdReferral;
 }
+export interface WebhookMessageDataWhatsapp {
+    /**
+     * Business-scoped user ID. Stable for the person on your WhatsApp Business
+     * Account, whether or not `from` is a phone number.
+     */
+    bsuid: string;
+    /** The WhatsApp username, when the sender has one and Meta reported it. */
+    username?: string;
+}
 /** Webhook configuration for the sender. */
 export interface SenderWebhook {
     /** HTTPS URL that will receive webhook events. */
@@ -1258,6 +1303,13 @@ export interface Contact {
     countryCode?: string;
     /** Contact's WhatsApp profile name. Only available for WhatsApp contacts. */
     profileName?: string | null;
+    /**
+     * WhatsApp identity. Present when Zavu has a business-scoped user ID (BSUID) for
+     * the contact, and absent otherwise. A contact with a username can be reached
+     * under its BSUID, its phone number, or both; they are the same contact. Look one
+     * up by BSUID with the `bsuid` query parameter of the list endpoint.
+     */
+    whatsapp?: ContactWhatsapp;
     /** List of available messaging channels for this contact. */
     availableChannels: Array<string>;
     /** Preferred channel for this contact. */
@@ -1272,6 +1324,12 @@ export interface Contact {
     createdAt: string;
     updatedAt?: string;
 }
+export interface ContactWhatsapp {
+    /** Business-scoped user ID. Can be used as `to` when sending. */
+    bsuid: string;
+    /** The WhatsApp username, when Meta reported one. */
+    username?: string;
+}
 export type ContactDefaultChannel = 'sms' | 'whatsapp' | 'telegram' | 'email' | 'instagram' | 'messenger' | 'voice';
 export interface ContactUpdateRequest {
     /**
@@ -2791,12 +2849,19 @@ export interface TenDlcBrandCreateRequest {
     displayName: string;
     /** Legal company name. */
     companyName?: string;
-    /** Employer Identification Number (format: XX-XXXXXXX). */
+    /**
+     * Employer Identification Number (format: XX-XXXXXXX). Required to submit every
+     * entity type except `SOLE_PROPRIETOR`: a brand without it can be created as a
+     * draft, and `POST /v1/10dlc/brands/{brandId}/submit` refuses it with `400`.
+     */
     ein?: string;
     firstName?: string;
     lastName?: string;
     email: string;
-    /** Contact phone in E.164 format. */
+    /**
+     * Contact phone in E.164 format. For a `SOLE_PROPRIETOR`, a mobile number: the
+     * carrier texts a verification code to it.
+     */
     phone: string;
     street: string;
     city: string;
@@ -3289,7 +3354,9 @@ export interface VoiceCall {
     transcript?: Array<VoiceCallTurn>;
     /**
      * Total cost of the call in USD, combining the managed voice pipeline per-minute
-     * charge and telephony. Available once the call has ended.
+     * charge, telephony, and, on an agent that runs a premium model, that model's
+     * tokens. Available once the call has ended. Tokens are charged between 30 minutes
+     * and 24 hours after the call ends, so the figure can grow until then.
      */
     cost?: number | null;
     /** Arbitrary metadata you attached when creating the call. */
@@ -4266,6 +4333,13 @@ export interface ContactsListParams {
      * start a new pagination run when the search term changes.
      */
     search?: string;
+    /**
+     * Exact WhatsApp business-scoped user ID (e.g. `CO.13491208655302741918`). Returns
+     * the contact that holds it, or an empty list. Combines with `phoneNumber` and
+     * `tag` as a filter, and cannot be combined with `search` (400). A value that is
+     * not shaped like a BSUID returns 400.
+     */
+    bsuid?: string;
     /**
      * Tag name. Repeatable: `?tag=vip&tag=chile` returns contacts carrying **every**
      * tag given, not any of them — the same rule the dashboard filter applies.