Data Storage

Current Choice

  • whatsapp-adapter-api stores a local CSV group registry in whatsapp-adapter-api/data/groups.csv.
  • whatsapp-adapter-api may read a local CSV user registry in whatsapp-adapter-api/data/users.csv for optional local metadata overlays, but live API responses are derived from provider data.
  • whatsapp-adapter-api stores its bearer-token registry in whatsapp-adapter-api/data/api-tokens.csv.
  • whatsapp-adapter-api stores the latest known message reactions in whatsapp-adapter-api/data/message-reactions.csv.

Default Rule

  • CSV is the default for simple local data and operator-managed configuration.
  • PostgreSQL becomes the default once concurrency, relations, complex queries, or transactional guarantees matter.

Current Contents

groups.csv

  • stable internal group ID
  • WAHA group chat ID
  • last known group name
  • last known description
  • last sync timestamp

users.csv

  • optional stable internal user ID override
  • optional display name override
  • WhatsApp phone number used for matching
  • optional operator notes
  • optional last update timestamp

This file is not the primary public API source of truth for session identities or conversation participants.

api-tokens.csv

  • bearer token value
  • issued to
  • issue date

message-reactions.csv

  • adapter session ID
  • target message ID
  • reacting participant address
  • latest emoji for that participant on that message
  • last update timestamp

Migration Trigger

  • multiple concurrent writers
  • more than one runtime instance of whatsapp-adapter-api
  • richer configuration per group
  • richer relations between users, groups, and delivery preferences
  • audit trail requirements beyond append-safe flat files

Exceptions

  • No current storage exception is approved.