Status Tracking 📡

The app allows you to track the status of messages using multiple methods.

Tracking Methods 🔍

App Interface Webhooks REST API CLI Tool

Sample Webhook Payload

{
  "event": "sms:failed",
  "payload": {
    "messageId": "zXDYfTmTVf3iMd16zzdBj",
    "sender": "+1234567890",
    "recipient": "+9876543210",
    "phoneNumber": "+9876543210",
    "simNumber": 1,
    "failedAt": "2024-02-20T15:30:00Z",
    "reason": "Invalid number"
  }
}

Webhook Setup Guide

Get Status via API

curl -X GET https://api.sms-gate.app/3rdparty/v1/messages/zXDYfTmTVf3iMd16zzdBj \
  -u "user:pass"

API Documentation

Check Status via CLI

smsgate --format=json status zXDYfTmTVf3iMd16zzdBj

{
  "id": "zXDYfTmTVf3iMd16zzdBj",
  "state": "Failed",
  "reason": "Invalid number"
}

Message Lifecycle 🔄

stateDiagram-v2
    direction LR
    [*] --> Pending
    Pending --> Cancelling
    Cancelling --> Cancelled
    Cancelling --> Sent
    Cancelling --> Failed
    Cancelled --> [*]
    Pending --> Processed
    Processed --> Sent
    Sent --> Delivered
    Delivered --> [*]
    Failed --> [*]
    Pending --> Failed
    Processed --> Failed
    Sent --> Failed
    Delivered --> Failed

Status Definitions 🚦

• Pending
  Message queued, awaiting device processing
• Cancelling
  Server requested cancellation, awaiting device confirmation
• Cancelled
  Message successfully cancelled before processing
• Processed
  Device prepared message, handed to Android SMS API
• Sent
  SMSC accepted message (Android API confirmation)
• Delivered
  Recipient device confirmed receipt (requires "withDeliveryReport": true)
• Failed
  Terminal error at any stage

Message Scenarios 📨

📨 Multipart Messages👥 Multiple Recipients

Condition	Result Status
All parts sent	Sent
Any part delivered	Delivered
Any part failed	Failed (terminal)

Condition	Result Status
Any pending	Pending
Any processed	Processed
All cancelled	Cancelled
All delivered	Delivered
All failed	Failed
Otherwise	Sent

Delivery Reports 📋

If the app receives an error code in the delivery report, the action depends on the type of the error:

• Permanent error: the status changes to Failed
• Temporary error without retries: the status changes to Failed
• Temporary error with retries: ignored, the status doesn't change