Data Schemas¶

Standardized schemas for storage in @arcaelas/whatsapp.

Principles: - Minimal: Only essential fields - Flat: No unnecessary nesting - Typed: Explicit types - Temporal: Timestamps in milliseconds UTC - Nullable: null for absence, never undefined

Raw Schemas¶

Classes work with "raw" objects that contain protocol properties. Getters/setters expose a simplified API.

Contact Raw¶

Raw contact object properties (IContactRaw).

Raw Example¶

{
    "id": "584144709840@s.whatsapp.net",
    "lid": "140913951141911@lid",
    "name": "Juan Perez",
    "notify": "Juanito",
    "verifiedName": null,
    "imgUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
    "status": "Available 24/7"
}

Chat Raw¶

Raw conversation object properties (IChatRaw).

IGroupParticipant¶

Raw Example¶

{
    "id": "120363123456789@g.us",
    "name": "Development Team",
    "displayName": null,
    "description": "Project coordination group",
    "unreadCount": 5,
    "readOnly": false,
    "archived": false,
    "pinned": 1767371367857,
    "muteEndTime": null,
    "markedAsUnread": false,
    "createdAt": 1700000000,
    "createdBy": "584144709840@s.whatsapp.net",
    "participant": [
        { "id": "584144709840@s.whatsapp.net", "admin": "superadmin" },
        { "id": "584121234567@s.whatsapp.net", "admin": null }
    ],
    "ephemeralExpiration": 604800
}

Message Raw¶

Raw message object properties. The library stores two parts: IMessageIndex (metadata) and WAMessage (full Baileys raw).

MessageKey (key)¶

Main Properties¶

Message Statuses (status)¶

Media Properties¶

Temporal Properties¶

Reaction and Poll Properties¶

Receipt Properties¶

Stub Properties (System Messages)¶

Business Properties¶

Status/History Properties¶

Pin Properties¶

Bot/AI Properties¶

Internal Properties¶

Raw Example¶

{
    "key": {
        "remoteJid": "584144709840@s.whatsapp.net",
        "fromMe": false,
        "id": "AC07DE0D18FA8254897A26C90B2FFD98",
        "participant": null
    },
    "message": {
        "extendedTextMessage": {
            "text": "Hello world",
            "contextInfo": {
                "stanzaId": "AC9BE0D81D965A3C240B6ACAA891C6FD",
                "participant": "584121234567@s.whatsapp.net",
                "isForwarded": false,
                "forwardingScore": 0,
                "expiration": 604800
            }
        }
    },
    "messageTimestamp": 1767366759,
    "status": 4,
    "pushName": "Juan Perez",
    "broadcast": false,
    "starred": false,
    "duration": null,
    "labels": [],
    "ephemeralStartTimestamp": 1767366759,
    "ephemeralDuration": 604800,
    "reactions": [
        { "text": "❤️", "groupingKey": "❤️", "senderTimestampMs": 1767366800000 }
    ],
    "userReceipt": [
        { "userJid": "584144709840@s.whatsapp.net", "readTimestamp": 1767366800 }
    ]
}

Message Content¶

Content types inside message.

Text¶

Media¶

Media Properties (common)¶

Location¶

Poll¶

Reaction¶

Protocol¶

ProtocolMessage Types¶

ContextInfo¶

API Schemas¶

Simplified schemas exposed by classes.

Contact¶

Storage Key¶

contact/{id}/index

Stored format: IContactRaw JSON (id, lid, name, notify, verifiedName, imgUrl, status).

Chat¶

Storage Key¶

chat/{id}/index

Stored format: IChatRaw JSON (id, name, displayName, description, unreadCount, readOnly, archived, pinned, muteEndTime, markedAsUnread, participant, createdBy, createdAt, ephemeralExpiration).

Message¶

IMessageIndex (stored in chat/{cid}/message/{id}/index)¶

Instance methods¶

Storage¶

Field Summary¶

Storage Guidelines¶

Storage strategies for different backends.

Primary Fields (Columns/Indexes)¶

Scalar fields used for filters/searches:

NoSQL Strategy (Key-Value)¶

For FileEngine, RedisEngine, or other key-value stores.

Key Structure¶

