Copy page

SMS

SMS Analytics Integration Guide

SMS Analytics Integration Guide

This guide explains how to consume SMS analytics from the Tech231 Platform API.

Overview

The SMS Analytics API provides time-series metrics for your messaging activity. All data is:

• Tenant-scoped: You only see your own data
• Aggregated: No individual message details, just counts and rates
• Time-partitioned: Organized by UTC date or period

Authentication

All analytics endpoints require Zitadel authentication:

Code
curl -X GET "https://api.tech231.com/api/v2/sms/analytics/timeseries/daily?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

GET /api/v2/sms/analytics/timeseries/daily

Get daily SMS analytics for your tenant.

Query Parameters:

Parameter	Type	Required	Description
startDate	DateOnly	Yes	Start of date range (inclusive)
endDate	DateOnly	Yes	End of date range (inclusive)
direction	string	No	Filter by direction: 'outbound' or 'inbound'

Example Request:

Code
GET /api/v2/sms/analytics/timeseries/daily?startDate=2024-01-01&endDate=2024-01-07

Example Response:

Code
{
  "tenantId": "org_abc123",
  "startDate": "2024-01-01",
  "endDate": "2024-01-07",
  "records": [
    {
      "date": "2024-01-01",
      "direction": "outbound",
      "attemptedCount": 1250,
      "processedCount": 1200,
      "deliveredCount": 1150,
      "failedCount": 50,
      "uniqueRecipientCount": 980,
      "avgSendToFinalStatusSeconds": 2.5,
      "deliveryRatePercent": 95.83,
      "failureRatePercent": 4.17
    },
    {
      "date": "2024-01-02",
      "direction": "outbound",
      "attemptedCount": 1300,
      "processedCount": 1280,
      "deliveredCount": 1240,
      "failedCount": 40,
      "uniqueRecipientCount": 1050,
      "avgSendToFinalStatusSeconds": 2.3,
      "deliveryRatePercent": 96.88,
      "failureRatePercent": 3.12
    }
  ]
}

GET /api/v2/sms/analytics/timeseries/period

Get aggregated SMS analytics for a period (week/month/quarter/year).

Query Parameters:

Parameter	Type	Required	Description
startDate	DateOnly	Yes	Start of date range (inclusive)
endDate	DateOnly	Yes	End of date range (inclusive)
granularity	string	Yes	Aggregation level: 'week', 'month', 'quarter', 'year'
direction	string	No	Filter by direction: 'outbound' or 'inbound'

Example Request:

Code
GET /api/v2/sms/analytics/timeseries/period?startDate=2024-01-01&endDate=2024-03-31&granularity=month

Example Response:

Code
{
  "tenantId": "org_abc123",
  "startDate": "2024-01-01",
  "endDate": "2024-03-31",
  "granularity": "month",
  "records": [
    {
      "periodStart": "2024-01-01",
      "periodEnd": "2024-01-31",
      "direction": "outbound",
      "attemptedCount": 38500,
      "processedCount": 37200,
      "deliveredCount": 35800,
      "failedCount": 1400,
      "uniqueRecipientCount": 12500,
      "avgSendToFinalStatusSeconds": 2.4,
      "deliveryRatePercent": 96.24,
      "failureRatePercent": 3.76
    },
    {
      "periodStart": "2024-02-01",
      "periodEnd": "2024-02-29",
      "direction": "outbound",
      "attemptedCount": 42000,
      "processedCount": 41500,
      "deliveredCount": 40200,
      "failedCount": 1300,
      "uniqueRecipientCount": 14200,
      "avgSendToFinalStatusSeconds": 2.2,
      "deliveryRatePercent": 96.87,
      "failureRatePercent": 3.13
    }
  ]
}

Metrics Explained

Metric	Description
attemptedCount	Total SMS messages submitted for sending
processedCount	Messages that reached the SMSC (gateway)
deliveredCount	Messages confirmed delivered to recipients
failedCount	Messages that failed to deliver
uniqueRecipientCount	Distinct phone numbers messaged
avgSendToFinalStatusSeconds	Average time from send to final status
deliveryRatePercent	(delivered / processed) × 100
failureRatePercent	(failed / processed) × 100

Date Range Limits

• Maximum date range: 90 days for daily, 365 days for period
• All dates are in UTC
• Start date must be before or equal to end date

Rate Limiting

Analytics endpoints are subject to rate limiting:

• 100 requests per minute per tenant
• Rate limit headers included in response

Migration from Legacy Analytics

If you were using the legacy /api/v2/analytics/* endpoints (Orleans grain-based), migrate to the new TimescaleDB endpoints:

Legacy Endpoint	New Endpoint
/api/v2/analytics/daily	/api/v2/sms/analytics/timeseries/daily
/api/v2/analytics/weekly	/api/v2/sms/analytics/timeseries/period?granularity=week
/api/v2/analytics/monthly	/api/v2/sms/analytics/timeseries/period?granularity=month

The new endpoints provide:

• Better performance: TimescaleDB hypertables and continuous aggregates
• Longer retention: 12 months of daily data
• More granularities: Quarterly and yearly aggregates
• Lower latency: Optimized indexing and compression

Error Codes

Status	Error	Description
400	Invalid date range	startDate > endDate or range exceeds limit
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Tenant does not have analytics access
429	Too Many Requests	Rate limit exceeded

Code Examples

C# / .NET

Code
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync(
    "https://api.tech231.com/api/v2/sms/analytics/timeseries/daily" +
    "?startDate=2024-01-01&endDate=2024-01-31");

var analytics = await response.Content.ReadFromJsonAsync<DailySmsAnalyticsResponse>();
foreach (var record in analytics.Records)
{
    Console.WriteLine($"{record.Date}: {record.DeliveredCount} delivered, " +
        $"{record.DeliveryRatePercent:F2}% delivery rate");
}

Python

Code
import requests

headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(
    "https://api.tech231.com/api/v2/sms/analytics/timeseries/daily",
    params={"startDate": "2024-01-01", "endDate": "2024-01-31"},
    headers=headers
)

analytics = response.json()
for record in analytics["records"]:
    print(f"{record['date']}: {record['deliveredCount']} delivered, "
          f"{record['deliveryRatePercent']:.2f}% delivery rate")

JavaScript / Node.js

Code
const response = await fetch(
  'https://api.tech231.com/api/v2/sms/analytics/timeseries/daily' +
  '?startDate=2024-01-01&endDate=2024-01-31',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

const analytics = await response.json();
for (const record of analytics.records) {
  console.log(`${record.date}: ${record.deliveredCount} delivered, ` +
    `${record.deliveryRatePercent.toFixed(2)}% delivery rate`);
}

See Also

• SMS Analytics Architecture
• SMS Sending Flows
• Billing Integration