meta-cloud-api 3.12.1 → 3.13.0

package/dist/index.d.mts

@@ -1490,6 +1490,14 @@ type CallPermissionAction = {
   can_perform_action: boolean;
   limits?: CallPermissionLimit[];
 };
+/**
+ * Identify the WhatsApp user by phone number (`userWaId`) or BSUID (`recipient`).
+ * At least one is required.
+ */
+type GetCallPermissionsParams = {
+  userWaId?: string;
+  recipient?: string;
+};
 type CallPermissionsResponse = {
   messaging_product: 'whatsapp';
   permission: CallPermission;
@@ -1537,7 +1545,8 @@ type MessagingAccountIdParam = {
   messaging_account_id?: string;
 };
 type InitiateCallRequest = MessagingAccountIdParam & {
-  to: string;
+  /** Callee phone number. Required unless `recipient` is provided; takes precedence when both are set. */to?: string; /** Callee business-scoped user ID (BSUID) or parent BSUID. Use instead of, or in addition to, `to`. */
+  recipient?: string;
   session: CallSession;
   biz_opaque_callback_data?: string;
   recording?: CallRecordingConfig;
@@ -1576,9 +1585,7 @@ interface CallingClass {
     fields?: string[] | string;
     include_sip_credentials?: boolean;
   }): Promise<CallingSettingsResponse>;
-  getCallPermissions(params: {
-    userWaId: string;
-  }): Promise<CallPermissionsResponse>;
+  getCallPermissions(params: GetCallPermissionsParams): Promise<CallPermissionsResponse>;
   initiateCall(params: InitiateCallRequest): Promise<InitiateCallResponse>;
   preAcceptCall(params: PreAcceptCallRequest): Promise<CallActionResponse>;
   acceptCall(params: AcceptCallRequest): Promise<CallActionResponse>;
@@ -1629,18 +1636,18 @@ declare class CallingApi extends BaseAPI implements CallingClass {
    * Get calling permissions for a specific WhatsApp user.
    *
    * @param params - The request parameters.
-   * @param params.userWaId - The WhatsApp ID of the user to check permissions for.
+   * @param params.userWaId - The WhatsApp ID of the user to check permissions for. Required unless `recipient` is set.
+   * @param params.recipient - The user's business-scoped user ID (BSUID) or parent BSUID, used instead of `userWaId`.
    * @returns The call permissions for the specified user.
    * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
    */
-  getCallPermissions(params: {
-    userWaId: string;
-  }): Promise<CallPermissionsResponse>;
+  getCallPermissions(params: GetCallPermissionsParams): Promise<CallPermissionsResponse>;
   /**
    * Initiate an outbound call to a WhatsApp user.
    *
    * @param params - The call initiation parameters.
-   * @param params.to - The recipient's WhatsApp phone number.
+   * @param params.to - The recipient's WhatsApp phone number. Required unless `recipient` is set.
+   * @param params.recipient - The recipient's business-scoped user ID (BSUID) or parent BSUID. `to` takes precedence when both are set.
    * @param params.session - The call session configuration.
    * @param params.messaging_account_id - Optional Messaging account placing the call (required when the token reaches more than one).
    * @param params.biz_opaque_callback_data - Optional opaque data passed back in webhooks.
@@ -2554,7 +2561,9 @@ type InteractiveObject = ButtonInteractiveObject | ListInteractiveObject | Produ
 interface ReactionParams {
   messageId: string;
   emoji: string;
-  to: string;
+  to?: string;
+  /** Business-scoped user ID (BSUID) or parent BSUID; `to` takes precedence when both are set. */
+  recipient?: string;
   recipientType?: MessageRecipientType;
 }
 //#endregion
@@ -2608,8 +2617,9 @@ type DirectSendOptions = {
   directSendConfig?: DirectSendConfig;
 };
 type MessageRequestBody<T extends MessageTypesEnum> = GeneralMessageBody & {
-  recipient_type?: MessageRecipientType;
-  to: string;
+  recipient_type?: MessageRecipientType; /** Recipient phone number. Optional when `recipient` (BSUID) is provided. */
+  to?: string; /** Business-scoped user ID (BSUID) or parent BSUID. `to` takes precedence when both are set. */
+  recipient?: string;
   context?: ConTextObject;
   type?: T;
   category?: DirectSendCategory;
@@ -2617,7 +2627,14 @@ type MessageRequestBody<T extends MessageTypesEnum> = GeneralMessageBody & {
 };
 interface MessageRequestParams<T> {
   body: T;
-  to: string;
+  /** Recipient phone number. Required unless `recipient` is provided. */
+  to?: string;
+  /**
+   * Business-scoped user ID (BSUID) or parent BSUID of the recipient. Use instead of,
+   * or in addition to, `to`; if both are set, `to` takes precedence.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/business-scoped-user-ids
+   */
+  recipient?: string;
   recipientType?: MessageRecipientType;
   replyMessageId?: string;
   /**
@@ -3972,7 +3989,7 @@ interface WABAClass {
  * WABA event types for account_update webhook.
  * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_update
  */
-type AccountUpdateEvent = 'ACCOUNT_DELETED' | 'ACCOUNT_OFFBOARDED' | 'ACCOUNT_RECONNECTED' | 'ACCOUNT_RESTRICTION' | 'ACCOUNT_VIOLATION' | 'AD_ACCOUNT_LINKED' | 'AUTH_INTL_PRICE_ELIGIBILITY_UPDATE' | 'BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE' | 'DISABLED_UPDATE' | 'MM_LITE_TERMS_SIGNED' | 'PARTNER_ADDED' | 'PARTNER_APP_INSTALLED' | 'PARTNER_APP_UNINSTALLED' | 'PARTNER_CLIENT_CERTIFICATION_STATUS_UPDATE' | 'PARTNER_REMOVED' | 'VERIFIED_ACCOUNT' | 'VOLUME_BASED_PRICING_TIER_UPDATE';
+type AccountUpdateEvent = 'ACCOUNT_DELETED' | 'ACCOUNT_OFFBOARDED' | 'ACCOUNT_RECONNECTED' | 'ACCOUNT_RESTRICTION' | 'ACCOUNT_VIOLATION' | 'AD_ACCOUNT_LINKED' | 'AUTH_INTL_PRICE_ELIGIBILITY_UPDATE' | 'CALLING_TIER_UPDATE' | 'BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE' | 'DISABLED_UPDATE' | 'MM_LITE_TERMS_SIGNED' | 'PARTNER_ADDED' | 'PARTNER_APP_INSTALLED' | 'PARTNER_APP_UNINSTALLED' | 'PARTNER_CLIENT_CERTIFICATION_STATUS_UPDATE' | 'PARTNER_REMOVED' | 'VERIFIED_ACCOUNT' | 'VOLUME_BASED_PRICING_TIER_UPDATE';
 /**
  * WABA ban state — present on DISABLED_UPDATE events.
  */
@@ -4040,6 +4057,13 @@ interface AuthInternationalRateEligibility {
     start_time: number;
   }>;
 }
+/** Business-initiated calling tier for quality-based calling */
+type CallingLimitTier = 'CALLING_TIER_NO_ACCESS' | 'CALLING_TIER_1K' | 'CALLING_TIER_15K' | 'CALLING_TIER_UNLIMITED';
+/** Present on CALLING_TIER_UPDATE events */
+interface CallingLimitInfo {
+  current_limit: CallingLimitTier;
+  previous_limit: CallingLimitTier;
+}
 /** Present on VOLUME_BASED_PRICING_TIER_UPDATE events */
 interface VolumeTierInfo {
   /** Unix timestamp of the tier update */
@@ -4095,6 +4119,8 @@ interface AccountUpdateValue {
   waba_info?: AccountUpdateWabaInfo;
   /** Present on AUTH_INTL_PRICE_ELIGIBILITY_UPDATE events */
   auth_international_rate_eligibility?: AuthInternationalRateEligibility;
+  /** Present on CALLING_TIER_UPDATE events */
+  calling_limit_info?: CallingLimitInfo;
   /** Present on VOLUME_BASED_PRICING_TIER_UPDATE events */
   volume_tier_info?: VolumeTierInfo;
   /** Present on PARTNER_REMOVED events where business used WhatsApp Business app + Cloud API */
@@ -4413,8 +4439,12 @@ interface CallEntry {
   event: CallEventType;
   /** Unix timestamp */
   timestamp: number;
-  /** Callee of the call (Page ID) — present on connect / call_created */
+  /** Callee of the call (Page ID) — present on connect / call_created. May be omitted when the user has a username and the phone number is hidden. */
   to?: string;
+  /** BSUID of the callee (business-initiated calls) */
+  to_user_id?: string;
+  /** Parent BSUID of the callee, only when parent BSUIDs are enabled */
+  to_parent_user_id?: string;
   /** Caller of the call (PSID) — present on connect / call_created */
   from?: string;
   /** Whether the call was business- or user-initiated — present on connect */
@@ -4427,6 +4457,10 @@ interface CallEntry {
   from_parent_user_id?: string;
   /** PSID of the consumer — present on call_status */
   recipient_id?: string;
+  /** BSUID of the callee — present on call_status */
+  recipient_user_id?: string;
+  /** Parent BSUID of the callee, only when parent BSUIDs are enabled — present on call_status */
+  recipient_parent_user_id?: string;
   /** Ringing or accepted — present on call_status */
   call_status?: CallStatusValue;
   /** SDP session information; apply the offer to your local peer connection — present on media_update */
@@ -4453,10 +4487,12 @@ interface CallContact {
     /** Display name of the caller */name: string; /** Business-scoped username, when Meta includes it */
     username?: string;
   };
-  /** WhatsApp ID of the caller */
-  wa_id: string;
+  /** WhatsApp ID of the caller. May be omitted when the user has a username and the phone number is hidden. */
+  wa_id?: string;
   /** Business-scoped user ID, when Meta includes it */
   user_id?: string;
+  /** Parent business-scoped user ID, only when parent BSUIDs are enabled */
+  parent_user_id?: string;
 }
 interface CallsValue {
   messaging_product: 'whatsapp';
@@ -5912,7 +5948,7 @@ type MetaErrorData = {
 interface MetaError extends Error {
   error: MetaErrorData;
 }
-declare const WHATSAPP_ERROR_CODES: readonly [0, 1, 2, 3, 4, 10, 33, 100, 190, 200, 299, 368, 613, 80007, 130429, 130472, 130497, 131000, 131005, 131008, 131009, 131016, 131020, 131021, 131026, 131030, 131031, 131037, 131041, 131042, 131044, 131045, 131047, 131048, 131049, 131050, 131051, 131052, 131053, 131055, 131056, 131057, 131059, 131061, 131062, 131063, 131065, 131070, 131201, 131202, 131203, 131204, 131207, 131208, 131209, 131210, 131211, 131212, 131213, 131214, 131215, 132000, 132001, 132005, 132007, 132008, 132012, 132015, 132016, 132068, 132069, 133000, 133004, 133005, 133006, 133008, 133009, 133010, 133015, 133016, 134011, 134100, 134101, 134102, 135000, 137000, 138000, 138001, 138002, 138003, 138004, 138005, 138006, 138007, 138009, 138012, 138013, 138018, 138038, 139000, 139001, 139002, 139003, 139004, 139100, 139101, 139102, 139103, 147005, 200005, 200006, 200007, 1752041, 2388001, 2388012, 2388019, 2388040, 2388047, 2388072, 2388073, 2388091, 2388093, 2388103, 2388293, 2388299, 2494100, 2494191, 2593079, 2593085, 2593107, 2593108];
+declare const WHATSAPP_ERROR_CODES: readonly [0, 1, 2, 3, 4, 10, 33, 100, 190, 200, 299, 368, 613, 80007, 130429, 130472, 130497, 131000, 131005, 131008, 131009, 131016, 131020, 131021, 131026, 131030, 131031, 131037, 131041, 131042, 131044, 131045, 131047, 131048, 131049, 131050, 131051, 131052, 131053, 131055, 131056, 131057, 131059, 131061, 131062, 131063, 131065, 131070, 131201, 131202, 131203, 131204, 131207, 131208, 131209, 131210, 131211, 131212, 131213, 131214, 131215, 132000, 132001, 132005, 132007, 132008, 132012, 132015, 132016, 132068, 132069, 133000, 133004, 133005, 133006, 133008, 133009, 133010, 133015, 133016, 134011, 134100, 134101, 134102, 135000, 137000, 138000, 138001, 138002, 138003, 138004, 138005, 138006, 138007, 138009, 138012, 138013, 138018, 138037, 138038, 139000, 139001, 139002, 139003, 139004, 139100, 139101, 139102, 139103, 147005, 200005, 200006, 200007, 1752041, 2388001, 2388012, 2388019, 2388040, 2388047, 2388072, 2388073, 2388091, 2388093, 2388103, 2388293, 2388299, 2494100, 2494191, 2593079, 2593085, 2593107, 2593108];
 type ApiPermissionErrorCode = number;
 type WhatsAppErrorCode = (typeof WHATSAPP_ERROR_CODES)[number] | ApiPermissionErrorCode;
 declare const AUTHORIZATION_ERROR_CODES: readonly [0, 3, 10, 190];
@@ -5921,7 +5957,7 @@ declare const INTEGRITY_ERROR_CODES: readonly [368, 130497, 131031];
 declare const SEND_MESSAGE_ERROR_CODES: readonly [130472, 131000, 131005, 131008, 131009, 131016, 131021, 131026, 131030, 131042, 131044, 131045, 131047, 131050, 131051, 131052, 131053, 131056, 131057, 131048, 131061, 131062, 131063, 131065, 131070, 132000, 132001, 132005, 132007, 132008, 132012, 132015, 132016, 132068, 132069, 135000, 137000];
 declare const FLOW_ERROR_CODES: readonly [139000, 139001, 139002, 139003, 139004];
 declare const BLOCK_USER_ERROR_CODES: readonly [139100, 139101, 139102, 139103];
-declare const CALLING_ERROR_CODES: readonly [138000, 138001, 138002, 138003, 138004, 138005, 138006, 138007, 138009, 138012, 138013, 138018, 138038, 613];
+declare const CALLING_ERROR_CODES: readonly [138000, 138001, 138002, 138003, 138004, 138005, 138006, 138007, 138009, 138012, 138013, 138018, 138037, 138038, 613];
 declare const GROUP_ERROR_CODES: readonly [131020, 131041, 131059, 131201, 131202, 131203, 131204, 131207, 131208, 131209, 131210, 131211, 131212, 131213, 131214, 131215];
 declare function isWhatsAppErrorCode(code: number): code is WhatsAppErrorCode;
 declare function isApiPermissionErrorCode(code: number): code is ApiPermissionErrorCode;
@@ -7487,10 +7523,11 @@ declare class MessagesApi extends BaseAPI implements MessagesClass {
    *
    * @param type - The type of message to send (e.g., text, image, template)
    * @param payload - The message payload object matching the specified type
-   * @param to - The recipient's phone number in international format (e.g., "1234567890")
+   * @param to - The recipient's phone number in international format (e.g., "1234567890"). Optional when `recipient` is set.
    * @param replyMessageId - Optional message ID to reply to, setting the message context
    * @param recipientType - Whether `to` addresses an individual or a group
    * @param directSend - Optional Direct Send options (`category` and `directSendConfig`)
+   * @param recipient - Optional business-scoped user ID (BSUID) or parent BSUID. Use instead of, or with, `to`; `to` takes precedence when both are set.
    * @returns The formatted request body ready to be serialized and sent
    *
    * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages | Messages API Reference}
@@ -7505,7 +7542,7 @@ declare class MessagesApi extends BaseAPI implements MessagesClass {
    * );
    * ```
    */
-  bodyBuilder<T extends MessageTypesEnum>(type: T, payload: MessagePayloadType<T>, to: string, replyMessageId?: string, recipientType?: MessageRecipientType, directSend?: DirectSendOptions): MessageRequestBody<T>;
+  bodyBuilder<T extends MessageTypesEnum>(type: T, payload: MessagePayloadType<T>, to: string | undefined, replyMessageId?: string, recipientType?: MessageRecipientType, directSend?: DirectSendOptions, recipient?: string): MessageRequestBody<T>;
   /**
    * Sends a request to the WhatsApp Cloud API messages endpoint.
    *