contact/{id}/index          -> IContactRaw JSON
lid/{lid}                   -> JID string
chat/{id}/index             -> IChatRaw JSON
chat/{cid}/messages         -> Message index text file
chat/{cid}/message/{id}/index   -> IMessageIndex JSON
chat/{cid}/message/{id}/content -> Buffer base64
chat/{cid}/message/{id}/raw     -> WAMessage JSON

Storage Format¶

// contact/{id}/index -- stores IContactRaw
{
    "id": "584144709840@s.whatsapp.net",
    "lid": "140913951141911@lid",
    "name": "Juan Perez",
    "notify": "Juanito",
    "verifiedName": null,
    "imgUrl": "https://...",
    "status": "Available"
}

// chat/{id}/index -- stores IChatRaw
{
    "id": "120363123456789@g.us",
    "name": "Dev Team",
    "displayName": null,
    "description": "Group description",
    "unreadCount": 5,
    "readOnly": false,
    "archived": false,
    "pinned": 1767371367857,
    "muteEndTime": null,
    "markedAsUnread": false,
    "participant": [
        { "id": "584144709840@s.whatsapp.net", "admin": "superadmin" }
    ],
    "createdBy": "584144709840@s.whatsapp.net",
    "createdAt": 1700000000,
    "ephemeralExpiration": 604800
}

// chat/{cid}/message/{id}/index -- stores IMessageIndex
{
    "id": "AC07DE0D18FA8254897A26C90B2FFD98",
    "cid": "584144709840@s.whatsapp.net",
    "mid": null,
    "me": false,
    "type": "text",
    "author": "584144709840@s.whatsapp.net",
    "status": 4,
    "starred": false,
    "forwarded": false,
    "created_at": 1767366759000,
    "deleted_at": null,
    "mime": "text/plain",
    "caption": "",
    "edited": false
}

Advantages¶

• Simplicity: Everything is JSON, no migrations
• Atomicity: One record = one key
• Flexibility: Add fields without altering structure

Considerations¶

Listings and Filters:

# List contacts
engine.list("contact/")

# List messages of a chat
Read chat/{cid}/messages index, then fetch each message

# Filter starred messages
Requires iterating and filtering in memory

Cleanup (Cascade Delete):

# Delete chat and all its messages
engine.set("chat/{cid}", null)
# The engine cascade-deletes all sub-keys: chat/{cid}/*

Orphan Data: - When deleting chat: set("chat/{cid}", null) removes all keys with prefix chat/{cid}/ - When deleting contact: set("contact/{id}/index", null) (no dependencies)

SQL Strategy (Relational)¶

For PostgreSQL, MySQL, SQLite.

Table Schema¶

-- Contacts (stores IContactRaw fields)
CREATE TABLE contacts (
    id VARCHAR(50) PRIMARY KEY,
    lid VARCHAR(50),
    name VARCHAR(255),
    notify VARCHAR(255),
    verified_name VARCHAR(255),
    img_url TEXT,
    status TEXT
);

-- Chats (stores IChatRaw fields)
CREATE TABLE chats (
    id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(255),
    display_name VARCHAR(255),
    description TEXT,
    unread_count INTEGER,
    read_only BOOLEAN DEFAULT FALSE,
    archived BOOLEAN DEFAULT FALSE,
    pinned BIGINT,  -- timestamp or NULL
    mute_end_time BIGINT,  -- timestamp or NULL
    marked_as_unread BOOLEAN DEFAULT FALSE,
    created_by VARCHAR(50),
    created_at BIGINT,
    ephemeral_expiration INTEGER
);

-- Group participants
CREATE TABLE chat_participants (
    chat_id VARCHAR(50) REFERENCES chats(id) ON DELETE CASCADE,
    contact_id VARCHAR(50),
    admin VARCHAR(20),  -- NULL, 'admin', 'superadmin'
    PRIMARY KEY (chat_id, contact_id)
);

