Get Your App's Own Usage Stats

Set up your AI chatbot to fetch and send its own activity reports -- daily, weekly, or on demand. No coding required.

Your chatbot can send you (or any team member) regular usage reports — “You had 47 conversations this week, 12 unique people, 318 messages” — without you ever logging into the dashboard. This guide walks through setting it up by chatting with the Alchemist. No code, no copy-paste of API keys into config files.

What you’ll build

By the end, your app will have a new tool called fetch_my_app_usage (you can name it anything). You can use it three ways:

In chat: ask your bot “how many conversations did we have this week?” and it’ll answer with live numbers.
In the Heartbeat: schedule the bot to email you a weekly summary automatically.
From any channel: WhatsApp, Slack, email — anywhere your bot runs.

ℹ️

This setup uses Custom Actions and (for the optional weekly summary) Heartbeat, both of which require a Builder plan or higher. The Builder API itself has no tier gate, but the custom HTTP action that calls it does.

Upgrade to Builder →

Before you start

You’ll need:

A Chipp app you’ve already created on a Builder plan or higher
Access to the Alchemist panel (the AI assistant on the right side of the builder)
About 5 minutes

Step 1 — Ask the Alchemist to set everything up

1

Open your app and open the Alchemist

Go to build.chipp.ai, open the app you want to monitor, and click the Alchemist panel on the right (the AI assistant).

2

Paste this prompt into the Alchemist

plaintext

Set up a tool so this app can fetch its own usage stats.
Use the Builder API at /api/v1/apps/{appId}/analytics/usage.
Create the Builder API key, save it as a secret variable
called BUILDER_API_KEY, and wire it into a custom HTTP action
called fetch_my_app_usage.

The Alchemist will respond in three stages:

Create the API key. The Alchemist mints a Builder API key for this app and shows you the raw value once — it starts with chipp_. Save it somewhere safe (your password manager, a sticky note, anywhere offline). You won’t see the raw key again. If you lose it, ask the Alchemist to revoke the old key and create a new one — your data isn’t lost, only the key.
Open a secure form. The Alchemist will pop up a form titled “Builder API Key” (or similar) with a single field. Paste the raw key into the form and click Save. The value is encrypted on our servers; nobody, including Chipp staff, can read it back.
Build the custom action. The Alchemist creates a new HTTP action called fetch_my_app_usage. You’ll see it appear under Build → Actions in your app (scroll past the integrations to the Custom Actions card). The action’s Authorization header is wired to Bearer {{var.BUILDER_API_KEY}}, so the encrypted key is substituted in only when the action runs — it never appears in chat history or logs.

3

Verify it worked

Still in the Alchemist chat, type:

plaintext

Test the fetch_my_app_usage action and show me the result.

You should see a JSON response with a summary object containing total_sessions, unique_consumers, and total_messages, plus a timeseries array. If you instead see a 401 Unauthorized error, the key was pasted wrong — ask the Alchemist “Re-collect the BUILDER_API_KEY value” and repeat stage 2.

Step 2 — Test it in the deployed chat

Open your app’s public chat (Publish → Share → open your chat URL) and try:

“How many conversations have we had this week?”
“Give me a usage summary for the last 30 days.”
“Compare this week to last week.”

Your bot will call fetch_my_app_usage behind the scenes and answer with live numbers from the database. The numbers are the same ones you’d see on the Insights → Overview page in the builder.

⚠️

Live conversation counts include sessions still in progress. If you want strict “completed conversations only”, phrase your question like “how many ended conversations did we have this week” — the bot will pick the right filter from the response.

Step 3 — Wire it into the Heartbeat (optional)

The Heartbeat is a separate feature that lets your bot proactively message you (or your customers) on a schedule. Because the Heartbeat agent loop shares the same tools as regular chat, your new fetch_my_app_usage action is automatically available to it — no extra wiring.

1

Open Heartbeat settings

From your app, navigate to Publish → Heartbeat.

2

Enable Heartbeat and pick a schedule

Toggle on Enable heartbeat. Choose:

