feat: apply June 2026 Cloud API changelog entries (#411–#418) (#55)

Co-authored-by: Evan <clcl6084@gmail.com>

Author: github-actions[bot]

.changeset/olive-pugs-repeat.md

@@ -0,0 +1,10 @@
+---
+'meta-cloud-api': minor
+---
+
+Apply June 2026 Cloud API changelog entries (#411–#418)
+
+- **Username API** (`phoneNumbers`): new `getUsername`, `updateUsername`, `deleteUsername`, and `getUsernameSuggestions` methods with `transfer_action` (`'none' | 'force_transfer'`) support, plus the new `147005` error code (username transfer required) in `WHATSAPP_ERROR_CODES`.
+- **Calling API**: per-call `recording` and `transcription` configuration on `initiateCall` and `acceptCall`, and new `call_recording_available` / `call_transcription_available` webhook events with `call_recording` / `call_transcript` payload types.
+- **SIP call webhooks**: new `call_created` call event type; business-scoped user ID fields (`from_user_id`, `from_parent_user_id`) on call entries.
+- **Coexistence webhooks**: new `edit` and `revoke` message webhook types (`EditMessage`, `RevokeMessage`) with business-scoped user ID fields, and matching `MessageTypesEnum.Edit` / `MessageTypesEnum.Revoke` members.

CLOUD_API_CHANGELOG.md

@@ -4,6 +4,38 @@
 > Updated: 2026-06-09T06:43:10.860Z
 
 
+## July 3, 2026
+
+- [x] **#418** Documented geographic availability for the In-App Signup API, including the regions where it is not available.
+
+## June 30, 2026
+
+- [x] **#417** Added call recording and transcription for the WhatsApp Business Calling API.
+
+## June 29, 2026
+
+- [x] **#416** Username reservation and adoption go live June 29, 2026; BSUID message-send support and the contact-request button move to July 2026.
+
+## June 26, 2026
+
+- [x] **#415** Added SIP call webhooks support with call_created and terminate events for SIP-enabled numbers.
+
+## June 25, 2026
+
+- [x] **#414** WhatsApp Cloud API Calling voicemail is now generally available.
+
+## June 12, 2026
+
+- [x] **#413** Documented business-side message edits and revokes in the coexistence edit and revoke messages webhooks for business-scoped user IDs.
+
+## June 11, 2026
+
+- [x] **#412** Corrected the Terms of Service URL required in the In-App Signup API policy.tos field. Removed the United Kingdom from the unsupported regions for template analytics and template group analytics.
+
+## June 10, 2026
+
+- [x] **#411** Documented the optional transfer_action request parameter and the new 147005 error code for the WhatsApp Business Username API.
+
 ## June 4, 2026
 
 - [x] **#410** Clarified that deleting a business phone number is not supported via the API; use WhatsApp Manager.
@@ -1035,4 +1067,4 @@
 
 ---
 
-**Progress: 410/411 (100%)**
+**Progress: 419/419 (100%)**

docs/calling.md

@@ -13,6 +13,8 @@ Configure calling, check permissions, and control call sessions.
 - Call actions use `action` values: `connect`, `pre_accept`, `accept`, `reject`, `terminate`.
 - `session` must include `sdp_type` and `sdp`.
 - `biz_opaque_callback_data` is optional for tracking.
+- `initiateCall` and `acceptCall` accept optional per-call `recording` and `transcription` configs (`status`, `purpose`, `announcement_language`). Results arrive via the `call_recording_available` / `call_transcription_available` webhook events on the `calls` field.
+- SIP-enabled numbers receive `call_created` and `terminate` call webhooks; SIP webhooks omit the `session` object since signaling is handled via SIP.
 
 ## Example
 ```ts

docs/phone-numbers.md

@@ -19,9 +19,15 @@ Retrieve phone number details, request verification codes, configure conversatio
 - POST /{PHONE_NUMBER_ID}/official_business_account
 - GET /{PHONE_NUMBER_ID}/business_compliance_info
 - POST /{PHONE_NUMBER_ID}/business_compliance_info
+- GET /{PHONE_NUMBER_ID}/username
+- POST /{PHONE_NUMBER_ID}/username
+- DELETE /{PHONE_NUMBER_ID}/username
+- GET /{PHONE_NUMBER_ID}/username_suggestions
 
 ## Notes
 - Fields can be a comma-separated string or string array.
+- Usernames support an optional `transfer_action` (`none` or `force_transfer`). If the API returns error code `147005`, the username is in use by another number in your portfolio — retry with `force_transfer`.
+- Username `status` is `approved` (visible when the feature is available) or `reserved` (approved but not yet visible).
 - `messaging_limit_tier` is typed as known Meta tiers plus future string values, because Meta has changed tier names over time.
 - Official Business Account application payloads support the website fields Meta publishes in the OpenAPI examples and schema: `website_url` and `business_website_url`.
 - Verification `code_method` is `SMS` or `VOICE`.
@@ -55,6 +61,13 @@ await client.phoneNumbers.setConversationalAutomation({
 });
 
 const throughput = await client.phoneNumbers.getThroughput();
+
+const { username, status } = await client.phoneNumbers.getUsername();
+
+await client.phoneNumbers.updateUsername({
+  username: 'jaspersmarket',
+  transfer_action: 'none',
+});
 ```
 
 ## Example Details
@@ -63,3 +76,4 @@ const throughput = await client.phoneNumbers.getThroughput();
 - `requestVerificationCode` uses `code_method` and `language` to deliver the code.
 - `setConversationalAutomation` toggles `enable_welcome_message` and sets user-facing `prompts`.
 - `getThroughput` reads throughput info for the phone number.
+- `getUsername` / `updateUsername` / `deleteUsername` / `getUsernameSuggestions` manage the phone number's username.

src/api/calling/CallingApi.ts

@@ -101,6 +101,8 @@ export default class CallingApi extends BaseAPI implements calling.CallingClass
      * @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.
+     * @param params.recording - Optional per-call recording configuration.
+     * @param params.transcription - Optional per-call transcription configuration.
      * @returns The initiated call response with call ID and status.
      * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
      */
@@ -116,11 +118,15 @@ export default class CallingApi extends BaseAPI implements calling.CallingClass
             action: calling.CallAction;
             session: calling.CallSession;
             biz_opaque_callback_data?: string;
+            recording?: calling.CallRecordingConfig;
+            transcription?: calling.CallTranscriptionConfig;
         };
 
         if (params.biz_opaque_callback_data) {
             body.biz_opaque_callback_data = params.biz_opaque_callback_data;
         }
+        if (params.recording) body.recording = params.recording;
+        if (params.transcription) body.transcription = params.transcription;
 
         return this.sendJson(
             HttpMethodsEnum.Post,
@@ -168,6 +174,8 @@ export default class CallingApi extends BaseAPI implements calling.CallingClass
      * @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.
+     * @param params.recording - Optional per-call recording configuration.
+     * @param params.transcription - Optional per-call transcription configuration.
      * @returns The call action response confirming acceptance.
      * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/
      */
@@ -182,12 +190,16 @@ export default class CallingApi extends BaseAPI implements calling.CallingClass
             action: calling.CallAction;
             session?: calling.CallSession;
             biz_opaque_callback_data?: string;
+            recording?: calling.CallRecordingConfig;
+            transcription?: calling.CallTranscriptionConfig;
         };
 
         if (params.session) body.session = params.session;
         if (params.biz_opaque_callback_data) {
             body.biz_opaque_callback_data = params.biz_opaque_callback_data;
         }
+        if (params.recording) body.recording = params.recording;
+        if (params.transcription) body.transcription = params.transcription;
 
         return this.sendJson(
             HttpMethodsEnum.Post,

src/api/calling/__test__/unit.test.ts

@@ -61,4 +61,44 @@ describe('Calling API - Unit Tests', () => {
             session: { sdp_type: 'offer', sdp: 'v=0' },
         });
     });