-- Messages (stores IMessageIndex fields)
CREATE TABLE messages (
    id VARCHAR(50),
    cid VARCHAR(50) REFERENCES chats(id) ON DELETE CASCADE,
    mid VARCHAR(50),  -- parent message (reply)
    me BOOLEAN NOT NULL,
    type VARCHAR(20) NOT NULL,
    author VARCHAR(50) NOT NULL,
    status SMALLINT DEFAULT 1,
    starred BOOLEAN DEFAULT FALSE,
    forwarded BOOLEAN DEFAULT FALSE,
    created_at BIGINT NOT NULL,
    deleted_at BIGINT,
    mime VARCHAR(100),
    caption TEXT,
    edited BOOLEAN DEFAULT FALSE,
    PRIMARY KEY (cid, id)
);

-- Message content (separated for efficiency)
CREATE TABLE message_contents (
    cid VARCHAR(50),
    message_id VARCHAR(50),
    content BYTEA,
    raw JSONB,
    PRIMARY KEY (cid, message_id),
    FOREIGN KEY (cid, message_id) REFERENCES messages(cid, id) ON DELETE CASCADE
);

-- Reactions
CREATE TABLE message_reactions (
    cid VARCHAR(50),
    message_id VARCHAR(50),
    reactor_id VARCHAR(50),
    emoji VARCHAR(10),
    timestamp BIGINT,
    PRIMARY KEY (cid, message_id, reactor_id),
    FOREIGN KEY (cid, message_id) REFERENCES messages(cid, id) ON DELETE CASCADE
);

Recommended Indexes¶

-- Frequent searches
CREATE INDEX idx_messages_chat ON messages(cid);
CREATE INDEX idx_messages_created ON messages(cid, created_at DESC);
CREATE INDEX idx_messages_author ON messages(author);
CREATE INDEX idx_messages_starred ON messages(cid, starred) WHERE starred = TRUE;

-- Chat filters
CREATE INDEX idx_chats_archived ON chats(archived) WHERE archived = TRUE;
CREATE INDEX idx_chats_pinned ON chats(pinned) WHERE pinned IS NOT NULL;

Advantages¶

• Integrity: Foreign keys guarantee consistency
• Cascade Delete: ON DELETE CASCADE cleans automatically
• Efficient Filters: Indexes on search fields
• Joins: Relate data without multiple queries

Common Queries¶

-- Chat messages sorted
SELECT * FROM messages WHERE cid = ? ORDER BY created_at DESC LIMIT 50;

-- Starred messages from user
SELECT * FROM messages WHERE me = TRUE AND starred = TRUE;

-- Chats with unread messages
SELECT * FROM chats WHERE unread_count > 0 OR marked_as_unread = TRUE;

-- Delete chat (cascade deletes messages, reactions, etc.)
DELETE FROM chats WHERE id = ?;

Comparison¶

Recommendations by Use Case¶

Simple Bot / Prototype¶

• Backend: FileEngine (JSON files)
• Reason: Zero setup, easy debugging

Production Bot (< 100k messages)¶

• Backend: SQLite + FileEngine (content)
• Reason: Balance between performance and simplicity

Production Bot (> 100k messages)¶

• Backend: PostgreSQL + Redis (cache)
• Reason: Indexes, cascade delete, complex queries

Multi-tenant / SaaS¶

• Backend: PostgreSQL with partitioning by cid
• Reason: Data isolation, per-tenant cleanup

Orphan Data Prevention¶

Principle¶

When deleting a parent entity, ALWAYS delete its dependencies.

Deletion Cascade¶

Delete Contact:
+-- contact/{id}/index

Delete Chat (via set("chat/{cid}", null)):
|-- chat/{id}/index
|-- chat/{id}/messages
|-- chat/{id}/message/*/index
|-- chat/{id}/message/*/content
|-- chat/{id}/message/*/raw
+-- (SQL) chat_participants, messages, message_contents, message_reactions

Delete Message (via set("chat/{cid}/message/{mid}", null)):
|-- chat/{cid}/message/{id}/index
|-- chat/{cid}/message/{id}/content
+-- chat/{cid}/message/{id}/raw
    (SQL) message_contents, message_reactions

Implementation¶

Cascade delete is handled by the Engine's set(key, null) contract. The library calls:

// Delete chat and all its content
await wa.Chat.remove(cid);
// or
const chat = await wa.Chat.get(cid);
await chat.remove();

// Internally calls:
// await wa.engine.set("chat/{cid}", null);
// which cascade-deletes all sub-keys