Skip to main content

UC-019 — Analyze Message History

FieldValue
IDUC-019
GoalQuery message history and export data for reports and audits
ChannelAll (SMS, RCS, WhatsApp)
ComplexityIntermediate
Estimated time15 minutes
APIs involvedGET /api/partner-gateway/v1/messages/history, POST /api/partner-gateway/v1/messages/history/export

Real-world scenarios​

  • Monthly report: The TravelDream marketing manager generates a monthly report with sending volumes by channel and delivery rate.
  • Per-channel analysis: The BrandCo team compares SMS vs WhatsApp performance to optimize the communication strategy.
  • Audit trail: The compliance officer retrieves the complete history of messages sent to a specific customer for a GDPR audit.

Analysis flow​

The diagram shows the interactive query flow and the asynchronous export for large datasets.

Prerequisites​

  • Active API Key with message read permissions
  • At least one message sent or received in the account
  • For large volume exports: allow time for asynchronous processing

Step 1 — Query message history​

Query the history with filters for channel, date and delivery status.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history?channel=SMS&from=2026-04-01&to=2026-04-09&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Message history​

{
  "messages": [
    {
      "messageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "channel": "SMS",
      "direction": "OUTBOUND",
      "destination": "+393471234567",
      "sender": "TechStore",
      "body": "Ciao Marco, il tuo ordine #ORD-20260409 e stato confermato!",
      "status": "DELIVERED",
      "sendDate": "2026-04-09T10:15:00+02:00",
      "deliveryDate": "2026-04-09T10:15:03+02:00",
      "cost": 0.035,
      "parts": 1
    },
    {
      "messageId": "a2c4e6f8-1234-5678-9abc-def012345678",
      "channel": "SMS",
      "direction": "OUTBOUND",
      "destination": "+393489876543",
      "sender": "TechStore",
      "body": "Giulia, la tua spedizione e in arrivo domani!",
      "status": "DELIVERED",
      "sendDate": "2026-04-08T16:00:00+02:00",
      "deliveryDate": "2026-04-08T16:00:05+02:00",
      "cost": 0.035,
      "parts": 1
    }
  ],
  "total": 156,
  "page": 1,
  "totalPages": 8,
  "hasMore": true
}

:::tip Available filters Combine the channel, from, to, status, destination and direction parameters to narrow results. Use direction=INBOUND to see only received messages. :::

Behind the scenes — Query and performance
  1. Indexing: The message history is indexed by channel, sendDate and destination to ensure fast queries even on millions of records.
  2. Pagination: Results are paginated with limit and page. The maximum is 100 messages per page.
  3. Time window: A query without from/to filter returns the last 30 days by default. The complete history is available for up to 24 months.
  4. Costs: The cost field shows the unit cost of the message in the account's currency.

Step 2 — Export data for reports​

For large datasets, start an asynchronous export in CSV or JSON format.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "channel": "SMS",
    "from": "2026-03-01",
    "to": "2026-03-31",
    "format": "csv",
    "includeFields": ["messageId", "destination", "status", "sendDate", "deliveryDate", "cost"]
  }'

Response — Export started​

{
  "exportId": "exp_x1y2z3w4",
  "status": "PROCESSING",
  "format": "csv",
  "estimatedRecords": 4520,
  "createdAt": "2026-04-09T16:00:00+02:00",
  "estimatedCompletionAt": "2026-04-09T16:02:00+02:00"
}

:::info Asynchronous export The export is processed in the background. Use the exportId to check the status and download the file when ready. :::

# Check export status
curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export/exp_x1y2z3w4" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Export completed​

{
  "exportId": "exp_x1y2z3w4",
  "status": "COMPLETED",
  "format": "csv",
  "totalRecords": 4520,
  "fileSize": 524288,
  "downloadUrl": "https://exports.qlara.com/exp_x1y2z3w4/messages-2026-03.csv",
  "expiresAt": "2026-04-16T16:00:00+02:00",
  "completedAt": "2026-04-09T16:01:30+02:00"
}
Behind the scenes — Export process
  1. Queue: The export request is placed in a dedicated processing queue to avoid impacting real-time API performance.
  2. Generation: The system iterates over the history applying the requested filters and generates the file in the chosen format (CSV or JSON).
  3. Storage: The file is saved in temporary storage with a signed URL, accessible without authentication for 7 days.
  4. Limits: A maximum of 3 concurrent exports are allowed. Expired exports are automatically removed.

Expected result​

StepActionResult
1GET /messages/historyPaginated message list with filters
2POST /messages/history/exportAsynchronous export started, exportId returned
3GET /messages/history/export/{id}File ready, downloadUrl available

Complete end-to-end example​

Scenario TravelDream: monthly SMS report for March.

# 1. Data preview (first 5 messages)
echo "=== March History Preview ==="
curl -s -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history?channel=SMS&from=2026-03-01&to=2026-03-31&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{total: .total, sample: [.messages[] | {destination, status, cost}]}'

# 2. Start full export
EXPORT_ID=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "channel": "SMS",
    "from": "2026-03-01",
    "to": "2026-03-31",
    "format": "csv"
  }' | jq -r '.exportId')

echo "Export started: $EXPORT_ID"

# 3. Wait and download
sleep 120
DOWNLOAD_URL=$(curl -s -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export/${EXPORT_ID}" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.downloadUrl')

echo "Download: $DOWNLOAD_URL"

Variants​

Filter by specific recipient (GDPR audit)​

Retrieve all messages sent to a specific number for compliance:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history?destination=%2B393471234567&from=2025-01-01&to=2026-04-09" \
  -H "X-Api-Key: YOUR_API_KEY"

Export in JSON format​

For programmatic integrations, export in JSON:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/history/export \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "from": "2026-03-01",
    "to": "2026-03-31",
    "format": "json"
  }'

Common errors​

400 Bad Request — Invalid time range​

{
  "status": "fail",
  "data": {
    "dateRange": "Date range cannot exceed 12 months"
  }
}

Solution: Reduce the time range to a maximum of 12 months. For longer periods, run multiple separate exports.

429 Too Many Requests — Export in progress​

{
  "status": "fail",
  "data": {
    "export": "Maximum concurrent exports (3) reached. Wait for current exports to complete."
  }
}

Solution: Wait for current exports to complete before starting new ones. Use GET /messages/history/export/{id} to check the status.

Next steps​

References​