Skip to content

Add whatsapp groups documentation for multiple numbers updates #654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mahajantejas merged 3 commits into from
Jul 17, 2026
Merged

Add whatsapp groups documentation for multiple numbers updates #654

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0e2bb7b
Enhance WhatsApp Groups Automation documentation
mahajantejas Jul 15, 2026
fcc2d53
Revise WhatsApp Groups Automation Features documentation
mahajantejas Jul 15, 2026
74dedc9
Update notes on primary phone selection process
mahajantejas Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 127 additions & 1 deletion docs/6. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,99 @@
### **5 minute read                                                                                                                         `Beginner`**
<h3>
<table>
<tr>
<td><b>5 minutes read</b></td>
<td style={{paddingLeft: '40px'}}><b>Level: Beginner</b></td>
<td style={{paddingLeft: '40px'}}><b>Last Updated: July 2026</b></td>
</tr>
</table>
</h3>

## User Guide: WhatsApp Groups Automation Features: Basic
Comment thread
akanshaaa19 marked this conversation as resolved.
This document provides details on using basic features of syncing all the WhatsApp Groups, sending messages and media to the groups from the Glific interface, creating collections or groups of groups to send targetted messages to a large number of groups and scheduling messages to the collections in advance.

@coderabbitai coderabbitai Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the typo in the introduction.

Change targetted to targeted; consider replacing “a large number of groups” with “many groups” for clearer wording.

🧰 Tools
🪛 LanguageTool

[grammar] ~12-~12: Ensure spelling is correct
Context: ...collections or groups of groups to send targetted messages to a large number of groups an...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

[style] ~12-~12: To reduce wordiness, try specifying a number or using “many” or “numerous” instead.
Context: ...of groups to send targetted messages to a large number of groups and scheduling messages to the c...

(LARGE_NUMBER_OF)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/6`. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md at
line 12, Update the introduction text to correct “targetted” to “targeted,” and
replace “a large number of groups” with “many groups” for clearer wording.

Source: Linters/SAST tools


### Phone connection status and reconnecting
The WhatsApp Phones page now shows each managed phone's live connection status, and a phone that gets logged out can now be reconnected directly from Glific by scanning a QR code.

#### Viewing Connection Status
1. Go to `WhatsApp Groups` → `WhatsApp Phones`.
2. Each row shows the phone number, an optional label, its current Status, and when it was Last checked.
3. Click Sync statuses (top right) at any time to refresh the status of all listed phones on demand.

<img width="" height="273" alt="Screenshot 2026-07-15 at 6 30 19 PM" src="https://github.com/user-attachments/assets/ef26f4ab-0f19-4a4e-8464-14be718f9e0a" />

WhatsApp Phones — status list
1. Sync statuses — manually refreshes the connection status of every phone in the list.
2. Status badge — Active (green) means the phone is connected and sending/receiving normally; Qr-Screen (red) means it has been logged out and needs to be reconnected.
3. Actions — QR icon appears for a disconnected phone; click it to open the reconnect flow.


### Reconnecting a Logged-Out Phone
If a phone shows a Qr-Screen status, it has been logged out of WhatsApp Web (e.g. session expired, phone unlinked). Use this flow instead of going to the Maytapi console.
1. On the WhatsApp Phones page, click the QR icon in the Actions column for the affected phone.
2. The Reconnect dialog opens with a live QR code and instructions.
3. On the phone itself: open WhatsApp → Linked devices → Link a device, then scan the QR code shown in Glific.

<img width="" height="662" alt="Screenshot 2026-07-15 at 6 31 37 PM" src="https://github.com/user-attachments/assets/4115ad3b-a9e3-4295-bc50-f6efe8b0f09c" />

4. Reconnect dialog — QR code to scan
- QR code — scan this from the phone's WhatsApp → Linked devices → Link a device screen.
- Status: Qr-Screen — confirms the phone is currently disconnected and waiting to be scanned.
- Log out & refresh QR — use if the QR code expires, to generate a fresh one.

5. After scanning, the dialog shows a loading state while WhatsApp links the session.

<img width="" height="709" alt="Screenshot 2026-07-15 at 6 32 16 PM" src="https://github.com/user-attachments/assets/ce6ad311-b426-472e-8b64-1e93fc7ebefc" />

6. Reconnect dialog — linking in progress. Once linked, WhatsApp Web loads the phone's chats inside the dialog.

<img width="" height="622" alt="Screenshot 2026-07-15 at 6 32 59 PM" src="https://github.com/user-attachments/assets/5b2ba614-38f1-4c65-8420-3d8ceec5fcc4" />

7. Reconnect dialog — session linked, chats loaded
8. Back on the WhatsApp Phones page, click Sync statuses to confirm the phone now shows Active.
Comment on lines +38 to +52

@coderabbitai coderabbitai Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Normalize ordered-list numbering.

These steps use hard-coded numbering across images and nested content, and the group-creation steps repeat 5. Use 1. for each Markdown list item or renumber the sequence consistently so the rendered instructions are unambiguous.

Also applies to: 76-85

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 38-38: Ordered list item prefix
Expected: 1; Actual: 4; Style: 1/1/1

(MD029, ol-prefix)

[warning] 43-43: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/1/1

(MD029, ol-prefix)

[warning] 47-47: Ordered list item prefix
Expected: 1; Actual: 6; Style: 1/1/1

(MD029, ol-prefix)

[warning] 51-51: Ordered list item prefix
Expected: 1; Actual: 7; Style: 1/2/3

(MD029, ol-prefix)

[warning] 52-52: Ordered list item prefix
Expected: 2; Actual: 8; Style: 1/2/3

(MD029, ol-prefix)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/6`. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md
around lines 38 - 52, Normalize the ordered-list numbering throughout the
WhatsApp Groups Automation documentation, including the referenced
group-creation steps around the later section. Replace hard-coded sequential
numbers with Markdown `1.` markers for each ordered-list item, including items
surrounding images and nested content, so the rendered sequence remains
unambiguous and no steps repeat.

