meta-cloud-api 2.0.1 → 2.1.0

package/dist/index.d.ts

@@ -934,17 +934,29 @@ interface BlockUsersClass {
 //#endregion
 //#region src/api/blockUsers/BlockUsersApi.d.ts
 /**
- * Block Users API
- * @see https://developers.facebook.com/docs/whatsapp/cloud-api/block-users
+ * API for blocking and unblocking WhatsApp users.
+ *
+ * Provides methods to block, unblock, and list blocked users for your
+ * WhatsApp Business phone number.
  *
  * Limitations:
  * - Can only block users that have messaged your business in the last 24 hours
  * - 64k blocklist limit
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}/block_users` - Block one or more users
+ * - `DELETE /{PHONE_NUMBER_ID}/block_users` - Unblock one or more users
+ * - `GET /{PHONE_NUMBER_ID}/block_users` - List blocked users with pagination
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users/
  */
 declare class BlockUsersApi extends BaseAPI implements BlockUsersClass {
   private readonly endpoint;
   /**
-   * Build request body for block/unblock operations
+   * Build the request body for block/unblock operations.
+   *
+   * @param users - Array of phone numbers or WhatsApp IDs.
+   * @returns The formatted request body.
    */
   private buildBlockUsersBody;
   /**
@@ -952,7 +964,7 @@ declare class BlockUsersApi extends BaseAPI implements BlockUsersClass {
    * @param users - Array of phone numbers or WhatsApp IDs to block
    * @returns Response with successfully blocked and failed users
    * @throws Error if users have not messaged in last 24 hours
-   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/block-users#block-users
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users/
    *
    * @example
    * ```typescript
@@ -972,7 +984,7 @@ declare class BlockUsersApi extends BaseAPI implements BlockUsersClass {
    * Unblock one or more WhatsApp users
    * @param users - Array of phone numbers or WhatsApp IDs to unblock
    * @returns Response with successfully unblocked and failed users
-   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/block-users#unblock-users
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users/
    *
    * @example
    * ```typescript
@@ -992,7 +1004,7 @@ declare class BlockUsersApi extends BaseAPI implements BlockUsersClass {
    * Get list of blocked WhatsApp users with pagination
    * @param params - Optional pagination parameters
    * @returns List of blocked users with pagination info
-   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/block-users#get-list-of-blocked-numbers
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users/
    *
    * @example
    * ```typescript
@@ -1138,21 +1150,102 @@ interface CallingClass {
 //#region src/api/calling/CallingApi.d.ts
 /**
  * API for WhatsApp Calling features.
+ *
+ * Provides methods to manage calling settings, permissions, and call lifecycle
+ * (initiate, pre-accept, accept, reject, terminate).
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}/settings` - Update calling settings
+ * - `GET /{PHONE_NUMBER_ID}/settings` - Get calling settings
+ * - `GET /{PHONE_NUMBER_ID}/call_permissions` - Get call permissions for a user
+ * - `POST /{PHONE_NUMBER_ID}/calls` - Initiate, pre-accept, accept, reject, or terminate a call
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
  */
 declare class CallingApi extends BaseAPI implements CallingClass {
   private readonly endpoint;
+  /**
+   * Update calling settings for the phone number, such as enabling/disabling calling
+   * or configuring SIP credentials.
+   *
+   * @param params - The calling settings to update.
+   * @returns A success response confirming the settings were updated.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   updateCallingSettings(params: UpdateCallingSettingsRequest): Promise<ResponseSuccess>;
+  /**
+   * Retrieve the current calling settings for the phone number.
+   *
+   * @param params - Optional query parameters to filter the response.
+   * @param params.fields - Specific fields to include in the response.
+   * @param params.include_sip_credentials - Whether to include SIP credentials in the response.
+   * @returns The current calling settings configuration.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   getCallingSettings(params?: {
     fields?: string[] | string;
     include_sip_credentials?: boolean;
   }): Promise<CallingSettingsResponse>;
+  /**
+   * 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.
+   * @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>;
+  /**
+   * 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.session - The call session configuration.
+   * @param params.biz_opaque_callback_data - Optional opaque data passed back in webhooks.
+   * @returns The initiated call response with call ID and status.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   initiateCall(params: InitiateCallRequest): Promise<InitiateCallResponse>;
+  /**
+   * Pre-accept an incoming call, signaling readiness to connect before full acceptance.
+   *
+   * @param params - The pre-accept request parameters.
+   * @param params.call_id - The ID of the call to pre-accept.
+   * @param params.session - Optional session configuration for the call.
+   * @returns The call action response confirming the pre-accept.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   preAcceptCall(params: PreAcceptCallRequest): Promise<CallActionResponse>;
+  /**
+   * Accept an incoming call and establish the connection.
+   *
+   * @param params - The accept request parameters.
+   * @param params.call_id - The ID of the call to accept.
+   * @param params.session - Optional session configuration for the call.
+   * @param params.biz_opaque_callback_data - Optional opaque data passed back in webhooks.
+   * @returns The call action response confirming acceptance.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   acceptCall(params: AcceptCallRequest): Promise<CallActionResponse>;
+  /**
+   * Reject an incoming call.
+   *
+   * @param params - The reject request parameters.
+   * @param params.call_id - The ID of the call to reject.
+   * @returns The call action response confirming rejection.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   rejectCall(params: RejectCallRequest): Promise<CallActionResponse>;
+  /**
+   * Terminate an active call.
+   *
+   * @param params - The terminate request parameters.
+   * @param params.call_id - The ID of the call to terminate.
+   * @returns The call action response confirming termination.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
+   */
   terminateCall(params: TerminateCallRequest): Promise<CallActionResponse>;
 }
 //#endregion
@@ -1181,10 +1274,32 @@ interface CommerceClass {
 //#region src/api/commerce/CommerceApi.d.ts
 /**
  * API for WhatsApp Commerce Settings.
+ *
+ * Provides methods to retrieve and update commerce settings such as cart
+ * and catalog visibility for your WhatsApp Business phone number.
+ *
+ * Endpoints covered:
+ * - `GET /{PHONE_NUMBER_ID}/whatsapp_commerce_settings` - Get commerce settings
+ * - `POST /{PHONE_NUMBER_ID}/whatsapp_commerce_settings` - Update commerce settings
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/sell-products-and-services/set-commerce-settings/
  */
 declare class CommerceApi extends BaseAPI implements CommerceClass {
   private readonly endpoint;
+  /**
+   * Retrieve the current commerce settings for the phone number.
+   *
+   * @returns The current commerce settings including cart and catalog visibility state.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/sell-products-and-services/set-commerce-settings/
+   */
   getCommerceSettings(): Promise<CommerceSettingsResponse>;
+  /**
+   * Update commerce settings for the phone number (e.g., enable/disable cart or catalog).
+   *
+   * @param params - The commerce settings to update (e.g., is_cart_enabled, is_catalog_visible).
+   * @returns A success response confirming the settings were updated.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/sell-products-and-services/set-commerce-settings/
+   */
   updateCommerceSettings(params: UpdateCommerceSettingsRequest): Promise<ResponseSuccess>;
 }
 //#endregion
@@ -1201,9 +1316,34 @@ interface EncryptionClass {
 }
 //#endregion
 //#region src/api/encryption/EncryptionApi.d.ts
+/**
+ * API for managing WhatsApp Business Encryption keys.
+ *
+ * Provides methods to get and set the public encryption key used for
+ * end-to-end encrypted messaging with WhatsApp Business.
+ *
+ * Endpoints covered:
+ * - `GET /{PHONE_NUMBER_ID}/whatsapp_business_encryption` - Get the current public encryption key
+ * - `POST /{PHONE_NUMBER_ID}/whatsapp_business_encryption` - Set a new public encryption key
+ *
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/whatsapp-business-encryption/
+ */
 declare class EncryptionApi extends BaseAPI implements EncryptionClass {
   private readonly endpoint;
+  /**
+   * Retrieve the current public encryption key for the phone number.
+   *
+   * @returns The current public encryption key.
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/whatsapp-business-encryption/
+   */
   getEncryptionPublicKey(): Promise<EncryptionPublicKeyResponse>;
+  /**
+   * Set a new public encryption key for the phone number.
+   *
+   * @param businessPublicKey - The PEM-encoded public key string to set.
+   * @returns A success response confirming the key was set.
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/whatsapp-business-encryption/
+   */
   setEncryptionPublicKey(businessPublicKey: string): Promise<ResponseSuccess>;
 }
 //#endregion
@@ -2710,11 +2850,21 @@ interface WabaAccount {
   timezone_id?: string;
   primary_business_location?: Record<string, unknown> | string;
   currency?: string;
+  country?: string;
+  analytics?: Record<string, unknown>;
+  is_enabled_for_insights?: boolean;
+  is_shared_with_partners?: boolean;
+  marketing_messages_lite_api_status?: string;
+  marketing_messages_onboarding_status?: string;
+  on_behalf_of_business_info?: Record<string, unknown>;
+  primary_funding_id?: string;
+  purchase_order_number?: string;
+  whatsapp_business_manager_messaging_limit?: string;
 }
 /**
  * Available fields for WABA account queries
  */
-type WabaAccountFields = 'id' | 'name' | 'timezone_id' | 'account_review_status' | 'auth_international_rate_eligibility' | 'business_verification_status' | 'country' | 'currency' | 'health_status' | 'status' | 'ownership_type' | 'message_template_namespace' | 'primary_business_location';
+type WabaAccountFields = 'id' | 'name' | 'timezone_id' | 'account_review_status' | 'auth_international_rate_eligibility' | 'business_verification_status' | 'country' | 'currency' | 'health_status' | 'status' | 'ownership_type' | 'message_template_namespace' | 'primary_business_location' | 'analytics' | 'is_enabled_for_insights' | 'is_shared_with_partners' | 'marketing_messages_lite_api_status' | 'marketing_messages_onboarding_status' | 'on_behalf_of_business_info' | 'primary_funding_id' | 'purchase_order_number' | 'whatsapp_business_manager_messaging_limit';
 /**
  * Parameter type for specifying which WABA account fields to retrieve
  */
@@ -4099,30 +4249,73 @@ interface FlowClass {
 /**
  * API for managing WhatsApp Flows.
  *
+ * WhatsApp Flows allow businesses to build structured, interactive experiences
+ * within WhatsApp conversations. Flows can be used for appointment booking,
+ * lead generation, customer support, surveys, and more.
+ *
  * This API allows you to:
- * - List flows
- * - Create flows
- * - Get flow details and previews
- * - Update flow metadata and JSON
- * - Delete flows
- * - Publish and deprecate flows
- * - Migrate flows between WABAs
- * - Validate flow JSON
+ * - List flows for a WhatsApp Business Account (`GET /{WABA_ID}/flows`)
+ * - Create new flows (`POST /{WABA_ID}/flows`)
+ * - Get flow details and previews (`GET /{FLOW_ID}`)
+ * - Update flow metadata (`POST /{FLOW_ID}`)
+ * - Delete draft flows (`DELETE /{FLOW_ID}`)
+ * - List flow assets / download Flow JSON (`GET /{FLOW_ID}/assets`)
+ * - Upload or update Flow JSON (`POST /{FLOW_ID}/assets`)
+ * - Publish flows (`POST /{FLOW_ID}/publish`)
+ * - Deprecate flows (`POST /{FLOW_ID}/deprecate`)
+ * - Migrate flows between WABAs (`POST /{DESTINATION_WABA_ID}/migrate_flows`)
+ *
+ * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi | Flows API Reference}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/flows/ | WhatsApp Flows Documentation}
  */
 declare class FlowApi extends BaseAPI implements FlowClass {
   /**
-   * List Flows
+   * List all flows belonging to a WhatsApp Business Account.
    *
-   * @param wabaId - The WABA ID
-   * @returns Promise with the list of flows
+   * Retrieves a paginated list of all flows associated with the given WABA ID,
+   * including their IDs, names, statuses, and categories.
+   *
+   * @param wabaId - The WhatsApp Business Account ID to list flows for.
+   * @returns A promise that resolves with the list of flows and pagination info.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#list | List Flows}
+   *
+   * @example
+   * ```ts
+   * const response = await whatsappClient.flow.listFlows('WABA_ID');
+   * for (const flow of response.data) {
+   *     console.log(flow.id, flow.name, flow.status);
+   * }
+   * ```
    */
   listFlows(wabaId: string): Promise<FlowsListResponse>;
   /**
-   * Create Flow
+   * Create a new flow for a WhatsApp Business Account.
    *
-   * @param wabaId - The WABA ID
-   * @param data - The flow data including name, categories, endpoint_uri, and optional clone_flow_id
-   * @returns Promise with the created flow ID and validation errors if any
+   * Creates a new flow in DRAFT status. You can optionally clone an existing flow,
+   * provide initial Flow JSON, and even publish the flow immediately upon creation.
+   *
+   * @param wabaId - The WhatsApp Business Account ID to create the flow under.
+   * @param data - The flow creation parameters.
+   * @param data.name - The name of the flow.
+   * @param data.categories - Optional array of flow categories (e.g., LEAD_GENERATION, APPOINTMENT_BOOKING).
+   * @param data.endpoint_uri - Optional URI for the flow endpoint that will receive flow action payloads.
+   * @param data.clone_flow_id - Optional ID of an existing flow to clone.
+   * @param data.flow_json - Optional Flow JSON definition as a string.
+   * @param data.publish - Optional flag to publish the flow immediately after creation.
+   * @returns A promise that resolves with the created flow ID and any validation errors.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#create | Create Flow}
+   *
+   * @example
+   * ```ts
+   * const result = await whatsappClient.flow.createFlow('WABA_ID', {
+   *     name: 'Appointment Booking',
+   *     categories: ['APPOINTMENT_BOOKING'],
+   *     endpoint_uri: 'https://example.com/flow-endpoint',
+   * });
+   * console.log(result.id); // New flow ID
+   * ```
    */
   createFlow(wabaId: string, data: {
     name: string;
@@ -4133,28 +4326,76 @@ declare class FlowApi extends BaseAPI implements FlowClass {
     publish?: boolean;
   }): Promise<CreateFlowResponse>;
   /**
-   * Get Flow details
+   * Get details of a specific flow.
    *
-   * @param flowId - The flow ID
-   * @param fields - Optional fields to return (e.g., 'name,status,preview.invalidate(false)')
-   * @param dateFormat - Optional date format
-   * @returns Promise with the flow details or preview response
+   * Retrieves flow information such as name, status, categories, JSON validation errors,
+   * and optionally a preview URL. Use the `fields` parameter to request specific fields
+   * or the preview endpoint.
+   *
+   * @param flowId - The ID of the flow to retrieve.
+   * @param fields - Optional comma-separated list of fields to return (e.g., `'name,status,preview.invalidate(false)'`).
+   * @param dateFormat - Optional date format string for date fields in the response.
+   * @returns A promise that resolves with the flow details or preview response.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#details | Get Flow Details}
+   *
+   * @example
+   * ```ts
+   * // Get all flow details
+   * const flow = await whatsappClient.flow.getFlow('FLOW_ID');
+   * console.log(flow.name, flow.status);
+   *
+   * // Get specific fields only
+   * const flow = await whatsappClient.flow.getFlow('FLOW_ID', 'name,status,categories');
+   * ```
    */
   getFlow(flowId: string, fields?: string, dateFormat?: string): Promise<Flow | FlowPreviewResponse>;
   /**
-   * Get Flow Preview URL
+   * Get a preview URL for a flow.
    *
-   * @param flowId - The flow ID
-   * @param invalidate - Optional. If true, invalidates existing preview and generates a new one. Defaults to false.
-   * @returns Promise with the flow preview details
+   * Generates a shareable preview URL that allows viewing the flow without publishing it.
+   * The preview can optionally be invalidated to force generation of a fresh URL.
+   *
+   * @param flowId - The ID of the flow to preview.
+   * @param invalidate - If `true`, invalidates the existing preview and generates a new one. Defaults to `false`.
+   * @returns A promise that resolves with the flow preview details including the preview URL.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#details | Get Flow Preview}
+   *
+   * @example
+   * ```ts
+   * // Get existing preview URL
+   * const preview = await whatsappClient.flow.getFlowPreview('FLOW_ID');
+   * console.log(preview.preview.preview_url);
+   *
+   * // Force a new preview URL
+   * const freshPreview = await whatsappClient.flow.getFlowPreview('FLOW_ID', true);
+   * ```
    */
   getFlowPreview(flowId: string, invalidate?: boolean): Promise<FlowPreviewResponse>;
   /**
-   * Update Flow Metadata
+   * Update the metadata of an existing flow.
    *
-   * @param flowId - The flow ID
-   * @param data - The flow metadata to update (name, categories, endpoint_uri, application_id)
-   * @returns Promise with the success status
+   * Allows updating a flow's name, categories, endpoint URI, or associated application ID.
+   * The flow must be in DRAFT status to update certain fields.
+   *
+   * @param flowId - The ID of the flow to update.
+   * @param data - The metadata fields to update.
+   * @param data.name - Optional new name for the flow.
+   * @param data.categories - Optional new categories for the flow.
+   * @param data.endpoint_uri - Optional new endpoint URI for flow action payloads.
+   * @param data.application_id - Optional application ID to associate with the flow.
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#update | Update Flow}
+   *
+   * @example
+   * ```ts
+   * await whatsappClient.flow.updateFlowMetadata('FLOW_ID', {
+   *     name: 'Updated Flow Name',
+   *     endpoint_uri: 'https://example.com/new-endpoint',
+   * });
+   * ```
    */
   updateFlowMetadata(flowId: string, data: {
     name?: string;
@@ -4163,61 +4404,168 @@ declare class FlowApi extends BaseAPI implements FlowClass {
     application_id?: string;
   }): Promise<ResponseSuccess>;
   /**
-   * Delete Flow (only works if the Flow is in DRAFT status)
+   * Delete a flow.
    *
-   * @param flowId - The flow ID
-   * @returns Promise with the success status
+   * Permanently deletes a flow. Only flows in DRAFT status can be deleted.
+   * Published or deprecated flows cannot be deleted.
+   *
+   * @param flowId - The ID of the flow to delete.
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#delete | Delete Flow}
+   *
+   * @example
+   * ```ts
+   * await whatsappClient.flow.deleteFlow('FLOW_ID');
+   * ```
    */
   deleteFlow(flowId: string): Promise<ResponseSuccess>;
   /**
-   * List Assets (e.g., get Flow JSON download URL)
+   * List assets associated with a flow.
    *
-   * @param flowId - The flow ID
-   * @returns Promise with the list of assets
+   * Retrieves the list of assets (e.g., Flow JSON) associated with the flow.
+   * The response includes download URLs for each asset.
+   *
+   * @param flowId - The ID of the flow to list assets for.
+   * @returns A promise that resolves with the list of assets including download URLs.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#asset-list | List Flow Assets}
+   *
+   * @example
+   * ```ts
+   * const assets = await whatsappClient.flow.listAssets('FLOW_ID');
+   * for (const asset of assets.data) {
+   *     console.log(asset.name, asset.download_url);
+   * }
+   * ```
    */
   listAssets(flowId: string): Promise<FlowAssetsResponse>;
   /**
-   * Update Flow JSON by uploading a file, buffer, JSON object, or Blob.
+   * Upload or update the Flow JSON for a flow.
    *
-   * @param flowId - The flow ID
+   * Uploads a Flow JSON definition to the flow's assets. The JSON defines the screens,
+   * layout, and logic of the flow. Accepts a Buffer, plain JSON object, or Blob.
+   *
+   * @param flowId - The ID of the flow to update.
    * @param data - Object containing the file data and optional name.
    * @param data.file - The Flow JSON content as a Buffer, JSON object, or Blob.
-   * @param data.name - Optional name for the asset, defaults to 'flow.json'.
-   * @returns Promise with the success status and validation errors, if any.
+   * @param data.name - Optional name for the asset. Defaults to `'flow.json'`.
+   * @returns A promise that resolves with the upload status and any validation errors.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#asset-upload | Upload Flow JSON}
+   *
+   * @example
+   * ```ts
+   * // Upload from a JSON object
+   * const result = await whatsappClient.flow.updateFlowJson('FLOW_ID', {
+   *     file: {
+   *         version: '5.0',
+   *         screens: [{ id: 'WELCOME', layout: { type: 'SingleColumnLayout', children: [] } }],
+   *     },
+   * });
+   *
+   * // Upload from a Buffer
+   * const jsonBuffer = Buffer.from(JSON.stringify(flowDefinition));
+   * await whatsappClient.flow.updateFlowJson('FLOW_ID', { file: jsonBuffer });
+   * ```
    */
   updateFlowJson(flowId: string, data: {
     file: Blob | Buffer | object;
     name?: string;
   }): Promise<UpdateFlowResponse>;
   /**
-   * Validate Flow JSON by attempting an update without publishing.
-   * This is a convenience method; the API doesn't have a dedicated validation endpoint.
+   * Validate Flow JSON without publishing.
    *
-   * @param flowId - The ID of the Flow (must exist, can be in DRAFT status).
-   * @param flowJsonData - The Flow JSON content as a file path (string), Buffer, JSON object, or Blob.
-   * @returns Promise indicating if the JSON is valid and includes validation errors if any.
+   * This is a convenience method that uploads the Flow JSON and checks for validation
+   * errors. The API does not have a dedicated validation endpoint, so this method
+   * performs an update and inspects the response for errors.
+   *
+   * @param flowId - The ID of the flow to validate against (must exist, can be in DRAFT status).
+   * @param flowJsonData - The Flow JSON content as a Buffer, JSON object, or Blob.
+   * @returns A promise that resolves with validation results, including a `valid` boolean
+   *          and any `validation_errors` found.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#asset-upload | Upload Flow JSON (validation)}
+   *
+   * @example
+   * ```ts
+   * const result = await whatsappClient.flow.validateFlowJson('FLOW_ID', {
+   *     version: '5.0',
+   *     screens: [{ id: 'WELCOME', layout: { type: 'SingleColumnLayout', children: [] } }],
+   * });
+   * if (result.valid) {
+   *     console.log('Flow JSON is valid');
+   * } else {
+   *     console.error('Validation errors:', result.validation_errors);
+   * }
+   * ```
    */
   validateFlowJson(flowId: string, flowJsonData: Blob | Buffer | object): Promise<ValidateFlowJsonResponse>;
   /**
-   * Publish Flow
+   * Publish a flow.
    *
-   * @param flowId - The flow ID
-   * @returns Promise with the success status
+   * Transitions a flow from DRAFT status to PUBLISHED. Once published, the flow
+   * can be sent to users in WhatsApp messages. A published flow's JSON can no longer
+   * be updated.
+   *
+   * @param flowId - The ID of the flow to publish.
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#publish | Publish Flow}
+   *
+   * @example
+   * ```ts
+   * await whatsappClient.flow.publishFlow('FLOW_ID');
+   * ```
    */
   publishFlow(flowId: string): Promise<ResponseSuccess>;
   /**
-   * Deprecate Flow
+   * Deprecate a flow.
    *
-   * @param flowId - The flow ID
-   * @returns Promise with the success status
+   * Transitions a flow from PUBLISHED status to DEPRECATED. A deprecated flow
+   * can no longer be sent to users but existing sessions will continue to work.
+   * This action cannot be undone.
+   *
+   * @param flowId - The ID of the flow to deprecate.
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#deprecate | Deprecate Flow}
+   *
+   * @example
+   * ```ts
+   * await whatsappClient.flow.deprecateFlow('FLOW_ID');
+   * ```
    */
   deprecateFlow(flowId: string): Promise<ResponseSuccess>;
   /**
-   * Migrate Flows between WABAs
+   * Migrate flows between WhatsApp Business Accounts.
    *
-   * @param destinationWabaId - The destination WABA ID
-   * @param data - The migration data including source_waba_id and optional source_flow_names
-   * @returns Promise with migration results (successes and failures)
+   * Copies flows from a source WABA to a destination WABA. You can optionally
+   * specify which flows to migrate by name. Migrated flows are created in DRAFT
+   * status in the destination WABA.
+   *
+   * @param destinationWabaId - The ID of the destination WhatsApp Business Account.
+   * @param data - The migration parameters.
+   * @param data.source_waba_id - The ID of the source WhatsApp Business Account to migrate flows from.
+   * @param data.source_flow_names - Optional array of flow names to migrate. If omitted, all flows are migrated.
+   * @returns A promise that resolves with migration results including successes and failures.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows/reference/flowsapi#migrate | Migrate Flows}
+   *
+   * @example
+   * ```ts
+   * // Migrate all flows from one WABA to another
+   * const result = await whatsappClient.flow.migrateFlows('DEST_WABA_ID', {
+   *     source_waba_id: 'SOURCE_WABA_ID',
+   * });
+   *
+   * // Migrate specific flows by name
+   * const result = await whatsappClient.flow.migrateFlows('DEST_WABA_ID', {
+   *     source_waba_id: 'SOURCE_WABA_ID',
+   *     source_flow_names: ['Appointment Booking', 'Lead Gen Form'],
+   * });
+   * console.log(result.migrated_flows, result.failed_flows);
+   * ```
    */
   migrateFlows(destinationWabaId: string, data: {
     source_waba_id: string;
@@ -4236,256 +4584,963 @@ declare class FlowApi extends BaseAPI implements FlowClass {
  * - Remove participants
  * - Update group settings
  * - Fetch group metadata and active groups
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}/groups` - Create a new group
+ * - `DELETE /{GROUP_ID}` - Delete a group
+ * - `GET /{GROUP_ID}` - Get group info
+ * - `GET /{PHONE_NUMBER_ID}/groups` - List active groups
+ * - `GET /{GROUP_ID}/invite_link` - Get group invite link
+ * - `POST /{GROUP_ID}/invite_link` - Reset group invite link
+ * - `GET /{GROUP_ID}/join_requests` - Get pending join requests
+ * - `POST /{GROUP_ID}/join_requests` - Approve join requests
+ * - `DELETE /{GROUP_ID}/join_requests` - Reject join requests
+ * - `DELETE /{GROUP_ID}/participants` - Remove participants
+ * - `POST /{GROUP_ID}` - Update group settings
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
  */
 declare class GroupsApi extends BaseAPI implements GroupsClass {
+  /**
+   * Create a new WhatsApp group.
+   *
+   * @param params - The group creation parameters.
+   * @param params.subject - The name/subject of the group.
+   * @param params.description - Optional description for the group.
+   * @param params.join_approval_mode - Optional join approval mode setting.
+   * @returns The created group response with group ID.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   createGroup(params: GroupCreateRequest): Promise<GroupCreateResponse>;
+  /**
+   * Delete a WhatsApp group.
+   *
+   * @param groupId - The ID of the group to delete.
+   * @returns A success response confirming deletion.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   deleteGroup(groupId: string): Promise<ResponseSuccess>;
+  /**
+   * Retrieve metadata and information about a specific group.
+   *
+   * @param groupId - The ID of the group to retrieve.
+   * @param fields - Optional fields to include in the response (e.g., subject, description, participants).
+   * @returns The group information including metadata and requested fields.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   getGroupInfo(groupId: string, fields?: GroupInfoFieldsParam): Promise<GroupInfoResponse>;
+  /**
+   * List all active groups for the phone number with optional pagination.
+   *
+   * @param params - Optional pagination parameters.
+   * @param params.limit - Maximum number of groups to return.
+   * @param params.after - Cursor for forward pagination.
+   * @param params.before - Cursor for backward pagination.
+   * @returns A paginated list of active groups.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   getActiveGroups(params?: GroupListParams): Promise<GroupListResponse>;
+  /**
+   * Get the current invite link for a group.
+   *
+   * @param groupId - The ID of the group.
+   * @returns The group invite link.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   getGroupInviteLink(groupId: string): Promise<GroupInviteLinkResponse>;
+  /**
+   * Reset and regenerate the invite link for a group, invalidating the previous link.
+   *
+   * @param groupId - The ID of the group.
+   * @returns The new group invite link.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   resetGroupInviteLink(groupId: string): Promise<GroupInviteLinkResponse>;
+  /**
+   * Get pending join requests for a group.
+   *
+   * @param groupId - The ID of the group.
+   * @returns A list of pending join requests.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   getJoinRequests(groupId: string): Promise<GroupJoinRequestsResponse>;
+  /**
+   * Approve one or more pending join requests for a group.
+   *
+   * @param groupId - The ID of the group.
+   * @param joinRequestIds - Array of join request IDs to approve.
+   * @returns The result of the approval action.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   approveJoinRequests(groupId: string, joinRequestIds: string[]): Promise<GroupJoinRequestsActionResponse>;
+  /**
+   * Reject one or more pending join requests for a group.
+   *
+   * @param groupId - The ID of the group.
+   * @param joinRequestIds - Array of join request IDs to reject.
+   * @returns The result of the rejection action.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   rejectJoinRequests(groupId: string, joinRequestIds: string[]): Promise<GroupJoinRequestsActionResponse>;
+  /**
+   * Remove one or more participants from a group.
+   *
+   * @param groupId - The ID of the group.
+   * @param participants - Array of user WhatsApp IDs to remove from the group.
+   * @returns A success response confirming removal.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   removeParticipants(groupId: string, participants: string[]): Promise<ResponseSuccess>;
+  /**
+   * Update group settings such as subject, description, or profile picture.
+   *
+   * @param groupId - The ID of the group to update.
+   * @param params - The settings to update.
+   * @param params.subject - Optional new group subject/name.
+   * @param params.description - Optional new group description.
+   * @param params.profilePictureFile - Optional profile picture as a Buffer or Blob.
+   * @returns The updated group settings response.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/reference/
+   */
   updateGroupSettings(groupId: string, params: UpdateGroupSettingsRequest): Promise<GroupSettingsResponse>;
 }
 //#endregion
 //#region src/api/marketingMessages/MarketingMessagesApi.d.ts
 /**
  * API for WhatsApp Marketing Messages.
+ *
+ * Provides methods to send marketing template messages to WhatsApp users,
+ * with support for message activity sharing opt-in.
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}/marketing_messages` - Send a marketing template message
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/marketing-messages/send-marketing-messages/
  */
 declare class MarketingMessagesApi extends BaseAPI implements MarketingMessagesClass {
   private readonly endpoint;
+  /**
+   * Send a marketing template message to a WhatsApp user.
+   *
+   * @param params - The marketing message request parameters.
+   * @param params.to - The recipient's WhatsApp phone number.
+   * @param params.template - The template configuration (name, language, components).
+   * @param params.message_activity_sharing - Optional flag to enable message activity sharing.
+   * @returns The messages response with message ID and status.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/marketing-messages/send-marketing-messages/
+   */
   sendTemplateMessage(params: MarketingMessageRequest): Promise<MessagesResponse>;
 }
 //#endregion
 //#region src/api/media/MediaApi.d.ts
 /**
- * API for managing WhatsApp Media.
+ * WhatsApp Media API client for uploading, retrieving, downloading, and deleting media.
  *
- * This API allows you to:
- * - Get media information by ID
- * - Upload media files
- * - Delete media files
- * - Download media files from URLs
+ * Media uploaded to the WhatsApp API can be used in messages (images, audio, video,
+ * documents, stickers). Each media object is identified by a unique media ID.
+ *
+ * **Covered endpoints:**
+ * - `GET /{MEDIA_ID}` - Retrieve media info ({@link MediaApi.getMediaById})
+ * - `POST /{PHONE_NUMBER_ID}/media` - Upload media ({@link MediaApi.uploadMedia})
+ * - `DELETE /{MEDIA_ID}` - Delete media ({@link MediaApi.deleteMedia})
+ * - `GET {MEDIA_URL}` - Download media content ({@link MediaApi.downloadMedia})
+ *
+ * **Supported media types and size limits:**
+ * | Type | MIME Types | Max Size |
+ * |------|-----------|----------|
+ * | Audio | audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg | 16 MB |
+ * | Document | Various (PDF, DOC, DOCX, PPT, XLS, etc.) | 100 MB |
+ * | Image | image/jpeg, image/png | 5 MB |
+ * | Sticker | image/webp | 100 KB (animated), 500 KB (static) |
+ * | Video | video/mp4, video/3gp | 16 MB |
+ *
+ * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media | WhatsApp Media API Reference}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media/ | WhatsApp Media Documentation}
+ *
+ * @example
+ * ```ts
+ * const client = new WhatsApp({ accessToken: '...', phoneNumberId: '...' });
+ *
+ * // Upload, send, then clean up
+ * const { id } = await client.media.uploadMedia(file);
+ * await client.messages.image({ body: { id }, to: '1234567890' });
+ * await client.media.deleteMedia(id);
+ * ```
  */
 declare class MediaApi extends BaseAPI implements MediaClass {
   private readonly endpoint;
   /**
-   * Retrieve media information by media ID.
+   * Retrieves media information by media ID.
    *
-   * @param mediaId The media ID to retrieve information for
-   * @param phone_number_id Optional phone number ID (defaults to configured one)
-   * @returns Media information including URL, mime type, file size, etc.
+   * Returns metadata about the media object including its URL, MIME type, file size,
+   * and SHA-256 hash. The returned URL can be used with {@link MediaApi.downloadMedia}
+   * to fetch the actual media content.
+   *
+   * **Endpoint:** `GET /{MEDIA_ID}`
+   *
+   * @param mediaId - The unique identifier of the media to retrieve
+   * @returns A promise resolving to the media metadata including `url`, `mime_type`, `sha256`, and `file_size`
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#get-media-id | Get Media ID Reference}
    *
    * @example
-   * const mediaInfo = await whatsappClient.media.getMediaById('media_id_123');
+   * ```ts
+   * const mediaInfo = await client.media.getMediaById('media_id_123');
+   * console.log(mediaInfo.url);       // URL to download the media
+   * console.log(mediaInfo.mime_type);  // e.g., "image/jpeg"
+   * console.log(mediaInfo.file_size);  // size in bytes
+   * ```
    */
   getMediaById(mediaId: string): Promise<MediaResponse>;
   /**
-   * Upload a media file to WhatsApp.
+   * Uploads a media file to the WhatsApp Cloud API.
    *
-   * @param file The file to upload
-   * @param messagingProduct The messaging product (default: 'whatsapp')
-   * @returns Upload response containing the media ID
+   * The uploaded media is assigned a unique media ID that can be used to send
+   * messages containing that media. Media is automatically encrypted and stored
+   * on Meta's servers.
+   *
+   * **Endpoint:** `POST /{PHONE_NUMBER_ID}/media`
+   *
+   * @param file - The `File` object to upload. The `type` property must match a supported MIME type.
+   * @param messagingProduct - The messaging product identifier (defaults to `'whatsapp'`)
+   * @returns A promise resolving to the upload response containing the assigned `id` (media ID)
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#upload-media | Upload Media Reference}
    *
    * @example
+   * ```ts
    * const file = new File([buffer], 'image.jpg', { type: 'image/jpeg' });
-   * const result = await whatsappClient.media.uploadMedia(file);
+   * const { id } = await client.media.uploadMedia(file);
+   * // Use the media ID to send an image message
+   * await client.messages.image({ body: { id }, to: '1234567890' });
+   * ```
    */
   uploadMedia(file: File, messagingProduct?: string): Promise<UploadMediaResponse>;
   /**
-   * Delete a media file.
+   * Deletes a media file from WhatsApp servers.
    *
-   * @param mediaId The media ID to delete
-   * @param phone_number_id Optional phone number ID (defaults to configured one)
-   * @returns Response indicating success or failure
+   * Once deleted, the media ID can no longer be used in messages. Any messages
+   * already sent with this media will continue to display the media.
+   *
+   * **Endpoint:** `DELETE /{MEDIA_ID}`
+   *
+   * @param mediaId - The unique identifier of the media to delete
+   * @returns A promise resolving to a success response (`{ success: true }`)
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#delete-media | Delete Media Reference}
    *
    * @example
-   * await whatsappClient.media.deleteMedia('media_id_123');
+   * ```ts
+   * const result = await client.media.deleteMedia('media_id_123');
+   * console.log(result.success); // true
+   * ```
    */
   deleteMedia(mediaId: string): Promise<ResponseSuccess>;
   /**
-   * Download media from a URL.
+   * Downloads media content from a WhatsApp media URL.
    *
-   * @param mediaUrl The URL to download media from
-   * @returns Blob containing the media data
+   * Use {@link MediaApi.getMediaById} first to obtain the media URL, then pass it
+   * to this method to download the actual file content. The returned URL from
+   * `getMediaById` is only valid for a limited time.
+   *
+   * **Endpoint:** `GET {MEDIA_URL}`
+   *
+   * @param mediaUrl - The media download URL obtained from {@link MediaApi.getMediaById}
+   * @returns A promise resolving to a `Blob` containing the raw media data
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#download-media | Download Media Reference}
    *
    * @example
-   * const blob = await whatsappClient.media.downloadMedia('https://...');
+   * ```ts
+   * // First get the media URL, then download it
+   * const mediaInfo = await client.media.getMediaById('media_id_123');
+   * const blob = await client.media.downloadMedia(mediaInfo.url);
+   * ```
    */
   downloadMedia(mediaUrl: string): Promise<Blob>;
 }
 //#endregion
 //#region src/api/messages/MessageApi.d.ts
 /**
- * Maps each message type to its appropriate payload type
+ * Maps each message type to its appropriate payload type.
+ *
+ * This conditional type resolves the correct payload interface based on the {@link MessageTypesEnum} value,
+ * ensuring type-safe message construction at compile time.
  */
 type MessagePayloadType<T extends MessageTypesEnum> = T extends MessageTypesEnum.Audio ? AudioMediaObject : T extends MessageTypesEnum.Contacts ? [ContactObject] : T extends MessageTypesEnum.Document ? DocumentMediaObject : T extends MessageTypesEnum.Image ? ImageMediaObject : T extends MessageTypesEnum.Interactive ? InteractiveObject : T extends MessageTypesEnum.Location ? LocationObject : T extends MessageTypesEnum.Template ? MessageTemplateObject<ComponentTypesEnum> : T extends MessageTypesEnum.Sticker ? StickerMediaObject : T extends MessageTypesEnum.Text ? TextObject : T extends MessageTypesEnum.Video ? VideoMediaObject : T extends MessageTypesEnum.Reaction ? {
   message_id: string;
   emoji: string;
 } : never;
+/**
+ * WhatsApp Messages API client for sending various message types.
+ *
+ * Provides methods to send text, media, interactive, template, location, contact,
+ * reaction, and status messages through the WhatsApp Cloud API.
+ *
+ * **Endpoint:** `POST /{PHONE_NUMBER_ID}/messages`
+ *
+ * **Covered operations:**
+ * - {@link MessagesApi.text | text} - Send plain text messages
+ * - {@link MessagesApi.audio | audio} - Send audio messages
+ * - {@link MessagesApi.image | image} - Send image messages
+ * - {@link MessagesApi.video | video} - Send video messages
+ * - {@link MessagesApi.document | document} - Send document messages
+ * - {@link MessagesApi.sticker | sticker} - Send sticker messages
+ * - {@link MessagesApi.location | location} - Send location messages
+ * - {@link MessagesApi.contacts | contacts} - Send contact card(s)
+ * - {@link MessagesApi.template | template} - Send template messages
+ * - {@link MessagesApi.interactive | interactive} - Send interactive messages (generic)
+ * - {@link MessagesApi.interactiveList | interactiveList} - Send list interactive messages
+ * - {@link MessagesApi.interactiveCtaUrl | interactiveCtaUrl} - Send CTA URL interactive messages
+ * - {@link MessagesApi.interactiveLocationRequest | interactiveLocationRequest} - Send location request messages
+ * - {@link MessagesApi.interactiveAddressMessage | interactiveAddressMessage} - Send address message interactive messages
+ * - {@link MessagesApi.interactiveReplyButtons | interactiveReplyButtons} - Send reply button interactive messages
+ * - {@link MessagesApi.interactiveFlow | interactiveFlow} - Send flow interactive messages
+ * - {@link MessagesApi.interactiveCarousel | interactiveCarousel} - Send carousel interactive messages
+ * - {@link MessagesApi.reaction | reaction} - Send reaction emoji to a message
+ * - {@link MessagesApi.status | status} - Update message status (read, typing)
+ * - {@link MessagesApi.markAsRead | markAsRead} - Mark a message as read
+ * - {@link MessagesApi.showTypingIndicator | showTypingIndicator} - Show typing indicator
+ *
+ * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages | WhatsApp Messages API Reference}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/ | WhatsApp Messages Documentation}
+ *
+ * @example
+ * ```ts
+ * const client = new WhatsApp({ accessToken: '...', phoneNumberId: '...' });
+ *
+ * // Send a text message
+ * await client.messages.text({ body: 'Hello!', to: '1234567890' });
+ *
+ * // Send an image
+ * await client.messages.image({ body: { link: 'https://example.com/image.jpg' }, to: '1234567890' });
+ * ```
+ */
 declare class MessagesApi extends BaseAPI implements MessagesClass {
   private readonly commonMethod;
   private readonly commonEndpoint;
   /**
-   * Builds the request body for WhatsApp API messages
-   * @param type The type of message to send
-   * @param payload The message payload object
-   * @param to The recipient's phone number
-   * @param replyMessageId Optional message ID to reply to
-   * @returns The formatted request body
+   * Builds the request body for WhatsApp API messages.
+   *
+   * Constructs a properly formatted message payload including the messaging product,
+   * recipient type, recipient phone number, message type, and optional reply context.
+   *
+   * @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 replyMessageId - Optional message ID to reply to, setting the message context
+   * @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}
+   *
+   * @example
+   * ```ts
+   * const body = messagesApi.bodyBuilder(
+   *   MessageTypesEnum.Text,
+   *   { body: 'Hello!' },
+   *   '1234567890',
+   * );
+   * ```
    */
   bodyBuilder<T extends MessageTypesEnum>(type: T, payload: MessagePayloadType<T>, to: string, replyMessageId?: string): MessageRequestBody<T>;
   /**
-   * Sends a request to the WhatsApp API
-   * @param body The request body to send
-   * @returns Promise with the API response
+   * Sends a request to the WhatsApp Cloud API messages endpoint.
+   *
+   * Internal method that dispatches the serialized JSON body to
+   * `POST /{PHONE_NUMBER_ID}/messages`.
+   *
+   * @param body - The serialized JSON request body to send
+   * @returns A promise resolving to the WhatsApp messages API response containing the message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages | Messages API Reference}
    */
   private send;
   /**
-   * Sends an audio message via WhatsApp
-   * @param params The audio message parameter object
-   * @returns Promise with the message response
-   */
-  audio(params: MessageRequestParams<AudioMediaObject>): Promise<MessagesResponse>;
-  /**
-   * Sends a contact card via WhatsApp
-   * @param params The contact message parameter object
-   * @returns Promise with the message response
-   */
-  contacts(params: MessageRequestParams<[ContactObject]>): Promise<MessagesResponse>;
-  /**
-   * Sends a document via WhatsApp
-   * @param params The document message parameter object
-   * @returns Promise with the message response
+   * Sends an audio message via the WhatsApp Cloud API.
+   *
+   * The audio can be specified by a media ID (previously uploaded) or a public URL link.
+   * Supported formats: audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg (with opus codec).
+   * Maximum file size: 16 MB.
+   *
+   * @param params - The audio message parameters
+   * @param params.body - Audio media object containing either `id` (media ID) or `link` (URL)
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#audio-object | Audio Object Reference}
+   *
+   * @example
+   * ```ts
+   * // Send audio by URL
+   * await client.messages.audio({
+   *   body: { link: 'https://example.com/audio.mp3' },
+   *   to: '1234567890',
+   * });
+   *
+   * // Send audio by media ID
+   * await client.messages.audio({
+   *   body: { id: 'media_id_123' },
+   *   to: '1234567890',
+   * });
+   * ```
+   */
+  audio(params: MessageRequestParams<AudioMediaObject>): Promise<MessagesResponse>;
+  /**
+   * Sends one or more contact cards via the WhatsApp Cloud API.
+   *
+   * Contact messages allow sharing structured contact information including names,
+   * phone numbers, email addresses, and more.
+   *
+   * @param params - The contact message parameters
+   * @param params.body - Array of {@link m.ContactObject} containing contact details (name, phones, emails, etc.)
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#contacts-object | Contacts Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.contacts({
+   *   body: [{
+   *     name: { formatted_name: 'John Doe', first_name: 'John', last_name: 'Doe' },
+   *     phones: [{ phone: '+1234567890', type: 'MOBILE' }],
+   *   }],
+   *   to: '1234567890',
+   * });
+   * ```
+   */
+  contacts(params: MessageRequestParams<[ContactObject]>): Promise<MessagesResponse>;
+  /**
+   * Sends a document message via the WhatsApp Cloud API.
+   *
+   * Documents can be specified by media ID or public URL. Supports various formats
+   * including PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, and more.
+   * Maximum file size: 100 MB.
+   *
+   * @param params - The document message parameters
+   * @param params.body - Document media object containing `id` or `link`, and optional `caption` and `filename`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#document-object | Document Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.document({
+   *   body: {
+   *     link: 'https://example.com/report.pdf',
+   *     caption: 'Monthly Report',
+   *     filename: 'report.pdf',
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   document(params: MessageRequestParams<DocumentMediaObject>): Promise<MessagesResponse>;
   /**
-   * Sends an image via WhatsApp
-   * @param params The image message parameter object
-   * @returns Promise with the message response
+   * Sends an image message via the WhatsApp Cloud API.
+   *
+   * Images can be specified by media ID or public URL.
+   * Supported formats: image/jpeg, image/png. Maximum file size: 5 MB.
+   *
+   * @param params - The image message parameters
+   * @param params.body - Image media object containing `id` or `link`, and optional `caption`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#image-object | Image Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.image({
+   *   body: { link: 'https://example.com/photo.jpg', caption: 'Check this out!' },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   image(params: MessageRequestParams<ImageMediaObject>): Promise<MessagesResponse>;
   /**
-   * Sends an interactive message via WhatsApp
-   * @param params The interactive message parameter object
-   * @returns Promise with the message response
+   * Sends an interactive message via the WhatsApp Cloud API.
+   *
+   * Interactive messages allow rich user interactions such as lists, buttons, CTAs,
+   * flows, location requests, address messages, and carousels. For type-specific
+   * convenience methods, see {@link MessagesApi.interactiveList}, {@link MessagesApi.interactiveReplyButtons}, etc.
+   *
+   * @param params - The interactive message parameters
+   * @param params.body - Interactive object containing the `type` and type-specific action/body/header/footer
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object | Interactive Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactive({
+   *   body: {
+   *     type: 'button',
+   *     body: { text: 'Choose an option' },
+   *     action: {
+   *       buttons: [
+   *         { type: 'reply', reply: { id: 'btn1', title: 'Option 1' } },
+   *         { type: 'reply', reply: { id: 'btn2', title: 'Option 2' } },
+   *       ],
+   *     },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactive(params: MessageRequestParams<InteractiveObject>): Promise<MessagesResponse>;
   /**
-   * Sends a location via WhatsApp
-   * @param params The location message parameter object
-   * @returns Promise with the message response
+   * Sends a location message via the WhatsApp Cloud API.
+   *
+   * Shares a geographic location with the recipient, displayed as a map pin.
+   *
+   * @param params - The location message parameters
+   * @param params.body - Location object containing `latitude`, `longitude`, and optional `name` and `address`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#location-object | Location Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.location({
+   *   body: {
+   *     latitude: 37.4220936,
+   *     longitude: -122.083922,
+   *     name: 'Googleplex',
+   *     address: '1600 Amphitheatre Parkway, Mountain View, CA',
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   location(params: MessageRequestParams<LocationObject>): Promise<MessagesResponse>;
   /**
-   * Sends a sticker via WhatsApp
-   * @param params The sticker message parameter object
-   * @returns Promise with the message response
+   * Sends a sticker message via the WhatsApp Cloud API.
+   *
+   * Stickers can be specified by media ID or public URL.
+   * Supported format: image/webp. Maximum file size: 100 KB (animated), 500 KB (static).
+   *
+   * @param params - The sticker message parameters
+   * @param params.body - Sticker media object containing `id` or `link`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#sticker-object | Sticker Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.sticker({
+   *   body: { link: 'https://example.com/sticker.webp' },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   sticker(params: MessageRequestParams<StickerMediaObject>): Promise<MessagesResponse>;
   /**
-   * Sends a template message via WhatsApp
-   * @param params The template message parameter object
-   * @returns Promise with the message response
+   * Sends a template message via the WhatsApp Cloud API.
+   *
+   * Template messages use pre-approved message templates and can include header,
+   * body, and button components with dynamic parameters. Templates must be
+   * approved before use.
+   *
+   * @param params - The template message parameters
+   * @param params.body - Template object containing `name`, `language`, and optional `components`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#template-object | Template Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.template({
+   *   body: {
+   *     name: 'hello_world',
+   *     language: { code: 'en_US' },
+   *     components: [
+   *       { type: 'body', parameters: [{ type: 'text', text: 'John' }] },
+   *     ],
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   template(params: MessageRequestParams<MessageTemplateObject<ComponentTypesEnum>>): Promise<MessagesResponse>;
   /**
-   * Sends a text message via WhatsApp
-   * @param params The text message parameter object
-   * @returns Promise with the message response
+   * Sends a text message via the WhatsApp Cloud API.
+   *
+   * Sends a plain text message. The `body` can be a string or a {@link m.TextObject}.
+   * URL preview is enabled by default.
+   *
+   * @param params - The text message parameters
+   * @param params.body - Message text as a string, or a {@link m.TextObject} with `body` and optional `preview_url`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @param params.previewUrl - Whether to show a URL preview (defaults to `true`)
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#text-object | Text Object Reference}
+   *
+   * @example
+   * ```ts
+   * // Simple text
+   * await client.messages.text({ body: 'Hello, World!', to: '1234567890' });
+   *
+   * // With URL preview disabled
+   * await client.messages.text({
+   *   body: { body: 'Visit https://example.com', preview_url: false },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   text(params: TextMessageParams): Promise<MessagesResponse>;
   /**
-   * Sends a video message via WhatsApp
-   * @param params The video message parameter object
-   * @returns Promise with the message response
+   * Sends a video message via the WhatsApp Cloud API.
+   *
+   * Videos can be specified by media ID or public URL.
+   * Supported formats: video/mp4, video/3gp. Maximum file size: 16 MB.
+   * Only H.264 video codec and AAC audio codec are supported.
+   *
+   * @param params - The video message parameters
+   * @param params.body - Video media object containing `id` or `link`, and optional `caption`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#video-object | Video Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.video({
+   *   body: { link: 'https://example.com/video.mp4', caption: 'Watch this!' },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   video(params: MessageRequestParams<VideoMediaObject>): Promise<MessagesResponse>;
   /**
-   * Updates message status (mark as read, etc.)
-   * @param params The status update parameters
-   * @returns Promise with the API response
+   * Updates the status of a message (e.g., mark as read or show typing indicator).
+   *
+   * This is the low-level status method. For convenience, use {@link MessagesApi.markAsRead}
+   * or {@link MessagesApi.showTypingIndicator} instead.
+   *
+   * @param params - The status update parameters
+   * @param params.status - The status to set (e.g., `'read'`, `'typing'`)
+   * @param params.messageId - The ID of the message to update
+   * @param params.typingIndicator - Optional typing indicator configuration
+   * @returns A promise resolving to the API response
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#status-object | Status Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.status({
+   *   status: 'read',
+   *   messageId: 'wamid.ABC123',
+   * });
+   * ```
    */
   status(params: StatusParams): Promise<MessagesResponse>;
   /**
-   * Marks a message as read
-   * @param params Object containing messageId
-   * @returns Promise with the API response
+   * Marks a message as read, sending a read receipt to the sender.
+   *
+   * This is a convenience wrapper around {@link MessagesApi.status} that sets the status to `'read'`.
+   * When a message is marked as read, all previous messages in the conversation are also marked as read.
+   *
+   * @param params - The parameters
+   * @param params.messageId - The ID of the incoming message to mark as read (the `wamid` value)
+   * @returns A promise resolving to the API response
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#status-object | Status Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.markAsRead({ messageId: 'wamid.ABC123' });
+   * ```
    */
   markAsRead(params: {
     messageId: string;
   }): Promise<MessagesResponse>;
   /**
-   * Shows typing indicator
-   * @param params Object containing messageId
-   * @returns Promise with the API response
+   * Shows a typing indicator to the user, indicating that a response is being composed.
+   *
+   * The typing indicator is displayed for approximately 25 seconds or until a message
+   * is sent, whichever comes first.
+   *
+   * @param params - The parameters
+   * @param params.messageId - The ID of the incoming message to associate the typing indicator with
+   * @returns A promise resolving to the API response
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#status-object | Status Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.showTypingIndicator({ messageId: 'wamid.ABC123' });
+   * ```
    */
   showTypingIndicator(params: {
     messageId: string;
   }): Promise<MessagesResponse>;
   /**
-   * Sends a list interactive message
-   * @param params The list interactive message parameters
-   * @returns Promise with the message response
+   * Sends a list interactive message via the WhatsApp Cloud API.
+   *
+   * List messages present up to 10 selectable options in a menu-style list.
+   * Each section can have a title and multiple rows with title, description, and ID.
+   *
+   * @param params - The list interactive message parameters
+   * @param params.body - Interactive object with `type: 'list'` and action containing sections
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#list-messages | List Messages Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveList({
+   *   body: {
+   *     type: 'list',
+   *     body: { text: 'Choose an option' },
+   *     action: {
+   *       button: 'View Options',
+   *       sections: [{ title: 'Section 1', rows: [{ id: '1', title: 'Option 1' }] }],
+   *     },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveList(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.List;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends a CTA URL interactive message
-   * @param params The CTA URL interactive message parameters
-   * @returns Promise with the message response
+   * Sends a Call-to-Action (CTA) URL button interactive message via the WhatsApp Cloud API.
+   *
+   * CTA URL messages display a button that opens a URL when tapped.
+   *
+   * @param params - The CTA URL interactive message parameters
+   * @param params.body - Interactive object with `type: 'cta_url'` and action containing the URL and display text
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object | Interactive Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveCtaUrl({
+   *   body: {
+   *     type: 'cta_url',
+   *     body: { text: 'Visit our website' },
+   *     action: { name: 'cta_url', parameters: { display_text: 'Open', url: 'https://example.com' } },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveCtaUrl(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.CtaUrl;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends a location request interactive message
-   * @param params The location request interactive message parameters
-   * @returns Promise with the message response
+   * Sends a location request interactive message via the WhatsApp Cloud API.
+   *
+   * Prompts the recipient to share their current location.
+   *
+   * @param params - The location request interactive message parameters
+   * @param params.body - Interactive object with `type: 'location_request_message'`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object | Interactive Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveLocationRequest({
+   *   body: {
+   *     type: 'location_request_message',
+   *     body: { text: 'Please share your location' },
+   *     action: { name: 'send_location' },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveLocationRequest(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.LocationRequest;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends an address message interactive message
-   * @param params The address message interactive message parameters
-   * @returns Promise with the message response
+   * Sends an address message interactive message via the WhatsApp Cloud API.
+   *
+   * Prompts the recipient to provide or confirm a shipping/delivery address.
+   *
+   * @param params - The address message interactive message parameters
+   * @param params.body - Interactive object with `type: 'address_message'`
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object | Interactive Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveAddressMessage({
+   *   body: {
+   *     type: 'address_message',
+   *     body: { text: 'Please confirm your delivery address' },
+   *     action: { name: 'address_message', parameters: { country: 'US' } },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveAddressMessage(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.AddressMessage;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends a reply buttons interactive message
-   * @param params The reply buttons interactive message parameters
-   * @returns Promise with the message response
+   * Sends a reply buttons interactive message via the WhatsApp Cloud API.
+   *
+   * Reply button messages display up to 3 quick-reply buttons. Each button has
+   * a unique ID and title (up to 20 characters).
+   *
+   * @param params - The reply buttons interactive message parameters
+   * @param params.body - Interactive object with `type: 'button'` and action containing up to 3 reply buttons
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#reply-button | Reply Button Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveReplyButtons({
+   *   body: {
+   *     type: 'button',
+   *     body: { text: 'Do you agree?' },
+   *     action: {
+   *       buttons: [
+   *         { type: 'reply', reply: { id: 'yes', title: 'Yes' } },
+   *         { type: 'reply', reply: { id: 'no', title: 'No' } },
+   *       ],
+   *     },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveReplyButtons(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.Button;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends a flow interactive message
-   * @param params The flow interactive message parameters
-   * @returns Promise with the message response
+   * Sends a flow interactive message via the WhatsApp Cloud API.
+   *
+   * Flow messages launch a WhatsApp Flow, which provides structured multi-step interactions
+   * (forms, surveys, appointment booking, etc.) within the chat.
+   *
+   * @param params - The flow interactive message parameters
+   * @param params.body - Interactive object with `type: 'flow'` and action containing the flow token and configuration
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object | Interactive Object Reference}
+   * @see {@link https://developers.facebook.com/docs/whatsapp/flows | WhatsApp Flows Documentation}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveFlow({
+   *   body: {
+   *     type: 'flow',
+   *     body: { text: 'Book an appointment' },
+   *     action: {
+   *       name: 'flow',
+   *       parameters: { flow_message_version: '3', flow_id: '123456', flow_cta: 'Book Now' },
+   *     },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveFlow(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.Flow;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends a carousel interactive message
-   * @param params The carousel interactive message parameters
-   * @returns Promise with the message response
+   * Sends a carousel interactive message via the WhatsApp Cloud API.
+   *
+   * Carousel messages display a horizontally scrollable set of cards, each with
+   * an image, body text, and up to 2 quick-reply buttons.
+   *
+   * @param params - The carousel interactive message parameters
+   * @param params.body - Interactive object with `type: 'carousel'` and action containing carousel cards
+   * @param params.to - Recipient phone number in international format
+   * @param params.replyMessageId - Optional message ID to reply to
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#interactive-object | Interactive Object Reference}
+   *
+   * @example
+   * ```ts
+   * await client.messages.interactiveCarousel({
+   *   body: {
+   *     type: 'carousel',
+   *     body: { text: 'Browse our products' },
+   *     action: {
+   *       cards: [
+   *         {
+   *           header: { type: 'image', image: { link: 'https://example.com/product1.jpg' } },
+   *           body: { text: 'Product 1 - $10' },
+   *           buttons: [{ type: 'reply', reply: { id: 'buy_1', title: 'Buy' } }],
+   *         },
+   *       ],
+   *     },
+   *   },
+   *   to: '1234567890',
+   * });
+   * ```
    */
   interactiveCarousel(params: MessageRequestParams<InteractiveObject & {
     type: InteractiveTypesEnum.Carousel;
   }>): Promise<MessagesResponse>;
   /**
-   * Sends a reaction to a message
-   * @param params The reaction parameters
-   * @returns Promise with the message response
+   * Sends a reaction emoji to an existing message via the WhatsApp Cloud API.
+   *
+   * Reactions allow users to respond to messages with a single emoji.
+   * To remove a reaction, send an empty string as the emoji.
+   *
+   * @param params - The reaction parameters
+   * @param params.messageId - The ID of the message to react to
+   * @param params.emoji - The emoji character to react with (e.g., "\uD83D\uDC4D"), or empty string to remove reaction
+   * @param params.to - Recipient phone number in international format
+   * @returns A promise resolving to the message response with the sent message ID
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#reaction-object | Reaction Object Reference}
+   *
+   * @example
+   * ```ts
+   * // Add a reaction
+   * await client.messages.reaction({
+   *   messageId: 'wamid.ABC123',
+   *   emoji: '\uD83D\uDC4D',
+   *   to: '1234567890',
+   * });
+   *
+   * // Remove a reaction
+   * await client.messages.reaction({
+   *   messageId: 'wamid.ABC123',
+   *   emoji: '',
+   *   to: '1234567890',
+   * });
+   * ```
    */
   reaction(params: ReactionParams): Promise<MessagesResponse>;
 }
@@ -4493,136 +5548,264 @@ declare class MessagesApi extends BaseAPI implements MessagesClass {
 //#region src/api/payments/PaymentsApi.d.ts
 /**
  * API for WhatsApp Payments (India payment configuration).
+ *
+ * Provides methods to manage payment configurations for WhatsApp Business Accounts,
+ * including creating, reading, updating, and deleting payment configurations,
+ * as well as generating OAuth links for payment onboarding.
+ *
+ * Endpoints covered:
+ * - `GET /{WABA_ID}/payment_configurations` - List all payment configurations
+ * - `GET /{WABA_ID}/payment_configuration/{CONFIGURATION_NAME}` - Get a specific payment configuration
+ * - `POST /{WABA_ID}/payment_configuration` - Create a new payment configuration
+ * - `POST /{WABA_ID}/payment_configuration/{CONFIGURATION_NAME}` - Update a payment configuration
+ * - `POST /{WABA_ID}/generate_payment_configuration_oauth_link` - Generate an OAuth link
+ * - `DELETE /{WABA_ID}/payment_configuration` - Delete a payment configuration
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
  */
 declare class PaymentsApi extends BaseAPI implements PaymentsClass {
+  /**
+   * List all payment configurations for a WhatsApp Business Account.
+   *
+   * @param wabaId - The WhatsApp Business Account ID.
+   * @returns A list of all payment configurations.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
+   */
   listPaymentConfigurations(wabaId: string): Promise<PaymentConfigurationsResponse>;
+  /**
+   * Get a specific payment configuration by name.
+   *
+   * @param wabaId - The WhatsApp Business Account ID.
+   * @param configurationName - The name of the payment configuration to retrieve.
+   * @returns The payment configuration details.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
+   */
   getPaymentConfiguration(wabaId: string, configurationName: string): Promise<PaymentConfigurationsResponse>;
+  /**
+   * Create a new payment configuration for a WhatsApp Business Account.
+   *
+   * @param wabaId - The WhatsApp Business Account ID.
+   * @param params - The payment configuration details to create.
+   * @returns The created payment configuration response.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
+   */
   createPaymentConfiguration(wabaId: string, params: PaymentConfigurationCreateRequest): Promise<PaymentConfigurationCreateResponse>;
+  /**
+   * Update an existing payment configuration.
+   *
+   * @param wabaId - The WhatsApp Business Account ID.
+   * @param configurationName - The name of the payment configuration to update.
+   * @param params - The payment configuration fields to update.
+   * @returns The updated payment configuration response.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
+   */
   updatePaymentConfiguration(wabaId: string, configurationName: string, params: PaymentConfigurationUpdateRequest): Promise<PaymentConfigurationUpdateResponse>;
+  /**
+   * Generate an OAuth link for payment configuration onboarding.
+   *
+   * @param wabaId - The WhatsApp Business Account ID.
+   * @param params - The OAuth link generation parameters.
+   * @returns The generated OAuth link response.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
+   */
   generatePaymentConfigurationOauthLink(wabaId: string, params: PaymentConfigurationOauthLinkRequest): Promise<PaymentConfigurationOauthLinkResponse>;
+  /**
+   * Delete a payment configuration from a WhatsApp Business Account.
+   *
+   * @param wabaId - The WhatsApp Business Account ID.
+   * @param params - The payment configuration deletion parameters (includes configuration name).
+   * @returns A success response confirming deletion.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/onboarding-apis/
+   */
   deletePaymentConfiguration(wabaId: string, params: PaymentConfigurationDeleteRequest): Promise<ResponseSuccess>;
 }
 //#endregion
 //#region src/api/phone/PhoneNumberApi.d.ts
 /**
- * API for managing WhatsApp Phone Numb ers.
+ * API for managing WhatsApp Business phone numbers.
  *
- * This API allows you to:
- * - Get phone number information by ID
- * - Get all phone numbers for a business account
- * - Request verification codes for phone numbers
- * - Verify phone numbers with codes
+ * This API provides methods for phone number management, verification,
+ * and conversational automation configuration within the WhatsApp Business Platform.
+ *
+ * Covered endpoints:
+ * - Get phone number info by ID (`GET /{PHONE_NUMBER_ID}`)
+ * - List all phone numbers for a WABA (`GET /{WABA_ID}/phone_numbers`)
+ * - Request a verification code (`POST /{PHONE_NUMBER_ID}/request_code`)
+ * - Verify a phone number with a code (`POST /{PHONE_NUMBER_ID}/verify_code`)
+ * - Set conversational automation config (`POST /{PHONE_NUMBER_ID}/conversational_automation`)
+ * - Get conversational automation config (`GET /{PHONE_NUMBER_ID}?fields=conversational_automation`)
+ * - Get throughput info (`GET /{PHONE_NUMBER_ID}?fields=throughput`)
+ *
+ * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers | Phone Numbers API Reference}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers/ | Phone Numbers Documentation}
  */
 declare class PhoneNumberApi extends BaseAPI implements PhoneNumberClass {
   private readonly endpoint;
   /**
    * Get phone number information by ID.
    *
-   * @param fields Optional comma-separated list of fields to include in the response
-   * @returns Phone number information including verification status, quality rating, etc.
+   * Retrieves details about the configured phone number, including display phone number,
+   * verified name, quality rating, platform type, and more. Use the `fields` parameter
+   * to request only specific fields.
+   *
+   * @param fields - Optional fields to include in the response. Can be a comma-separated
+   *   string (e.g., `'display_phone_number,verified_name'`) or an array of field names.
+   * @returns A promise that resolves with the phone number information.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#get-single | Get Phone Number}
    *
    * @example
+   * ```ts
+   * // Get all available fields
    * const phoneNumber = await whatsappClient.phoneNumber.getPhoneNumberById();
-   * const phoneNumberWithFields = await whatsappClient.phoneNumber.getPhoneNumberById('display_phone_number,verified_name');
+   *
+   * // Get specific fields as a comma-separated string
+   * const phoneNumber = await whatsappClient.phoneNumber.getPhoneNumberById(
+   *     'display_phone_number,verified_name,quality_rating'
+   * );
+   *
+   * // Get specific fields as an array
+   * const phoneNumber = await whatsappClient.phoneNumber.getPhoneNumberById(
+   *     ['display_phone_number', 'verified_name']
+   * );
+   * ```
    */
   getPhoneNumberById(fields?: PhoneNumberFieldsParam): Promise<PhoneNumberResponse>;
   /**
-   * Get all phone numbers for the business account.
+   * Get all phone numbers associated with the WhatsApp Business Account.
+   *
+   * Returns a list of all phone numbers registered under the configured WABA,
+   * including their verification status, quality rating, and display information.
    *
-   * @returns List of phone numbers associated with the business account
+   * @returns A promise that resolves with the list of phone numbers.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#get-all | List Phone Numbers}
    *
    * @example
-   * const phoneNumbers = await whatsappClient.phoneNumber.getPhoneNumbers();
+   * ```ts
+   * const response = await whatsappClient.phoneNumber.getPhoneNumbers();
+   * for (const number of response.data) {
+   *     console.log(number.display_phone_number, number.verified_name);
+   * }
+   * ```
    */
   getPhoneNumbers(): Promise<PhoneNumbersResponse>;
   /**
    * Request a verification code for the phone number.
    *
-   * @param request Verification code request containing method and language
-   * @returns Response indicating success or failure
+   * Sends a verification code to the configured phone number via SMS or voice call.
+   * This is the first step of the phone number verification process.
+   *
+   * @param request - The verification code request parameters.
+   * @param request.code_method - The delivery method for the code: `'SMS'` or `'VOICE'`.
+   * @param request.language - The language code for the verification message (e.g., `'en_US'`).
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#request-verification-code | Request Verification Code}
    *
    * @example
+   * ```ts
    * await whatsappClient.phoneNumber.requestVerificationCode({
-   *   code_method: 'SMS',
-   *   language: 'en_US'
+   *     code_method: 'SMS',
+   *     language: 'en_US',
    * });
+   * ```
    */
   requestVerificationCode(request: RequestVerificationCodeRequest): Promise<ResponseSuccess>;
   /**
-   * Verify the phone number with the received code.
+   * Verify the phone number with a received verification code.
    *
-   * @param request Verification request containing the code
-   * @returns Response indicating success or failure
+   * Completes the phone number verification process by submitting the code
+   * received via SMS or voice call from {@link requestVerificationCode}.
+   *
+   * @param request - The verification request parameters.
+   * @param request.code - The 6-digit verification code received via SMS or voice call.
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#verify-code | Verify Code}
    *
    * @example
+   * ```ts
    * await whatsappClient.phoneNumber.verifyCode({
-   *   code: '123456'
+   *     code: '123456',
    * });
+   * ```
    */
   verifyCode(request: VerifyCodeRequest): Promise<ResponseSuccess>;
   /**
-   * Configure conversational automation features (Welcome Messages, Ice Breakers, Commands).
+   * Configure conversational automation features for the phone number.
    *
-   * @param request Configuration for conversational components
-   * @returns Response indicating success or failure
+   * Sets up welcome messages, ice breakers (prompts), and commands that users
+   * see when they open a conversation with the business phone number.
    *
-   * @example
-   * // Enable welcome message
-   * await whatsappClient.phoneNumber.setConversationalAutomation({
-   *   enable_welcome_message: true
-   * });
+   * @param request - The conversational automation configuration.
+   * @param request.enable_welcome_message - Optional. Enable or disable the welcome message.
+   * @param request.commands - Optional. Array of command objects with `command_name` and `command_description`.
+   * @param request.prompts - Optional. Array of ice breaker prompt strings shown to users.
+   * @returns A promise that resolves with a success indicator.
    *
-   * @example
-   * // Configure commands
-   * await whatsappClient.phoneNumber.setConversationalAutomation({
-   *   commands: [
-   *     { command_name: 'tickets', command_description: 'Book flight tickets' },
-   *     { command_name: 'hotel', command_description: 'Book hotel' }
-   *   ]
-   * });
+   * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers/ | Conversational Automation}
    *
    * @example
-   * // Configure ice breakers (prompts)
+   * ```ts
+   * // Enable welcome message
    * await whatsappClient.phoneNumber.setConversationalAutomation({
-   *   prompts: ['Book a flight', 'Plan a vacation']
+   *     enable_welcome_message: true,
    * });
    *
-   * @example
-   * // Configure all features
+   * // Configure commands and ice breakers
    * await whatsappClient.phoneNumber.setConversationalAutomation({
-   *   enable_welcome_message: true,
-   *   commands: [
-   *     { command_name: 'tickets', command_description: 'Book flight tickets' }
-   *   ],
-   *   prompts: ['Book a flight']
+   *     enable_welcome_message: true,
+   *     commands: [
+   *         { command_name: 'tickets', command_description: 'Book flight tickets' },
+   *         { command_name: 'hotel', command_description: 'Book a hotel room' },
+   *     ],
+   *     prompts: ['Book a flight', 'Plan a vacation'],
    * });
+   * ```
    */
   setConversationalAutomation(request: ConversationalAutomationRequest): Promise<ResponseSuccess>;
   /**
-   * Get the current configuration of conversational automation features.
+   * Get the current conversational automation configuration for the phone number.
+   *
+   * Retrieves the current settings for welcome messages, ice breakers (prompts),
+   * and commands configured on the phone number.
    *
-   * @returns Current configuration including welcome message status, commands, and prompts
+   * @returns A promise that resolves with the current conversational automation settings,
+   *   including welcome message status, commands, and prompts.
+   *
+   * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers/ | Conversational Automation}
    *
    * @example
+   * ```ts
    * const config = await whatsappClient.phoneNumber.getConversationalAutomation();
-   * console.log(config.enable_welcome_message); // true/false
-   * console.log(config.commands); // Array of commands
-   * console.log(config.prompts); // Array of ice breakers
+   * console.log(config.enable_welcome_message); // true or false
+   * console.log(config.commands);               // Array of command objects
+   * console.log(config.prompts);                // Array of ice breaker strings
+   * ```
    */
   getConversationalAutomation(): Promise<ConversationalAutomationResponse>;
   /**
    * Get the current throughput level for the phone number.
    *
-   * Throughput represents the maximum messages per second (mps) that can be sent/received.
-   * - Default: 80 mps
-   * - Automatic upgrade to 1,000 mps available for eligible numbers
-   * - WhatsApp Business app coexistence numbers: fixed at 5 mps
+   * Throughput represents the maximum messages per second (MPS) that can be
+   * sent or received on this phone number.
+   *
+   * Throughput levels:
+   * - **STANDARD**: 80 MPS (default for most numbers)
+   * - **HIGH**: 1,000 MPS (automatic upgrade for eligible numbers)
+   * - **NOT_APPLICABLE**: Fixed at 5 MPS (WhatsApp Business app coexistence numbers)
    *
-   * @returns Current throughput information including the level (STANDARD, HIGH, or NOT_APPLICABLE)
+   * @returns A promise that resolves with the current throughput information,
+   *   including the throughput level.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers | Phone Numbers - Throughput}
    *
    * @example
+   * ```ts
    * const throughput = await whatsappClient.phoneNumber.getThroughput();
    * console.log(throughput.throughput.level); // 'STANDARD' | 'HIGH' | 'NOT_APPLICABLE'
+   * ```
    */
   getThroughput(): Promise<ThroughputResponse>;
 }
@@ -4631,135 +5814,161 @@ declare class PhoneNumberApi extends BaseAPI implements PhoneNumberClass {
 /**
  * API for managing WhatsApp Business Profiles and profile pictures.
  *
- * This API allows you to:
- * - Get business profile information
- * - Update business profile details
- * - Upload profile pictures using a three-step process:
- *   1. Create an upload session
- *   2. Upload the image binary data
- *   3. Get the upload handle to use when updating the profile
+ * Business profiles let customers see relevant information about your business,
+ * such as a description, email, address, website, and profile picture.
+ *
+ * Covered endpoints:
+ * - Get business profile (`GET /{PHONE_NUMBER_ID}/whatsapp_business_profile`)
+ * - Update business profile (`POST /{PHONE_NUMBER_ID}/whatsapp_business_profile`)
+ * - Create an upload session for profile pictures (`POST /app/uploads`)
+ * - Upload file binary data (`POST /{UPLOAD_ID}`)
+ * - Get upload handle (`GET /{UPLOAD_ID}`)
+ *
+ * Profile picture upload follows a three-step process:
+ * 1. Create an upload session ({@link createUploadSession})
+ * 2. Upload the image binary data ({@link uploadMedia})
+ * 3. Get the upload handle ({@link getUploadHandle}) and pass it to {@link updateBusinessProfile}
+ *
+ * Available business profile fields: `about`, `address`, `description`, `email`,
+ * `profile_picture_url`, `websites`, `vertical`, `messaging_product`.
+ *
+ * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles | Business Profiles API Reference}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-profiles/ | Business Profiles Documentation}
  */
 declare class BusinessProfileApi extends BaseAPI implements BusinessProfileClass {
   private readonly endpoint;
   /**
-   * Get your business profile information.
+   * Get your WhatsApp Business profile information.
    *
-   * Use this method to retrieve details about your WhatsApp business profile, including
-   * about text, address, description, email, profile picture URL, websites, and vertical.
+   * Retrieves the business profile details for the configured phone number.
+   * You can request all fields or specify a subset using the `fields` parameter.
    *
-   * @param fields Fields to be returned in the response. If not specified, all fields will be returned.
-   *               Possible values: about, address, description, email, profile_picture_url, websites, vertical
-   * @returns The business profile information.
+   * @param fields - Optional fields to return. Can be a comma-separated string
+   *   (e.g., `'about,address,email'`) or an array of field names. If omitted,
+   *   all fields are returned. Available fields: `about`, `address`, `description`,
+   *   `email`, `profile_picture_url`, `websites`, `vertical`.
+   * @returns A promise that resolves with the business profile information.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles#get-business-profile | Get Business Profile}
    *
    * @example
+   * ```ts
    * // Get all business profile fields
    * const profile = await whatsappClient.businessProfile.getBusinessProfile();
    *
-   * // Get specific business profile fields
+   * // Get specific fields as a string
    * const profile = await whatsappClient.businessProfile.getBusinessProfile('about,address,email');
    *
-   * // Using the BusinessProfileFieldsParam type
+   * // Get specific fields as an array
    * const profile = await whatsappClient.businessProfile.getBusinessProfile(['about', 'address', 'email']);
+   * ```
    */
   getBusinessProfile(fields?: BusinessProfileFieldsParam): Promise<BusinessProfileResponse>;
   /**
-   * Update your business profile.
+   * Update your WhatsApp Business profile.
    *
-   * Use this method to update one or more fields of your WhatsApp business profile.
+   * Updates one or more fields of the business profile for the configured phone number.
+   * Only the fields included in the request body are updated; omitted fields remain unchanged.
    *
-   * @param updateRequest The request object containing the fields to update.
-   *        - messaging_product: Required. Always set to "whatsapp".
-   *        - about: Optional. Business's About text (1-139 characters).
-   *        - address: Optional. Business address (max 256 characters).
-   *        - description: Optional. Business description (max 512 characters).
-   *        - vertical: Optional. Business category (use BusinessVerticalEnum for type safety).
-   *        - email: Optional. Contact email (valid format, max 128 characters).
-   *        - websites: Optional. Up to 2 URLs (max 256 characters each).
-   *        - profile_picture_handle: Optional. Handle from upload process.
-   * @returns Response indicating success or failure.
+   * @param updateRequest - The profile fields to update.
+   * @param updateRequest.messaging_product - Required. Must be set to `'whatsapp'`.
+   * @param updateRequest.about - Optional. Business About text (1-139 characters).
+   * @param updateRequest.address - Optional. Business address (max 256 characters).
+   * @param updateRequest.description - Optional. Business description (max 512 characters).
+   * @param updateRequest.vertical - Optional. Business industry/category.
+   * @param updateRequest.email - Optional. Contact email address (max 128 characters).
+   * @param updateRequest.websites - Optional. Up to 2 website URLs (max 256 characters each).
+   * @param updateRequest.profile_picture_handle - Optional. Handle obtained from the upload process.
+   * @returns A promise that resolves with a success indicator.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles#update-business-profile | Update Business Profile}
    *
    * @example
-   * // Update business profile with multiple fields including vertical using enum
+   * ```ts
    * await whatsappClient.businessProfile.updateBusinessProfile({
-   *   messaging_product: 'whatsapp',
-   *   about: 'We provide excellent service',
-   *   email: 'contact@example.com',
-   *   websites: ['https://example.com'],
-   *   vertical: BusinessVerticalEnum.RETAIL
+   *     messaging_product: 'whatsapp',
+   *     about: 'We provide excellent service',
+   *     description: 'Your trusted partner for quality products',
+   *     email: 'contact@example.com',
+   *     websites: ['https://example.com'],
    * });
+   * ```
    */
   updateBusinessProfile(updateRequest: UpdateBusinessProfileRequest): Promise<ResponseSuccess>;
   /**
    * Create an upload session for a profile picture.
    *
-   * This is the first step in the profile picture upload process.
+   * This is **step 1** of the three-step profile picture upload process.
+   * It initializes a resumable upload session on the server and returns a session ID
+   * to use in subsequent upload calls.
    *
-   * @param fileLength Length of the file to be uploaded in bytes.
-   * @param fileType MIME type of the file (e.g., 'image/jpeg').
-   * @param fileName Name of the file with extension.
-   * @returns Response containing the upload session ID needed for the next step.
+   * @param fileLength - The size of the file in bytes.
+   * @param fileType - The MIME type of the file (e.g., `'image/jpeg'`, `'image/png'`).
+   * @param fileName - The file name with extension (e.g., `'profile.jpg'`).
+   * @returns A promise that resolves with the upload session ID.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles | Business Profiles - Upload}
    *
    * @example
-   * // Create upload session for profile picture
+   * ```ts
    * const session = await whatsappClient.businessProfile.createUploadSession(
-   *   fileBuffer.length,
-   *   'image/jpeg',
-   *   'profile.jpg'
+   *     fileBuffer.length,
+   *     'image/jpeg',
+   *     'profile.jpg',
    * );
-   * const uploadSessionId = session.upload_session_id;
+   * console.log(session.upload_session_id);
+   * ```
    */
   createUploadSession(fileLength: number, fileType: string, fileName: string): Promise<UploadSessionResponse>;
   /**
-   * Upload media file to the upload session.
+   * Upload media file binary data to an upload session.
    *
-   * This is the second step in the profile picture upload process.
-   * Upload the binary content of the file to the previously created upload session.
+   * This is **step 2** of the three-step profile picture upload process.
+   * Uploads the raw binary content of the image to the previously created upload session.
    *
-   * @param uploadId The upload session ID from createUploadSession response.
-   * @param file The binary data of the file (Buffer).
-   * @returns Response indicating success or failure.
+   * @param uploadId - The upload session ID returned from {@link createUploadSession}.
+   * @param file - The binary data of the file as a Buffer.
+   * @returns A promise that resolves with the upload response.
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles | Business Profiles - Upload}
    *
    * @example
-   * // Upload the actual file content
+   * ```ts
+   * const fileBuffer = fs.readFileSync('profile.jpg');
    * await whatsappClient.businessProfile.uploadMedia(
-   *   uploadSessionId,
-   *   fileBuffer
+   *     session.upload_session_id,
+   *     fileBuffer,
    * );
+   * ```
    */
   uploadMedia(uploadId: string, file: Buffer): Promise<UploadBusinessProfileResponse>;
   /**
-   * Get the upload handle information.
+   * Get the upload handle for a completed upload.
+   *
+   * This is **step 3** of the three-step profile picture upload process.
+   * After uploading the file binary, retrieve the handle to use when updating
+   * the business profile's `profile_picture_handle` field.
    *
-   * This is the third step in the profile picture upload process.
-   * After uploading the file, get the handle to use when updating the profile.
+   * @param uploadId - The upload session ID returned from {@link createUploadSession}.
+   * @returns A promise that resolves with the upload handle information.
    *
-   * @param uploadId The upload session ID from createUploadSession response.
-   * @returns Response containing the upload handle information.
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles | Business Profiles - Upload}
    *
    * @example
-   * // Complete profile picture update process
-   * // 1. Create upload session
+   * ```ts
+   * // Complete three-step profile picture upload
    * const session = await whatsappClient.businessProfile.createUploadSession(
-   *   fileBuffer.length, 'image/jpeg', 'profile.jpg'
-   * );
-   *
-   * // 2. Upload the image data
-   * await whatsappClient.businessProfile.uploadMedia(
-   *   session.upload_session_id, fileBuffer
-   * );
-   *
-   * // 3. Get the handle for the uploaded file
-   * const handleInfo = await whatsappClient.businessProfile.getUploadHandle(
-   *   session.upload_session_id
+   *     fileBuffer.length, 'image/jpeg', 'profile.jpg',
    * );
+   * await whatsappClient.businessProfile.uploadMedia(session.upload_session_id, fileBuffer);
+   * const handleInfo = await whatsappClient.businessProfile.getUploadHandle(session.upload_session_id);
    *
-   * // 4. Update profile with new picture and business information
+   * // Use the handle to update the profile picture
    * await whatsappClient.businessProfile.updateBusinessProfile({
-   *   messaging_product: 'whatsapp',
-   *   profile_picture_handle: handleInfo.handle,
-   *   vertical: BusinessVerticalEnum.RESTAURANT,
-   *   about: 'Delicious food served daily'
+   *     messaging_product: 'whatsapp',
+   *     profile_picture_handle: handleInfo.handle,
    * });
+   * ```
    */
   getUploadHandle(uploadId: string): Promise<UploadHandle>;
 }
@@ -4774,14 +5983,24 @@ declare class BusinessProfileApi extends BaseAPI implements BusinessProfileClass
  * - Get specific QR code details
  * - Update QR code messages
  * - Delete QR codes
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}/message_qrdls` - Create a new QR code
+ * - `GET /{PHONE_NUMBER_ID}/message_qrdls` - Get all QR codes
+ * - `GET /{PHONE_NUMBER_ID}/message_qrdls/{QR_CODE_ID}` - Get a specific QR code
+ * - `POST /{PHONE_NUMBER_ID}/message_qrdls/{QR_CODE_ID}` - Update a QR code
+ * - `DELETE /{PHONE_NUMBER_ID}/message_qrdls/{QR_CODE_ID}` - Delete a QR code
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/qr-codes/
  */
 declare class QrCodeApi extends BaseAPI implements QrCodeClass {
   private readonly endpoint;
   /**
    * Create a new QR code with a prefilled message.
    *
-   * @param request The QR code creation request
-   * @returns QR code information including code, deep link URL, and optional image URL
+   * @param request - The QR code creation request containing the prefilled message and optional image format.
+   * @returns QR code information including code, deep link URL, and optional image URL.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/qr-codes/
    *
    * @example
    * const qrCode = await whatsappClient.qrCode.createQrCode({
@@ -4793,7 +6012,8 @@ declare class QrCodeApi extends BaseAPI implements QrCodeClass {
   /**
    * Get all QR codes for the current phone number.
    *
-   * @returns List of all QR codes
+   * @returns List of all QR codes.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/qr-codes/
    *
    * @example
    * const qrCodes = await whatsappClient.qrCode.getQrCodes();
@@ -4802,8 +6022,9 @@ declare class QrCodeApi extends BaseAPI implements QrCodeClass {
   /**
    * Get a specific QR code by ID.
    *
-   * @param qrCodeId The QR code ID to retrieve
-   * @returns QR code information
+   * @param qrCodeId - The QR code ID to retrieve.
+   * @returns QR code information.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/qr-codes/
    *
    * @example
    * const qrCode = await whatsappClient.qrCode.getQrCode('qr_code_123');
@@ -4812,8 +6033,9 @@ declare class QrCodeApi extends BaseAPI implements QrCodeClass {
   /**
    * Update an existing QR code's prefilled message.
    *
-   * @param request The QR code update request containing code and new message
-   * @returns Updated QR code information
+   * @param request - The QR code update request containing code and new message.
+   * @returns Updated QR code information.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/qr-codes/
    *
    * @example
    * const updatedQrCode = await whatsappClient.qrCode.updateQrCode({
@@ -4825,8 +6047,9 @@ declare class QrCodeApi extends BaseAPI implements QrCodeClass {
   /**
    * Delete a QR code.
    *
-   * @param qrCodeId The QR code ID to delete
-   * @returns Response indicating success or failure
+   * @param qrCodeId - The QR code ID to delete.
+   * @returns Response indicating success or failure.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/qr-codes/
    *
    * @example
    * await whatsappClient.qrCode.deleteQrCode('qr_code_123');
@@ -4841,14 +6064,21 @@ declare class QrCodeApi extends BaseAPI implements QrCodeClass {
  * This API allows you to:
  * - Register a WhatsApp Business Account with a PIN
  * - Deregister a WhatsApp Business Account
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}/register` - Register a phone number
+ * - `POST /{PHONE_NUMBER_ID}/deregister` - Deregister a phone number
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration/
  */
 declare class RegistrationApi extends BaseAPI implements RegistrationClass {
   /**
    * Register a WhatsApp Business Account using a PIN.
    *
-   * @param pin The registration PIN received via SMS or voice call
-   * @param dataLocalizationRegion Optional data localization region
-   * @returns Response indicating success or failure
+   * @param pin - The registration PIN received via SMS or voice call.
+   * @param dataLocalizationRegion - Optional data localization region for storage compliance.
+   * @returns Response indicating success or failure.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration/
    *
    * @example
    * await whatsappClient.registration.register('123456', DataLocalizationRegionEnum.Asia);
@@ -4857,7 +6087,8 @@ declare class RegistrationApi extends BaseAPI implements RegistrationClass {
   /**
    * Deregister a WhatsApp Business Account.
    *
-   * @returns Response indicating success or failure
+   * @returns Response indicating success or failure.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration/
    *
    * @example
    * await whatsappClient.registration.deregister();
@@ -4878,12 +6109,178 @@ declare function createProductCardCarouselTemplate(options: ProductCardCarouselT
 declare function createSPMTemplate(options: SPMTemplateOptions): TemplateRequestBody;
 //#endregion
 //#region src/api/template/TemplateApi.d.ts
+/**
+ * WhatsApp Message Templates API client for managing message templates.
+ *
+ * Message templates are pre-approved message formats that businesses can use to
+ * send notifications and customer care messages. Templates must be approved by
+ * Meta before they can be used to send messages.
+ *
+ * **Covered endpoints:**
+ * - `GET /{TEMPLATE_ID}` - Get a single template ({@link TemplateApi.getTemplate})
+ * - `POST /{TEMPLATE_ID}` - Update an existing template ({@link TemplateApi.updateTemplate})
+ * - `GET /{WABA_ID}/message_templates` - List all templates ({@link TemplateApi.getTemplates})
+ * - `POST /{WABA_ID}/message_templates` - Create a new template ({@link TemplateApi.createTemplate})
+ * - `DELETE /{WABA_ID}/message_templates` - Delete a template ({@link TemplateApi.deleteTemplate})
+ *
+ * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/message-templates | Message Templates API Reference}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/ | WhatsApp Templates Documentation}
+ *
+ * @example
+ * ```ts
+ * const client = new WhatsApp({ accessToken: '...', phoneNumberId: '...', businessAcctId: '...' });
+ *
+ * // Create a template
+ * const template = await client.template.createTemplate({
+ *   name: 'hello_world',
+ *   language: 'en_US',
+ *   category: 'MARKETING',
+ *   components: [{ type: 'BODY', text: 'Hello {{1}}!' }],
+ * });
+ *
+ * // List all templates
+ * const templates = await client.template.getTemplates();
+ * ```
+ */
 declare class TemplateApi extends BaseAPI implements TemplateClass {
   private readonly endpoint;
+  /**
+   * Retrieves a single message template by its ID.
+   *
+   * Returns the full template definition including name, language, status,
+   * category, and components.
+   *
+   * **Endpoint:** `GET /{TEMPLATE_ID}`
+   *
+   * @param templateId - The unique identifier of the template to retrieve
+   * @returns A promise resolving to the template details
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/message-templates | Message Templates Reference}
+   *
+   * @example
+   * ```ts
+   * const template = await client.template.getTemplate('template_id_123');
+   * console.log(template.name);     // e.g., "hello_world"
+   * console.log(template.status);   // e.g., "APPROVED"
+   * ```
+   */
   getTemplate(templateId: string): Promise<TemplateResponse>;
+  /**
+   * Updates an existing message template.
+   *
+   * Allows modifying template components and other properties. Note that editing
+   * an approved template will resubmit it for review, changing its status back
+   * to `PENDING`.
+   *
+   * **Endpoint:** `POST /{TEMPLATE_ID}`
+   *
+   * @param templateId - The unique identifier of the template to update
+   * @param template - Partial template body containing only the fields to update
+   * @returns A promise resolving to a success response (`{ success: true }`)
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/message-templates | Message Templates Reference}
+   *
+   * @example
+   * ```ts
+   * await client.template.updateTemplate('template_id_123', {
+   *   components: [{ type: 'BODY', text: 'Updated greeting: Hello {{1}}!' }],
+   * });
+   * ```
+   */
   updateTemplate(templateId: string, template: Partial<TemplateRequestBody>): Promise<ResponseSuccess>;
+  /**
+   * Lists message templates for the WhatsApp Business Account.
+   *
+   * Returns a paginated list of templates, optionally filtered by query parameters
+   * such as category, language, name, status, or quality score.
+   *
+   * **Endpoint:** `GET /{WABA_ID}/message_templates`
+   *
+   * @param params - Optional query parameters to filter results
+   * @param params.category - Filter by template category (e.g., `'MARKETING'`, `'UTILITY'`)
+   * @param params.content - Filter by template content
+   * @param params.language - Filter by language code (e.g., `'en_US'`)
+   * @param params.name - Filter by exact template name
+   * @param params.name_or_content - Filter by name or content (search)
+   * @param params.quality_score - Filter by quality score
+   * @param params.status - Filter by template status (e.g., `'APPROVED'`, `'PENDING'`, `'REJECTED'`)
+   * @returns A promise resolving to a paginated response containing an array of templates
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/message-templates | Message Templates Reference}
+   *
+   * @example
+   * ```ts
+   * // List all templates
+   * const allTemplates = await client.template.getTemplates();
+   *
+   * // Filter by category and status
+   * const approved = await client.template.getTemplates({
+   *   category: 'MARKETING',
+   *   status: 'APPROVED',
+   * });
+   * ```
+   */
   getTemplates(params?: TemplateGetParams): Promise<ResponsePagination<TemplateResponse>>;
+  /**
+   * Creates a new message template for the WhatsApp Business Account.
+   *
+   * The template will be submitted for review. Once approved, it can be used
+   * to send template messages via {@link MessagesApi.template}.
+   *
+   * **Endpoint:** `POST /{WABA_ID}/message_templates`
+   *
+   * @param template - The template definition
+   * @param template.name - Template name (lowercase alphanumeric and underscores only)
+   * @param template.language - Language code (e.g., `'en_US'`)
+   * @param template.category - Template category (`'MARKETING'`, `'UTILITY'`, or `'AUTHENTICATION'`)
+   * @param template.components - Array of template components (header, body, footer, buttons)
+   * @param template.allow_category_change - Whether Meta can auto-assign a different category
+   * @param template.parameter_format - Parameter format (`'POSITIONAL'` or `'NAMED'`)
+   * @param template.sub_category - Optional sub-category for the template
+   * @param template.message_send_ttl_seconds - Optional TTL in seconds for message delivery attempts
+   * @returns A promise resolving to the created template response with its assigned `id` and `status`
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/message-templates | Message Templates Reference}
+   *
+   * @example
+   * ```ts
+   * const template = await client.template.createTemplate({
+   *   name: 'order_confirmation',
+   *   language: 'en_US',
+   *   category: 'UTILITY',
+   *   components: [
+   *     { type: 'BODY', text: 'Your order {{1}} has been confirmed.' },
+   *   ],
+   * });
+   * console.log(template.id);     // Template ID
+   * console.log(template.status); // "PENDING"
+   * ```
+   */
   createTemplate(template: TemplateRequestBody): Promise<TemplateResponse>;
+  /**
+   * Deletes a message template from the WhatsApp Business Account.
+   *
+   * Deleting a template removes all language variations of that template.
+   * To delete a specific language version, provide the `hsm_id` parameter.
+   *
+   * **Endpoint:** `DELETE /{WABA_ID}/message_templates`
+   *
+   * @param params - The delete parameters
+   * @param params.name - The name of the template to delete (required)
+   * @param params.hsm_id - Optional template ID to delete a specific language version
+   * @returns A promise resolving to a success response (`{ success: true }`)
+   *
+   * @see {@link https://developers.facebook.com/docs/whatsapp/cloud-api/reference/message-templates | Message Templates Reference}
+   *
+   * @example
+   * ```ts
+   * // Delete all language versions of a template
+   * await client.template.deleteTemplate({ name: 'old_template' });
+   *
+   * // Delete a specific language version
+   * await client.template.deleteTemplate({ name: 'old_template', hsm_id: '123456' });
+   * ```
+   */
   deleteTemplate(params: TemplateDeleteParams): Promise<ResponseSuccess>;
 }
 //#endregion
@@ -4894,13 +6291,19 @@ declare class TemplateApi extends BaseAPI implements TemplateClass {
  * This API allows you to:
  * - Set a two-step verification PIN code
  * - Manage two-step verification settings
+ *
+ * Endpoints covered:
+ * - `POST /{PHONE_NUMBER_ID}` - Set two-step verification PIN
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/two-step-verification/
  */
 declare class TwoStepVerificationApi extends BaseAPI implements TwoStepVerificationClass {
   /**
    * Set a two-step verification PIN code.
    *
-   * @param pin The PIN code to set for two-step verification (6-digit numeric string)
-   * @returns Response indicating success or failure
+   * @param pin - The PIN code to set for two-step verification (6-digit numeric string).
+   * @returns Response indicating success or failure.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/two-step-verification/
    *
    * @example
    * await whatsappClient.twoStepVerification.setTwoStepVerificationCode('123456');
@@ -4917,13 +6320,22 @@ declare class TwoStepVerificationApi extends BaseAPI implements TwoStepVerificat
  * - Manage WABA subscriptions
  * - Subscribe/unsubscribe from WABA webhooks
  * - Update subscription settings
+ *
+ * Endpoints covered:
+ * - `GET /{WABA_ID}` - Get WABA account information
+ * - `GET /{WABA_ID}/subscribed_apps` - Get all WABA subscriptions
+ * - `POST /{WABA_ID}/subscribed_apps` - Update/create a WABA subscription
+ * - `DELETE /{WABA_ID}/subscribed_apps` - Unsubscribe from WABA webhooks
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/whatsapp-business-accounts/
  */
 declare class WabaApi extends BaseAPI implements WABAClass {
   /**
    * Retrieve WhatsApp Business Account information.
    *
-   * @param fields Optional array of specific fields to retrieve
+   * @param fields - Optional array of specific fields to retrieve.
    * @returns WABA account information including status, health, verification status, etc.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/whatsapp-business-accounts/
    *
    * @example
    * const account = await whatsappClient.waba.getWabaAccount(['id', 'name', 'status']);
@@ -4932,7 +6344,8 @@ declare class WabaApi extends BaseAPI implements WABAClass {
   /**
    * Get all WABA subscriptions for the business account.
    *
-   * @returns List of all subscribed apps and their configurations
+   * @returns List of all subscribed apps and their configurations.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/whatsapp-business-accounts/
    *
    * @example
    * const subscriptions = await whatsappClient.waba.getAllWabaSubscriptions();
@@ -4941,8 +6354,9 @@ declare class WabaApi extends BaseAPI implements WABAClass {
   /**
    * Update WABA subscription configuration.
    *
-   * @param params Configuration parameters including callback URI and verify token
-   * @returns Response indicating success or failure
+   * @param params - Configuration parameters including callback URI and verify token.
+   * @returns Response indicating success or failure.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/whatsapp-business-accounts/
    *
    * @example
    * await whatsappClient.waba.updateWabaSubscription({
@@ -4957,7 +6371,8 @@ declare class WabaApi extends BaseAPI implements WABAClass {
   /**
    * Unsubscribe from WABA webhooks.
    *
-   * @returns Response indicating success or failure
+   * @returns Response indicating success or failure.
+   * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/whatsapp-business-accounts/
    *
    * @example
    * await whatsappClient.waba.unsubscribeFromWaba();