Chat List Schema (`model-storage-chat.json`)
Relevant source files
The following files were used as context for generating this wiki page:The model-storage-chat.json file provides essential metadata that maps internal WhatsApp chat identifiers to human-readable names. It is a critical component for the web application, as it allows users to filter and view analytics by specific conversations. Without this file, the application can only query messages from the msgstore.db database but cannot associate them with specific chat names, such as "John Doe" or "Family Group".
This file is not part of the standard Android backup but is generated manually by the user. The process involves running a JavaScript snippet in the browser's developer tools while on the WhatsApp Web interface. Once generated and downloaded, it is uploaded into the web application alongside the decrypted msgstore.db file, enabling the full suite of search and analysis features.
Sources: README.md:46-60, web/src/Pages/SearchSQLite/components/UploadStep.jsx:40-45
Generation Process
The model-storage-chat.json file is created by executing the dumbWAChats.js snippet within the context of WhatsApp Web. This script accesses the application's internal models to extract the list of all chats and their associated names.
Sources: README.md:46-60, chatsExporter/dumbWAChats.js
The generation flow is as follows:
- The user navigates to
https://web.whatsapp.comand waits for all chats to load. - The user opens the browser's Developer Tools (
F12). - The content of
dumbWAChats.jsis pasted into a new snippet and executed. - The script programmatically extracts the chat data and triggers a browser download of the
model-storage-chat.jsonfile.
This diagram illustrates the manual generation process performed by the user.
Sources: README.md:48-60
File Schema and Structure
The model-storage-chat.json file is a JSON array where each object represents a single WhatsApp chat. The raw file contains a minimal set of fields necessary for identification.
Sources: web/src/Pages/SearchSQLite/services/fileService.js:52-68
Raw JSON Schema
The file directly downloaded from the browser contains objects with the following properties:
| Field | Type | Description |
|---|---|---|
id | string | The unique identifier for the chat, e.g., 1234567890@c.us or 123-456@g.us. |
name | string | The display name of the chat or group. Can be null or empty. |
Sources: web/src/Pages/SearchSQLite/services/fileService.js:56-59
Parsed Data Structure
After the file is uploaded to the web application, the FileService.parseChatFile method processes it into a more structured format for internal use. This involves splitting the id to extract the numerical identifier and the chat type.
| Field | Type | Description | Derivation |
|---|---|---|---|
id | string | The numerical part of the original ID. | chat.id.split('@')[0] |
name | string | The display name of the chat. Defaults to the id if name is missing. | `chat.name |
type | string | The type of chat, typically c for contact or g for group. | Derived from the part of the original ID after @, e.g., g.us -> g |
Sources: web/src/Pages/SearchSQLite/services/fileService.js:55-61
The following diagram shows the transformation from the raw JSON object to the parsed object used within the application.
Processing in the Web Application
The model-storage-chat.json file is a key part of the initial setup in the SearchSQLite page. The user must upload it along with the msgstore.db file in the first step.
Sources: web/src/Pages/SearchSQLite/index.jsx:28-34, web/src/Pages/SearchSQLite/components/UploadStep.jsx:40-45
The processing flow is as follows:
- The user uploads the
model-storage-chat.jsonfile via the<Uploader>component inUploadStep.jsx. - The
useFileUploadhook manages the file state. - The
FileService.readAsTextmethod reads the file content as a string. FileService.parseChatFileis called to parse the JSON string and transform it into thechatListarray of objects.- The resulting
chatListis stored in theSearchSQLitecomponent's state and passed down to child components.
This sequence diagram shows the flow of data from file upload to state update.
The core parsing logic is handled by the parseChatFile static method.
// web/src/Pages/SearchSQLite/services/fileService.js:52-68
static parseChatFile(jsonString) {
try {
const jsonData = JSON.parse(jsonString);
console.log('Parsed JSON:', jsonData);
const chatList = jsonData.map((chat) => {
let [id, type] = chat.id.split('@');
type = type.split('.')[0];
const name = chat.name || id;
return { id, name, type };
});
return chatList;
} catch (error) {
console.error('Error parsing JSON file:', error);
throw new Error('Failed to parse chat file');
}
}
Sources: web/src/Pages/SearchSQLite/services/fileService.js:52-68
Usage in UI and Queries
The parsed chatList data is primarily used in the SearchStep component to populate a dropdown menu (SelectPicker) that allows users to filter messages by a specific chat.
Sources: web/src/Pages/SearchSQLite/components/SearchStep.jsx:67-83
The SelectPicker component is configured to display the chat name and use the id as the value. It also renders an icon (PeoplesIcon for groups, AdminIcon for individual chats) based on the type property derived during parsing.
// web/src/Pages/SearchSQLite/components/SearchStep.jsx:67-83
<SelectPicker
data={chatList}
label="Chat"
labelKey="name"
valueKey="id"
style={{ width: 400 }}
placeholder="If empty, all chats are selected"
value={selectedChat}
onChange={onChatChange}
renderMenuItem={(name, item) => (
<div>
{item.type === 'g' ? <PeoplesIcon /> : <AdminIcon />} {name}
</div>
)}
renderValue={(name, item) => (
<div>
{item.type === 'g' ? <PeoplesIcon /> : <AdminIcon />} {item.name}
</div>
)}
/>
Sources: web/src/Pages/SearchSQLite/components/SearchStep.jsx:67-83
When a user selects a chat, the corresponding id is stored in the selectedChat state. This id is then passed to buildMessagesQuery to construct the final SQL query, which filters messages by joining the message table with the chat and jid tables. The getChatName utility also uses the chatList to retrieve the name for display purposes.
Sources: web/src/Pages/SearchSQLite/hooks/useMessageSearch.js:40-47, web/src/Pages/SearchSQLite/utils/queryBuilder.js:21-23, web/src/Pages/SearchSQLite/utils/queryBuilder.js:81-86
Conclusion
The model-storage-chat.json file is a cornerstone of the user experience in the WhatsApp Chat Analytics tool. Although it requires a manual extraction step, it provides the indispensable link between raw database identifiers and user-friendly chat names. Its schema, while simple, is effectively processed and integrated into the application's state to power the chat filtering functionality, which is fundamental to performing targeted analysis.