whatsapp-web.js 1.22.2-alpha.1 → 1.22.2-alpha.3

package/example.js

@@ -91,6 +91,78 @@ client.on('message', async msg => {
         } catch (e) {
             msg.reply('That invite code seems to be invalid.');
         }
+    } else if (msg.body.startsWith('!addmembers')) {
+        const group = await msg.getChat();
+        const result = await group.addParticipants(['number1@c.us', 'number2@c.us', 'number3@c.us']);
+        /**
+         * The example of the {@link result} output:
+         *
+         * {
+         *   'number1@c.us': {
+         *     code: 200,
+         *     message: 'The participant was added successfully',
+         *     isInviteV4Sent: false
+         *   },
+         *   'number2@c.us': {
+         *     code: 403,
+         *     message: 'The participant can be added by sending private invitation only',
+         *     isInviteV4Sent: true
+         *   },
+         *   'number3@c.us': {
+         *     code: 404,
+         *     message: 'The phone number is not registered on WhatsApp',
+         *     isInviteV4Sent: false
+         *   }
+         * }
+         *
+         * For more usage examples:
+         * @see https://github.com/pedroslopez/whatsapp-web.js/pull/2344#usage-example1
+         */
+        console.log(result);
+    } else if (msg.body === '!creategroup') {
+        const partitipantsToAdd = ['number1@c.us', 'number2@c.us', 'number3@c.us'];
+        const result = await client.createGroup('Group Title', partitipantsToAdd);
+        /**
+         * The example of the {@link result} output:
+         * {
+         *   title: 'Group Title',
+         *   gid: {
+         *     server: 'g.us',
+         *     user: '1111111111',
+         *     _serialized: '1111111111@g.us'
+         *   },
+         *   participants: {
+         *     'botNumber@c.us': {
+         *       statusCode: 200,
+         *       message: 'The participant was added successfully',
+         *       isGroupCreator: true,
+         *       isInviteV4Sent: false
+         *     },
+         *     'number1@c.us': {
+         *       statusCode: 200,
+         *       message: 'The participant was added successfully',
+         *       isGroupCreator: false,
+         *       isInviteV4Sent: false
+         *     },
+         *     'number2@c.us': {
+         *       statusCode: 403,
+         *       message: 'The participant can be added by sending private invitation only',
+         *       isGroupCreator: false,
+         *       isInviteV4Sent: true
+         *     },
+         *     'number3@c.us': {
+         *       statusCode: 404,
+         *       message: 'The phone number is not registered on WhatsApp',
+         *       isGroupCreator: false,
+         *       isInviteV4Sent: false
+         *     }
+         *   }
+         * }
+         *
+         * For more usage examples:
+         * @see https://github.com/pedroslopez/whatsapp-web.js/pull/2344#usage-example2
+         */
+        console.log(result);
     } else if (msg.body === '!groupinfo') {
         let chat = await msg.getChat();
         if (chat.isGroup) {
@@ -151,7 +223,14 @@ client.on('message', async msg => {
             await client.sendMessage(msg.from, media, { isViewOnce: true });
         }
     } else if (msg.body === '!location') {
-        msg.reply(new Location(37.422, -122.084, 'Googleplex\nGoogle Headquarters'));
+        // only latitude and longitude
+        await msg.reply(new Location(37.422, -122.084));
+        // location with name only
+        await msg.reply(new Location(37.422, -122.084, { name: 'Googleplex' }));
+        // location with address only
+        await msg.reply(new Location(37.422, -122.084, { address: '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA' }));
+        // location with name, address and url
+        await msg.reply(new Location(37.422, -122.084, { name: 'Googleplex', address: '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA', url: 'https://google.com' }));
     } else if (msg.location) {
         msg.reply(msg.location);
     } else if (msg.body.startsWith('!status ')) {
@@ -232,6 +311,52 @@ client.on('message', async msg => {
     } else if (msg.body === '!removelabels') {
         const chat = await msg.getChat();
         await chat.changeLabels([]);
+    } else if (msg.body === '!approverequest') {
+        /**
+         * Presented an example for membership request approvals, the same examples are for the request rejections.
+         * To approve the membership request from a specific user:
+         */
+        await client.approveGroupMembershipRequests(msg.from, { requesterIds: 'number@c.us' });
+        /** The same for execution on group object (no need to provide the group ID): */
+        const group = await msg.getChat();
+        await group.approveGroupMembershipRequests({ requesterIds: 'number@c.us' });
+        /** To approve several membership requests: */
+        const approval = await client.approveGroupMembershipRequests(msg.from, {
+            requesterIds: ['number1@c.us', 'number2@c.us']
+        });
+        /**
+         * The example of the {@link approval} output:
+         * [
+         *   {
+         *     requesterId: 'number1@c.us',
+         *     message: 'Rejected successfully'
+         *   },
+         *   {
+         *     requesterId: 'number2@c.us',
+         *     error: 404,
+         *     message: 'ParticipantRequestNotFoundError'
+         *   }
+         * ]
+         *
+         */
+        console.log(approval);
+        /** To approve all the existing membership requests (simply don't provide any user IDs): */
+        await client.approveGroupMembershipRequests(msg.from);
+        /** To change the sleep value to 300 ms: */
+        await client.approveGroupMembershipRequests(msg.from, {
+            requesterIds: ['number1@c.us', 'number2@c.us'],
+            sleep: 300
+        });
+        /** To change the sleep value to random value between 100 and 300 ms: */
+        await client.approveGroupMembershipRequests(msg.from, {
+            requesterIds: ['number1@c.us', 'number2@c.us'],
+            sleep: [100, 300]
+        });
+        /** To explicitly disable the sleep: */
+        await client.approveGroupMembershipRequests(msg.from, {
+            requesterIds: ['number1@c.us', 'number2@c.us'],
+            sleep: null
+        });
     }
 });
 
@@ -353,3 +478,29 @@ client.on('group_admin_changed', (notification) => {
         /** Emitted when a current user is demoted to a regular user. */
         console.log(`You were demoted by ${notification.author}`);
 });
+
+client.on('group_membership_request', async (notification) => {
+    /**
+     * The example of the {@link notification} output:
+     * {
+     *     id: {
+     *         fromMe: false,
+     *         remote: 'groupId@g.us',
+     *         id: '123123123132132132',
+     *         participant: 'number@c.us',
+     *         _serialized: 'false_groupId@g.us_123123123132132132_number@c.us'
+     *     },
+     *     body: '',
+     *     type: 'created_membership_requests',
+     *     timestamp: 1694456538,
+     *     chatId: 'groupId@g.us',
+     *     author: 'number@c.us',
+     *     recipientIds: []
+     * }
+     *
+     */
+    console.log(notification);
+    /** You can approve or reject the newly appeared membership request: */
+    await client.approveGroupMembershipRequestss(notification.chatId, notification.author);
+    await client.rejectGroupMembershipRequests(notification.chatId, notification.author);
+});

package/index.d.ts

@@ -35,12 +35,8 @@ declare namespace WAWebJS {
         /** Unpins the Chat and returns its new Pin state */
         unpinChat(chatId: string): Promise<boolean>
 
-        /**
-         * Create a new group
-         * @param name group title
-         * @param participants an array of Contacts or contact IDs to add to the group
-         */
-        createGroup(name: string, participants: Contact[] | string[]): Promise<CreateGroupResult>
+        /** Creates a new group */
+        createGroup(title: string, participants?: string | Contact | Contact[] | string[], options?: CreateGroupOptions): Promise<CreateGroupResult|string>
 
         /** Closes the client */
         destroy(): Promise<void>
@@ -160,6 +156,15 @@ declare namespace WAWebJS {
         /** Deletes the current user's profile picture */
         deleteProfilePicture(): Promise<boolean>
 
+        /** Gets an array of membership requests */
+        getGroupMembershipRequests: (groupId: string) => Promise<Array<GroupMembershipRequest>>
+
+        /** Approves membership requests if any */
+        approveGroupMembershipRequests: (groupId: string, options: MembershipRequestActionOptions) => Promise<Array<MembershipRequestActionResult>>;
+
+        /** Rejects membership requests if any */
+        rejectGroupMembershipRequests: (groupId: string, options: MembershipRequestActionOptions) => Promise<Array<MembershipRequestActionResult>>;
+
         /** Generic event */
         on(event: string, listener: (...args: any) => void): this
 
@@ -210,6 +215,15 @@ declare namespace WAWebJS {
             notification: GroupNotification
         ) => void): this
 
+        /**
+         * Emitted when some user requested to join the group
+         * that has the membership approval mode turned on
+         */
+        on(event: 'group_membership_request', listener: (
+            /** GroupNotification with more information about the action */
+            notification: GroupNotification
+        ) => void): this
+
         /** Emitted when group settings are updated, such as subject, description or picture */
         on(event: 'group_update', listener: (
             /** GroupNotification with more information about the action */
@@ -522,14 +536,47 @@ declare namespace WAWebJS {
         plugged: boolean,
     }
 
+    /** An object that handles options for group creation */
+    export interface CreateGroupOptions {
+        /**
+         * The number of seconds for the messages to disappear in the group,
+         * won't take an effect if the group is been creating with myself only
+         * @default 0
+         */
+        messageTimer?: number
+        /**
+         * The ID of a parent community group to link the newly created group with,
+         * won't take an effect if the group is been creating with myself only
+         */
+        parentGroupId?: string
+        /** If true, the inviteV4 will be sent to those participants
+         * who have restricted others from being automatically added to groups,
+         * otherwise the inviteV4 won't be sent
+         * @default true
+         */
+        autoSendInviteV4?: boolean,
+        /**
+         * The comment to be added to an inviteV4 (empty string by default)
+         * @default ''
+         */
+        comment?: string
+    }
+
+    /** An object that handles the result for createGroup method */
     export interface CreateGroupResult {
-        /** ID for the group that was just created */
-        gid: string,
-        /** participants that were not added to the group. 
-         * Keys represent the ID for participant that was not added and its value is a status code
-         * that represents the reason why participant could not be added. 
-         * This is usually 403 if the user's privacy settings don't allow you to add them to groups. */
-        missingParticipants: Record<string, string>
+        /** A group title */
+        title: string;
+        /** An object that handles the newly created group ID */
+        gid: ChatId;
+        /** An object that handles the result value for each added to the group participant */
+        participants: {
+            [participantId: string]: {
+                statusCode: number,
+                message: string,
+                isGroupCreator: boolean,
+                isInviteV4Sent: boolean
+            };
+        };
     }
 
     export interface GroupNotification {
@@ -589,6 +636,7 @@ declare namespace WAWebJS {
         GROUP_JOIN = 'group_join',
         GROUP_LEAVE = 'group_leave',
         GROUP_ADMIN_CHANGED = 'group_admin_changed',
+        GROUP_MEMBERSHIP_REQUEST = 'group_membership_request',
         GROUP_UPDATE = 'group_update',
         QR_RECEIVED = 'qr',
         LOADING_SCREEN = 'loading_screen',
@@ -879,13 +927,23 @@ declare namespace WAWebJS {
         _serialized: string,
     }
 
+    /** Options for sending a location */
+    export interface LocationSendOptions {
+        /** Location name */
+        name?: string;
+        /** Location address */
+        address?: string;
+        /** URL address to be shown within a location message */
+        url?: string;
+    }
+
     /** Location information */
     export class Location {
-        description?: string | null
-        latitude: string
-        longitude: string
+        latitude: string;
+        longitude: string;
+        options?: LocationSendOptions;
         
-        constructor(latitude: number, longitude: number, description?: string)
+        constructor(latitude: number, longitude: number, options?: LocationSendOptions)
     }
 
     export interface Label {
@@ -1167,9 +1225,9 @@ declare namespace WAWebJS {
         /** Returns the Contact that corresponds to this Chat. */
         getContact: () => Promise<Contact>,
         /** Marks this Chat as unread */
-        markUnread: () => Promise<void>
+        markUnread: () => Promise<void>,
         /** Returns array of all Labels assigned to this Chat */
-        getLabels: () => Promise<Label[]>
+        getLabels: () => Promise<Label[]>,
         /** Add or remove labels to this Chat */
         changeLabels: (labelIds: Array<string | number>) => Promise<void>
     }
@@ -1229,18 +1287,70 @@ declare namespace WAWebJS {
     export type ChangeParticipantsPermissions = 
         (participantIds: Array<string>) => Promise<{ status: number }>
 
-    /** Adds or removes a list of participants by ID to the group */
-    export type ChangeGroupParticipants = 
-        (participantIds: Array<string>) => Promise<{
-            status: number;
-            participants: Array<{
-                [key: string]: {
-                    code: number
-                }
-            }>
-         } & {
-             [key: string]: number;
-         }>
+    /** An object that handles the result for addParticipants method */
+    export interface AddParticipantsResult {
+        [participantId: string]: {
+            code: number;
+            message: string;
+            isInviteV4Sent: boolean,
+        };
+    };
+
+    /** An object that handles options for adding participants */
+    export interface AddParticipantsOptions {
+        /**
+         * The number of milliseconds to wait before adding the next participant.
+         * If it is an array, a random sleep time between the sleep[0] and sleep[1] values will be added
+         * (the difference must be >=100 ms, otherwise, a random sleep time between sleep[1] and sleep[1] + 100
+         * will be added). If sleep is a number, a sleep time equal to its value will be added
+         * @default [250,500]
+         */
+        sleep?: Array<number>|number,
+        /**
+         * If true, the inviteV4 will be sent to those participants
+         * who have restricted others from being automatically added to groups,
+         * otherwise the inviteV4 won't be sent
+         * @default true
+         */
+        autoSendInviteV4?: boolean,
+        /**
+         * The comment to be added to an inviteV4 (empty string by default)
+         * @default ''
+         */
+        comment?: string
+    };
+
+    /** An object that handles the information about the group membership request */
+    export interface GroupMembershipRequest {
+        /** The wid of a user who requests to enter the group */
+        id: Object;
+        /** The wid of a user who created that request */
+        addedBy: Object;
+        /** The wid of a community parent group to which the current group is linked */
+        parentGroupId: Object | null;
+        /** The method used to create the request: NonAdminAdd/InviteLink/LinkedGroupJoin */
+        requestMethod: string,
+        /** The timestamp the request was created at */
+        t: number
+    }
+
+    /** An object that handles the result for membership request action */
+    export interface MembershipRequestActionResult {
+        /** User ID whos membership request was approved/rejected */
+        requesterId: Array<string> | string | null;
+        /** An error code that occurred during the operation for the participant */
+        error?: number;
+        /** A message with a result of membership request action */
+        message: string;
+    }
+
+    /** Options for performing a membership request action  */
+    export interface MembershipRequestActionOptions {
+        /** User ID/s who requested to join the group, if no value is provided, the method will search for all membership requests for that group */
+        requesterIds: Array<string> | string | null;
+        /** The number of milliseconds to wait before performing an operation for the next requester. If it is an array, a random sleep time between the sleep[0] and sleep[1] values will be added (the difference must be >=100 ms, otherwise, a random sleep time between sleep[1] and sleep[1] + 100 will be added). If sleep is a number, a sleep time equal to its value will be added. By default, sleep is an array with a value of [250, 500] */
+        sleep: Array<number> | number | null;
+    }
 
     export interface GroupChat extends Chat {
         /** Group owner */
@@ -1252,9 +1362,9 @@ declare namespace WAWebJS {
         /** Group participants */
         participants: Array<GroupParticipant>;
         /** Adds a list of participants by ID to the group */
-        addParticipants: ChangeGroupParticipants;
+        addParticipants: (participantIds: string|string[], options?: AddParticipantsOptions) => Promise<Object.<string, AddParticipantsResult>|string>;
         /** Removes a list of participants by ID to the group */
-        removeParticipants: ChangeGroupParticipants;
+        removeParticipants: (participantIds: string[]) => Promise<{ status: number }>;
         /** Promotes participants by IDs to admins */
         promoteParticipants: ChangeParticipantsPermissions;
         /** Demotes participants by IDs to regular users */
@@ -1263,17 +1373,34 @@ declare namespace WAWebJS {
         setSubject: (subject: string) => Promise<boolean>;
         /** Updates the group description */
         setDescription: (description: string) => Promise<boolean>;
-        /** Updates the group settings to only allow admins to send messages 
-         * @param {boolean} [adminsOnly=true] Enable or disable this option 
+        /** Updates the group settings to only allow admins to send messages
+         * @param {boolean} [adminsOnly=true] Enable or disable this option
          * @returns {Promise<boolean>} Returns true if the setting was properly updated. This can return false if the user does not have the necessary permissions.
          */
         setMessagesAdminsOnly: (adminsOnly?: boolean) => Promise<boolean>;
         /**
          * Updates the group settings to only allow admins to edit group info (title, description, photo).
-         * @param {boolean} [adminsOnly=true] Enable or disable this option 
+         * @param {boolean} [adminsOnly=true] Enable or disable this option
          * @returns {Promise<boolean>} Returns true if the setting was properly updated. This can return false if the user does not have the necessary permissions.
          */
         setInfoAdminsOnly: (adminsOnly?: boolean) => Promise<boolean>;
+        /**
+         * Gets an array of membership requests
+         * @returns {Promise<Array<GroupMembershipRequest>>} An array of membership requests
+         */
+        getGroupMembershipRequests: () => Promise<Array<GroupMembershipRequest>>;
+        /**
+         * Approves membership requests if any
+         * @param {MembershipRequestActionOptions} options Options for performing a membership request action
+         * @returns {Promise<Array<MembershipRequestActionResult>>} Returns an array of requester IDs whose membership requests were approved and an error for each requester, if any occurred during the operation. If there are no requests, an empty array will be returned
+         */
+        approveGroupMembershipRequests: (options: MembershipRequestActionOptions) => Promise<Array<MembershipRequestActionResult>>;
+        /**
+         * Rejects membership requests if any
+         * @param {MembershipRequestActionOptions} options Options for performing a membership request action
+         * @returns {Promise<Array<MembershipRequestActionResult>>} Returns an array of requester IDs whose membership requests were rejected and an error for each requester, if any occurred during the operation. If there are no requests, an empty array will be returned
+         */
+        rejectGroupMembershipRequests: (options: MembershipRequestActionOptions) => Promise<Array<MembershipRequestActionResult>>;
         /** Gets the invite code for a specific group */
         getInviteCode: () => Promise<string>;
         /** Invalidates the current group invite code and generates a new one */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-web.js",
-  "version": "1.22.2-alpha.1",
+  "version": "1.22.2-alpha.3",
   "description": "Library for interacting with the WhatsApp Web API ",
   "main": "./index.js",
   "typings": "./index.d.ts",