Source: Linters/SAST tools


<img width="" height="278" alt="Screenshot 2026-07-15 at 6 33 31 PM" src="https://github.com/user-attachments/assets/1e950b06-1123-4e42-bf77-831fc6254bd0" />

- Note: Reconnecting only re-links the WhatsApp Web session for that phone; it does not affect groups, flows, or message history tied to it.

### Group Chats

1. Shows all the groups and the group chats that the maytapi linked phone number is part of.
2. Provides an interface to see the chats, group details, and send messages and media to the groups.

### Create Groups

Creating a WhatsApp Group
Use this to spin up a new WhatsApp group from Glific and add members in bulk, instead of creating the group manually on WhatsApp first.

<img width="" height="310" alt="Screenshot 2026-07-15 at 6 15 19 PM" src="https://github.com/user-attachments/assets/8bb3f0d6-1c47-4e96-9ec3-4029aba77bd5" />

1. Go to `WhatsApp Groups` → `Group Chats`.
2. Click `New group` (top right of the Groups panel).
3. In the Create WhatsApp group dialog, fill in the fields (see callouts below).

<img width="" height="420" alt="Screenshot 2026-07-15 at 6 16 19 PM" src="https://github.com/user-attachments/assets/fd2343c1-02d9-4cb8-8038-dab26c6fe13d" />

