Accounting

Accounting & Metrics Webhook Stream

Token-protected usage accounting and system metrics, exposed as a Server-Sent Events (SSE) stream, a WebSocket stream, and a JSON snapshot.

Endpoints

Authentication

HTTP endpoints require the header:

Authorization: Bearer <ACCOUNTING_TOKEN>

The WebSocket endpoint accepts the token either as a query parameter (?token=<ACCOUNTING_TOKEN>) or as the first Sec-WebSocket-Protocol value. If ACCOUNTING_TOKEN is empty, all accounting endpoints are disabled.

Example: snapshot

curl -H "Authorization: Bearer $ACCOUNTING_TOKEN" \
  https://chatagent.emwee.co/accounting/snapshot

Example: SSE stream

curl -N -H "Authorization: Bearer $ACCOUNTING_TOKEN" \
  https://chatagent.emwee.co/accounting/stream

Each SSE event is:

event: accounting
data: { ...snapshot json... }

Example: WebSocket stream

const ws = new WebSocket(
  `wss://chatagent.emwee.co/accounting/ws?token=${ACCOUNTING_TOKEN}`
);
ws.onmessage = (e) => {
  const snapshot = JSON.parse(e.data);
  console.log(snapshot.agents_online, snapshot.totals, snapshot.hardware);
};

Each WebSocket frame is a JSON object with the exact same schema as a snapshot (see below), pushed every ACCOUNTING_STREAM_INTERVAL seconds.

Snapshot Schema

Every event carries a single JSON object:

{
  "ts": 1785639022.2,
  "agents_online": 3,
  "totals": {
    "messages_received": 120,
    "messages_replied": 115,
    "words_replied": 45200,
    "message_units": 452.0,
    "images_sent": 18
  },
  "per_number": [
    {
      "whatsapp_number": "94707373703",
      "messages_received": 40,
      "messages_replied": 38,
      "words_replied": 15000,
      "message_units": 150.0,
      "images_sent": 6,
      "last_activity": 1785639022.2
    }
  ],
  "tokens": {
    "totals": {
      "input_tokens": 125000,
      "output_tokens": 48000,
      "cache_read_tokens": 30000,
      "cache_write_tokens": 1500,
      "total_tokens": 204500
    },
    "per_model": [
      {
        "provider": "google",
        "model": "gemini-3.8-flash",
        "input_tokens": 80000,
        "output_tokens": 30000,
        "cache_read_tokens": 30000,
        "cache_write_tokens": 1500,
        "total_tokens": 141500,
        "calls": 412
      }
    ],
    "per_number": [
      {
        "whatsapp_number": "94707373703",
        "input_tokens": 45000,
        "output_tokens": 20000,
        "cache_read_tokens": 12000,
        "cache_write_tokens": 600,
        "total_tokens": 77600
      }
    ]
  },
  "hardware": {
    "cpu_percent": 12.5,
    "cpu_count": 8,
    "memory_total_bytes": 17179869184,
    "memory_used_bytes": 6442450944,
    "memory_percent": 37.5,
    "disk_total_bytes": 214748364800,
    "disk_used_bytes": 85899345920,
    "disk_percent": 40.0,
    "uptime_seconds": 86400.5,
    "hostname": "webhook-1",
    "pid": 42
  }
}

Field reference

Billing convention

One reply message is billed as 1 unit per 100 words (rounded to 2 decimals). Images are counted separately in images_sent. Example: a reply of 250 words = 2.5 message units; sending 3 product images adds 3 to images_sent.

Storage

Counters persist in the SQLite database (CHATAGENT_DB_PATH) in the accounting table, keyed by whatsapp_number. The ConversationStore exposes:

• record_inbound(user_id) — increment received
• record_reply(user_id, words, images) — increment replied + words + images
• accounting_report() — raw per-number rows

LLM token usage is stored in a separate SQLite database (CHATAGENT_TOKENS_DB_PATH, default ./data/tokens.db) in the token_usage table via TokenUsageStore:

• record_usage(number, provider, model, *, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, total_tokens) — one row per LLM call
• report() — aggregated totals + per-model + per-number

Each LLM call inserts a row; report() sums cached/input/output/total tokens per model and per WhatsApp number.