@zavudev/sdk 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 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
+
+* **messages:** `MessageContent.replyToMessageId` documents quoting when
+  sending: on WhatsApp and Telegram, a send quotes an earlier message of the
+  same conversation and sender, and is refused with `400` when it cannot. The
+  other `replyTo*` fields are read-only. Same text in `@zavudev/sdk/v2`.
+
 ## 0.59.0 (unreleased)
 
 ### Features

package/package.json

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

package/src/types.ts

@@ -440,25 +440,42 @@ export interface MessageContent {
   /** Message ID to react to. */
   reactToMessageId?: string;
   /**
-   * Zavu message ID of the quoted message this message replies to. Present on
-   * inbound messages that quote an earlier message. Omitted when the quoted message
-   * is not found in Zavu (e.g. an old or unknown message) — use
-   * replyToProviderMessageId in that case.
+   * Zavu message ID of the quoted message this message replies to.
+   *
+   * **When sending:** set it to make the message a quoted reply to an earlier
+   * message in the same conversation, such as the `data.messageId` of a
+   * `message.inbound` webhook. Supported on WhatsApp (every message type except
+   * `reaction`) and Telegram. The quoted message must belong to this project
+   * (otherwise `404`), must have gone out on the same channel as this send, must
+   * belong to the conversation `to` addresses, must have been sent or received by
+   * the sender this message goes out from (pass it in `Zavu-Sender`), and must have
+   * a `providerMessageId`. A failed message and a Telegram button tap cannot be
+   * quoted. Any other case returns `400` instead of sending the message unquoted.
+   * The stored message then carries the rest of the `replyTo*` fields.
+   *
+   * **When receiving:** present on inbound messages that quote an earlier message.
+   * Omitted when the quoted message is not found in Zavu (e.g. an old or unknown
+   * message) — use replyToProviderMessageId in that case.
    */
   replyToMessageId?: string;
   /**
-   * Provider message ID (WhatsApp WAMID) of the quoted message. Present whenever an
-   * inbound message is a reply, even if the quoted message is not stored in Zavu.
+   * Provider message ID (WhatsApp WAMID, or Telegram message ID) of the quoted
+   * message. Present whenever an inbound WhatsApp message is a reply, even if the
+   * quoted message is not stored in Zavu, and on outbound quoted replies. Read-only:
+   * to quote when sending, set replyToMessageId.
    */
   replyToProviderMessageId?: string;
-  /** Sender of the quoted message (phone number in E.164 format). */
+  /**
+   * Sender of the quoted message (phone number in E.164 format, or the Telegram chat
+   * ID). Read-only.
+   */
   replyToFrom?: string;
   /**
-   * Truncated snippet of the quoted message's text, for display. Empty when the
-   * quoted message has no text (e.g. media).
+   * Truncated snippet (up to 200 characters) of the quoted message's text, for
+   * display. Empty when the quoted message has no text (e.g. media). Read-only.
    */
   replyToText?: string;
-  /** Type of the quoted message (text, image, video, etc.). */
+  /** Type of the quoted message (text, image, video, etc.). Read-only. */
   replyToMessageType?: string;
   /** Template ID for template messages. */
   templateId?: string;
@@ -909,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
@@ -939,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
@@ -1000,6 +1037,7 @@ export type WebhookEvent =
   | 'message.unsupported'
   | 'broadcast.status_changed'
   | 'conversation.new'
+  | 'contact.identity_linked'
   | 'template.status_changed'
   | 'invitation.status_changed'
   | 'call.initiated'
@@ -1050,14 +1088,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.
@@ -1085,6 +1138,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. */
@@ -1357,6 +1420,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. */
@@ -1370,6 +1440,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'
@@ -3095,12 +3172,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;
@@ -4750,6 +4834,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'
@@ -1044,25 +1058,42 @@ export interface MessageContent {
   /** Message ID to react to. */
   reactToMessageId?: string;
   /**
-   * Zavu message ID of the quoted message this message replies to. Present on
-   * inbound messages that quote an earlier message. Omitted when the quoted message
-   * is not found in Zavu (e.g. an old or unknown message) — use
-   * replyToProviderMessageId in that case.
+   * Zavu message ID of the quoted message this message replies to.
+   *
+   * **When sending:** set it to make the message a quoted reply to an earlier
+   * message in the same conversation, such as the `data.messageId` of a
+   * `message.inbound` webhook. Supported on WhatsApp (every message type except
+   * `reaction`) and Telegram. The quoted message must belong to this project
+   * (otherwise `404`), must have gone out on the same channel as this send, must
+   * belong to the conversation `to` addresses, must have been sent or received by
+   * the address this message goes out from (`from`), and must have a
+   * `providerMessageId`. A failed message and a Telegram button tap cannot be
+   * quoted. Any other case returns `400` instead of sending the message unquoted.
+   * The stored message then carries the rest of the `replyTo*` fields.
+   *
+   * **When receiving:** present on inbound messages that quote an earlier message.
+   * Omitted when the quoted message is not found in Zavu (e.g. an old or unknown
+   * message) — use replyToProviderMessageId in that case.
    */
   replyToMessageId?: string;
   /**
-   * Provider message ID (WhatsApp WAMID) of the quoted message. Present whenever an
-   * inbound message is a reply, even if the quoted message is not stored in Zavu.
+   * Provider message ID (WhatsApp WAMID, or Telegram message ID) of the quoted
+   * message. Present whenever an inbound WhatsApp message is a reply, even if the
+   * quoted message is not stored in Zavu, and on outbound quoted replies. Read-only:
+   * to quote when sending, set replyToMessageId.
    */
   replyToProviderMessageId?: string;
-  /** Sender of the quoted message (phone number in E.164 format). */
+  /**
+   * Sender of the quoted message (phone number in E.164 format, or the Telegram chat
+   * ID). Read-only.
+   */
   replyToFrom?: string;
   /**
-   * Truncated snippet of the quoted message's text, for display. Empty when the
-   * quoted message has no text (e.g. media).
+   * Truncated snippet (up to 200 characters) of the quoted message's text, for
+   * display. Empty when the quoted message has no text (e.g. media). Read-only.
    */
   replyToText?: string;
-  /** Type of the quoted message (text, image, video, etc.). */
+  /** Type of the quoted message (text, image, video, etc.). Read-only. */
   replyToMessageType?: string;
   /** Template ID for template messages. */
   templateId?: string;
@@ -1667,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
@@ -1697,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
@@ -1756,6 +1807,7 @@ export type WebhookEvent =
   | 'message.unsupported'
   | 'broadcast.status_changed'
   | 'conversation.new'
+  | 'contact.identity_linked'
   | 'template.status_changed'
   | 'invitation.status_changed'
   | 'call.initiated'
@@ -1788,14 +1840,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.
@@ -1823,6 +1890,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
@@ -2306,6 +2383,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.0'; // x-release-please-version
+export const VERSION = '0.60.0'; // x-release-please-version