4. Create WhatsApp group dialog
- Group name — the name of the WhatsApp group as it will appear on WhatsApp.
- Creator phone — the managed phone number that creates the group on WhatsApp; it becomes the group's primary phone in Glific.
- Upload File — upload a CSV of members to add to the group. Must include a phone column; a name column is optional.
- View Sample — opens a [template Google Sheet](https://docs.google.com/spreadsheets/d/1-oupACzXqNWURa9nUv0rvpLrBNRTMRMN5EG-mY3zCvg/copy) showing the expected CSV format (see below).

5. CSV Template for Bulk Member Import, add the names and phone numbers with the country code this template and export the file as a csv
Comment on lines +79 to +82

@coderabbitai coderabbitai Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Clarify that the CSV name column is optional.

Line 79 says name is optional, but line 82 instructs readers to add names and phone numbers, making names appear mandatory. Rewrite this as: “Add phone numbers with country codes; names are optional. Export the file as CSV.”

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 82-82: Ordered list item prefix
Expected: 2; Actual: 5; Style: 1/2/3

(MD029, ol-prefix)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/6`. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md
around lines 79 - 82, Update the “CSV Template for Bulk Member Import”
instruction to state that phone numbers must include country codes, names are
optional, and the completed file should be exported as CSV.

<img width="" height="264" alt="Screenshot 2026-07-15 at 6 19 01 PM" src="https://github.com/user-attachments/assets/14fd19a6-4c00-4def-8fc0-fd8d39f3efdf" />

5. Create — submits the form and creates the group on WhatsApp with the uploaded members.

### Filtering groups by phone number
When an organization manages multiple WhatsApp numbers, the groups list can get long. Use the Phone Number filter to narrow it down to groups tied to one or more specific numbers.

<img width="" height="316" alt="Screenshot 2026-07-15 at 6 23 37 PM" src="https://github.com/user-attachments/assets/ea0d6e29-3241-4202-8180-56aa172d14f7" />

1. Go to `WhatsApp Groups` → `Group Chats`.
2. In the Groups panel, click the Phone Number dropdown, next to Sync and New group.
3. Check one or more phone numbers from the list.
4. The groups list updates to show only groups linked to the selected number(s).

### Group Collections
1. Group collection is a group of groups. A way to club together with groups. This is to enable sending or scheduling of messages to the bulk of the groups from the single action.

Expand All @@ -21,11 +107,51 @@ This document provides details on using basic features of syncing all the WhatsA

<img width="1047" alt="Screenshot 2024-04-16 at 3 28 16 PM" src="https://github.com/glific/docs/assets/141305477/e3368d3f-8c69-4e21-ae86-66b0dade17e8"/>

### Setting a Primary Phone (Collections & Groups)
When a group or a collection of groups has more than one managed phone connected, only one phone — the primary — is actually used to send messages. Glific now lets you set (and change) that primary phone from the Collections page or from an individual group.

#### Why use more than one phone per group?
Connecting multiple managed phones to a group (or collection) and being able to switch the primary on demand protects program delivery in two common situations:
- Avoiding message delays — if the primary number is rate-limited or slow, switching to a healthy secondary keeps broadcasts moving instead of stalling behind one number.
- Avoiding outages from number blocks/suspensions — if Meta blocks or suspends a number, the group isn't stuck waiting on that number to be restored; a different active phone can be promoted to primary immediately to keep messages flowing.

#### Setting a Primary Phone for a Collection

Use this to set one phone as primary across every group in a collection in a single action, instead of updating each group individually.
1. Go to `WhatsApp Groups` → `Collections`.
2. Go inside the collection, then click Set primary phone (top right, next to Add groups).
<img width="" height="442" alt="Screenshot 2026-07-15 at 6 41 54 PM" src="https://github.com/user-attachments/assets/a5f25982-746d-4520-8c9c-f6d24350d4a5" />

3. In the dialog, select a phone from Select a phone and click Apply.
<img width="577" height="492" alt="Screenshot 2026-07-15 at 6 42 22 PM" src="https://github.com/user-attachments/assets/82816d66-4529-4553-8b97-a9c7abbd4d3f" />

4. Apply — confirms the change. The phone becomes primary in every group in the collection where it is an active member; groups where it isn't a member are skipped (and reported, so nothing fails silently).


- Note: If the selected phone isn't a member of a particular group at all, that group's primary phone is left unchanged — or the next available phone in the groups is marked as primary.
- Note: If a group belongs to more than one collection, whichever collection-level primary-phone action was applied most recently is the one that takes effect for that group.
- Note: Setting primary for a collection happens in the bg and once done you get a notification with the status report because sometimes the phone might not be present in one of the groups
Comment on lines +131 to +133

@coderabbitai coderabbitai Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n -C 5 'Set primary phone|next available|skipped|status report|primary phone' --glob '!docs/**' .

Repository: glific/docs

Length of output: 762

🏁 Script executed:

#!/bin/bash
set -euo pipefail

file='docs/6. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md'

echo '--- surrounding lines ---'
sed -n '118,140p' "$file" | cat -n

echo
echo '--- nearby references in docs ---'
rg -n -C 3 'selected phone|next available|skipped|status report|primary phone|collection-level primary-phone' "docs/6. WhatsApp Groups Automation" .

Repository: glific/docs

Length of output: 13614

🏁 Script executed:

#!/bin/bash
set -euo pipefail

file='docs/6. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md'

echo '--- lines 124-136 ---'
nl -ba "$file" | sed -n '124,136p'

Repository: glific/docs

Length of output: 211

🏁 Script executed:

#!/bin/bash
set -euo pipefail

file='docs/6. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md'

rg -n -C 2 'skipped|next available|status report|selected phone|primary phone|collection' "$file"

Repository: glific/docs

Length of output: 5601

🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n -C 2 'status report|next available phone|selected phone isn.t a member|primary phone is left unchanged|collection-level primary-phone action' docs

Repository: glific/docs

Length of output: 1296

Clarify the fallback rule for groups missing the selected phone. Line 128 says those groups are skipped and reported, but line 131 says the next available phone may become primary. Keep one deterministic rule here and spell out when fallback applies so admins know which groups will change.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/6`. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md
around lines 131 - 133, Clarify the collection-level primary-phone notes so
groups missing the selected phone follow one deterministic rule consistent with
the earlier skip-and-report behavior. Explicitly state whether fallback to the
next available phone occurs, and under what conditions, while ensuring admins
can identify which groups will be changed.


#### Setting a Primary Phone for a Single Group
The same change can be made at the individual group level, which is useful when you only need to switch one group over — for example, to route around a number that Meta has temporarily blocked.

<img width="" height="389" alt="Screenshot 2026-07-15 at 6 43 28 PM" src="https://github.com/user-attachments/assets/15c39f09-a79a-444b-b1c8-9ddec24fb7ef" />

1. Open the group in Group Chats, click the chevron next to the group name, and choose View group details.
2. In Group Details, open the Phones tab.
3. Click Set as primary next to the phone you want to promote.

<img width="634" height="380" alt="Screenshot 2026-07-15 at 6 44 04 PM" src="https://github.com/user-attachments/assets/e7d74cef-0210-418f-a68c-3443ad63ee8b" />

- Note: Group-level and collection-level changes both write to the same setting — whichever one was applied most recently wins, whether it was set from the group itself or from a collection it belongs to.


### Sending Messages
1. Send message to the group via group chat
<img width="1038" alt="Screenshot 2024-04-16 at 3 28 59 PM" src="https://github.com/glific/docs/assets/141305477/d972cf1b-1443-43df-b3fd-0119f63464cf" />

2. Send message to a `Collection` by navigating to `Collections` list next to `Groups` window.

Comment on lines 150 to +154

@coderabbitai coderabbitai Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Mention the primary phone in the sending steps.

The new primary-phone section explains which phone sends messages, but the actual group and collection sending instructions do not tell users to verify or set the primary phone before sending. Add that prerequisite explicitly to prevent messages being sent through an unexpected managed number.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/6`. WhatsApp Groups Automation/WhatsApp Groups Automation Features.md
around lines 148 - 152, Update the sending steps for group chats and Collections
in the WhatsApp Groups Automation Features documentation to explicitly instruct
users to verify or set the primary phone before sending. Keep the existing
navigation and sending instructions intact while adding this prerequisite to
both flows.


### Sending Media
#### Prerequisite for sending media:
Expand Down
Loading