Skip to main content
Understanding how your bot is performing is essential for improving conversation quality and demonstrating ROI. Botsify exposes a dashboard statistics endpoint that lets you pull message counts and user engagement metrics for any custom date range — making it easy to build reports, set up monitoring dashboards, or feed data into your analytics stack.

​
The analytics endpoint

POST /api/v1/bot-dashboard-stats returns aggregated performance data for the bots associated with your API key. You control the reporting window by passing a date_from and date_to value in YYYY-MM-DD format.
Request body fields

​
Understanding the parameters

date_from — The first day of your reporting period. All statistics are aggregated from the beginning of this calendar day (midnight UTC). date_to — The last day of your reporting period. Statistics are aggregated through the end of this calendar day (23:59:59 UTC). Set date_to to today’s date to include the most recent activity. Both dates are inclusive, so a request with date_from: "2025-01-01" and date_to: "2025-01-01" returns data for exactly one day.

​
Sample response shape

The endpoint returns a JSON object containing aggregated statistics for the specified date range. The response includes metrics such as:
The stats object describes activity across all bots tied to your API key for the given window:
  • total_messages — combined inbound and outbound message volume
  • messages_sent — messages delivered from the bot to users
  • messages_received — messages sent by users to the bot
  • total_users — unique users who interacted during the period
  • new_users — users engaging for the first time
  • returning_users — users with prior interaction history
  • engaged_sessions — conversation sessions that progressed beyond the opening message
  • avg_messages_per_session — average depth of a conversation
The exact fields returned may vary based on your Botsify plan and the channels connected to your bots. Always inspect the live response to confirm which metrics are available for your account.

​
Building a rolling 30-day report

To track performance on a continuous basis, compute date_from dynamically as today’s date minus 30 days and date_to as today’s date. Schedule this call daily (e.g. via a cron job) and store each response in your data warehouse to build a time-series view of your bot’s growth. Here is a quick shell snippet to generate the correct date strings:

​
Next steps

  • Correlate with deployments — cross-reference stat drops or spikes with the version history from Deploy an Agent to identify the impact of configuration changes.
  • Combine with WhatsApp data — supplement bot-level stats with broadcast-specific metrics from the WhatsApp Integration guide.
  • Set up alerts — if new_users drops sharply day-over-day, that may signal a channel connectivity issue worth investigating in your Botsify dashboard.