Schedule: Weekly, Monday at 9:00 AM (or daily, or every-N-hours)
Channel: Email (so the report lands in your inbox)
Recipients: add your own email under Additional recipients or Curated list

3

Write the heartbeat instructions

In the Instructions field, paste something like:

plaintext

Every Monday morning, call fetch_my_app_usage to get the past
week's stats and email me a short summary. Format it like:

"Here's your weekly report for {date range}:
- {N} conversations
- {N} unique people
- {N} total messages"

If conversations are up 20%+ from the previous week, mention the
growth. If they're down 20%+, flag it as a heads-up. Always send
the report on Mondays, even if nothing changed.

The last sentence matters: by default Heartbeat suppresses messages when the AI decides there’s nothing worth saying. Telling it to always send the report overrides that for reporting use cases.

4

Send a test

Scroll to the Test Heartbeat card at the bottom, pick your own account in the consumer picker, and click Send Test. You should get an email within ~30 seconds. From then on, the heartbeat runs on the schedule you picked.

What stats are available?

Two endpoints today, both read-only:

Endpoint	Returns
`/api/v1/apps/{appId}/analytics/usage`	Total sessions, unique consumers, total messages, plus a day/week/month timeseries
`/api/v1/apps/{appId}/analytics/token-usage`	Total tokens consumed (input/output), per-model breakdown — useful for cost monitoring

See the full Analytics endpoint reference for query parameters and response fields.

If you want per-model token costs in your weekly email, repeat Step 1 with a second prompt:

plaintext

Create a second custom action called fetch_my_token_usage that calls
/api/v1/apps/{appId}/analytics/token-usage with the same
BUILDER_API_KEY variable I already saved.

The Alchemist will reuse the secret variable you already saved — no new key needed.

How the security works (short version)

The Builder API key starts with chipp_ and is scoped to a single app. It can’t read another app’s data.
The raw key is shown to you exactly once at creation. We store only a SHA-256 hash. You can’t recover the raw key from us — only revoke and replace it.
When you saved the key into the secure form, it was encrypted with the platform’s per-app encryption key. The custom action references it via {{var.BUILDER_API_KEY}}, which the platform substitutes server-side at runtime. The raw value never appears in chat history, the Alchemist’s tool arguments, or any log file.
To revoke a key (for rotation or after a leak), ask the Alchemist “Revoke the Builder API key called ‘Weekly stats reader’” (or whatever you named it). Old custom actions will start returning 401 Unauthorized. Mint a new key and update the secret variable to replace it.

See the Variables and Secrets reference for more on how secret variables are stored.

Troubleshooting

Symptom	Cause	Fix
Alchemist says “I created the variable but the value is empty”	You closed the secure form without pasting the key	Ask the Alchemist “Re-collect the BUILDER_API_KEY value” and paste the raw key
Bot says “I couldn’t fetch usage” or shows a 401	Key was pasted wrong, or the key was revoked	Mint a new key with “Create a new Builder API key and update BUILDER_API_KEY”
Bot says “I don’t know how to do that”	The custom action wasn’t actually created	Check Build → Actions — if `fetch_my_app_usage` isn’t listed in the Custom Actions card, repeat Step 1
Heartbeat email never arrives	The AI decided nothing needed reporting	Add “Always send the report, even when there’s no change” to your heartbeat instructions
You want to share this report with a team member	They don’t need the API key — the bot itself does the fetching	Just add their email to the heartbeat’s recipient list

What’s next

Schedule per-customer digests, not just self-reports: in your heartbeat instructions, ask the bot to compose personalized summaries for each consumer. The bot still has access to fetch_my_app_usage for org-wide context.
Pull stats into Google Sheets: build a second app on Chipp that calls the Builder API on a schedule and writes results to a sheet via the Google Sheets hosted integration.
Cross-app dashboards: Builder API keys are scoped per-app. To monitor several apps from one place, mint a key per app, save each as a separate secret variable in your dashboard app (e.g. STATS_KEY_APP_A, STATS_KEY_APP_B), and create one custom action per app.