+
+    it('initiates a call with recording and transcription', async () => {
+        await whatsApp.calling.initiateCall({
+            to: '14085551234',
+            session: { sdp_type: 'offer', sdp: 'v=0' },
+            recording: { status: 'ENABLED', purpose: 'Quality assurance', announcement_language: 'en_US' },
+            transcription: { status: 'ENABLED', purpose: 'Quality assurance', announcement_language: 'en_US' },
+        });
+
+        const [method, endpoint, _, body] = mockRequestSend.mock.calls[0];
+        expect(method).toBe('POST');
+        expect(endpoint).toBe(`${whatsApp.requester.phoneNumberId}/calls`);
+        expect(JSON.parse(body)).toEqual({
+            messaging_product: 'whatsapp',
+            to: '14085551234',
+            action: 'connect',
+            session: { sdp_type: 'offer', sdp: 'v=0' },
+            recording: { status: 'ENABLED', purpose: 'Quality assurance', announcement_language: 'en_US' },
+            transcription: { status: 'ENABLED', purpose: 'Quality assurance', announcement_language: 'en_US' },
+        });
+    });
+
+    it('accepts a call with recording configuration', async () => {
+        await whatsApp.calling.acceptCall({
+            call_id: 'wacid.123',
+            session: { sdp_type: 'answer', sdp: 'v=0' },
+            recording: { status: 'ENABLED', purpose: 'Quality assurance', announcement_language: 'en' },
+        });
+
+        const [method, endpoint, _, body] = mockRequestSend.mock.calls[0];
+        expect(method).toBe('POST');
+        expect(endpoint).toBe(`${whatsApp.requester.phoneNumberId}/calls`);
+        expect(JSON.parse(body)).toEqual({
+            messaging_product: 'whatsapp',
+            call_id: 'wacid.123',
+            action: 'accept',
+            session: { sdp_type: 'answer', sdp: 'v=0' },
+            recording: { status: 'ENABLED', purpose: 'Quality assurance', announcement_language: 'en' },
+        });
+    });
 });

src/api/calling/index.ts

@@ -4,13 +4,13 @@ import CallingApi from './CallingApi';
 
 export default CallingApi;
 
-export { CallingApi };
-
 export type {
     AcceptCallRequest,
     CallAction,
     CallActionResponse,
+    CallAnnouncementLanguage,
     CallbackPermissionStatus,
+    CallCaptureStatus,
     CallHours,
     CallHoursDay,
     CallHoursStatus,
@@ -23,8 +23,10 @@ export type {
     CallPermissionAction,
     CallPermissionLimit,
     CallPermissionsResponse,
+    CallRecordingConfig,
     CallSdpType,
     CallSession,
+    CallTranscriptionConfig,
     HolidaySchedule,
     InitiateCallRequest,
     InitiateCallResponse,
@@ -37,3 +39,4 @@ export type {
     UpdateCallingSettingsRequest,
     WeeklyOperatingHours,
 } from './types';
+export { CallingApi };

src/api/calling/types/calling.ts

@@ -96,10 +96,65 @@ export type CallSession = {
 
 export type CallAction = 'connect' | 'pre_accept' | 'accept' | 'reject' | 'terminate';
 
+export type CallCaptureStatus = 'ENABLED' | 'DISABLED';
+
+/**
+ * Supported announcement locales for call recording / transcription.
+ * The announcement is played to both participants before capture starts.
+ */
+export type CallAnnouncementLanguage =
+    | 'en'
+    | 'en_US'
+    | 'en_AU'
+    | 'en_CA'
+    | 'en_GB'
+    | 'en_IN'
+    | 'en_NZ'
+    | 'nl'
+    | 'fr'
+    | 'de'
+    | 'hi'
+    | 'it'
+    | 'kn'
+    | 'pt'
+    | 'es'
+    | 'es_ES'
+    | 'te'
+    | 'vi'
+    | (string & {});
+
+/**
+ * Per-call recording configuration. When status is ENABLED, `purpose` and
+ * `announcement_language` are required; the recording arrives via the
+ * `call_recording_available` webhook event.
+ */
+export type CallRecordingConfig = {
+    status: CallCaptureStatus;
+    /** Reason for recording, max 250 characters — required when status is ENABLED */
+    purpose?: string;
+    /** Locale of the pre-recording announcement — required when status is ENABLED */
+    announcement_language?: CallAnnouncementLanguage;
+};
+
+/**
+ * Per-call transcription configuration. When status is ENABLED, `purpose` and
+ * `announcement_language` are required; the transcript arrives via the
+ * `call_transcription_available` webhook event.
+ */
+export type CallTranscriptionConfig = {
+    status: CallCaptureStatus;
+    /** Reason for transcription, max 250 characters — required when status is ENABLED */
+    purpose?: string;
+    /** Locale of the pre-transcription announcement — required when status is ENABLED */
+    announcement_language?: CallAnnouncementLanguage;
+};
+
 export type InitiateCallRequest = {
     to: string;
     session: CallSession;
     biz_opaque_callback_data?: string;
+    recording?: CallRecordingConfig;
+    transcription?: CallTranscriptionConfig;
 };
 
 export type PreAcceptCallRequest = {
@@ -111,6 +166,8 @@ export type AcceptCallRequest = {
     call_id: string;
     session?: CallSession;
     biz_opaque_callback_data?: string;
+    recording?: CallRecordingConfig;
+    transcription?: CallTranscriptionConfig;
 };
 
 export type RejectCallRequest = {

src/api/phone/PhoneNumberApi.ts

@@ -16,6 +16,10 @@
 // - POST /{PHONE_NUMBER_ID}/official_business_account
 // - GET /{PHONE_NUMBER_ID}/business_compliance_info
 // - POST /{PHONE_NUMBER_ID}/business_compliance_info
+// - GET /{PHONE_NUMBER_ID}/username
+// - POST /{PHONE_NUMBER_ID}/username
+// - DELETE /{PHONE_NUMBER_ID}/username
+// - GET /{PHONE_NUMBER_ID}/username_suggestions
 
 import { BaseAPI } from '../../types/base';
 import { HttpMethodsEnum, WabaConfigEnum } from '../../types/enums';
@@ -389,4 +393,80 @@ export default class PhoneNumberApi extends BaseAPI implements phoneNumber.Phone
             JSON.stringify(params),
         );
     }
+
+    /**
+     * Get the username currently associated with the business phone number.
+     *
+     * @returns A promise that resolves with the username and its status
+     *   (`'approved'` or `'reserved'`).
+     *
+     * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/usernames/ | Usernames}
+     */
+    async getUsername(): Promise<phoneNumber.UsernameResponse> {
+        return this.sendJson(
+            HttpMethodsEnum.Get,
+            `${this.config[WabaConfigEnum.PhoneNumberId]}/username`,
+            this.config[WabaConfigEnum.RequestTimeout],
+            null,
+        );
+    }
+
+    /**
+     * Adopt or change the username for the business phone number.
+     *
+     * If the desired username is already in use by another phone number in your
+     * portfolio, the API responds with error code `147005`; retry with
+     * `transfer_action: 'force_transfer'` to move the username to this number.
+     *
+     * @param params - The username request.
+     * @param params.username - The desired username.
+     * @param params.transfer_action - Optional. `'none'` (default) or `'force_transfer'`.
+     * @returns A promise that resolves with a success indicator.
+     *
+     * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/usernames/ | Usernames}
+     *
+     * @example
+     * ```ts
+     * await whatsappClient.phoneNumbers.updateUsername({
+     *     username: 'jaspersmarket',
+     *     transfer_action: 'force_transfer',
+     * });
+     * ```
+     */
+    async updateUsername(params: phoneNumber.UpdateUsernameRequest): Promise<ResponseSuccess> {
+        return this.sendJson(
+            HttpMethodsEnum.Post,
+            `${this.config[WabaConfigEnum.PhoneNumberId]}/username`,
+            this.config[WabaConfigEnum.RequestTimeout],
+            JSON.stringify(params),
+        );
+    }
+
+    /**
+     * Delete the username associated with the business phone number.
+     *
+     * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/usernames/ | Usernames}
+     */
+    async deleteUsername(): Promise<ResponseSuccess> {
+        return this.sendJson(
+            HttpMethodsEnum.Delete,
+            `${this.config[WabaConfigEnum.PhoneNumberId]}/username`,
+            this.config[WabaConfigEnum.RequestTimeout],
+            null,
+        );
+    }
+
+    /**
+     * Get username suggestions for the business phone number.
+     *
+     * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/usernames/ | Usernames}
+     */
+    async getUsernameSuggestions(): Promise<phoneNumber.UsernameSuggestionsResponse> {
+        return this.sendJson(
+            HttpMethodsEnum.Get,
+            `${this.config[WabaConfigEnum.PhoneNumberId]}/username_suggestions`,
+            this.config[WabaConfigEnum.RequestTimeout],
+            null,
+        );
+    }
 }