JSON API for YateSMSC Control

From YateBTS
Jump to: navigation, search

Request: query_stats

Retrieve node statistics for the equipment.
It is mandatory to provide the desired node type.

Request

{ "request":"query_stats", "node":"smsc" }

Example response

{"code":0,
 "stats":{
   "engine":{
     "version":"5.5.1","revision":1830,"nodename":"blanked-as-ordered","plugins":21,"inuse":1,"handlers":190,"hooks":4,
     "messages":0,"maxqueue":10,"messagerate":40,"maxmsgrate":301,"enqueued":3326083,"dequeued":3326083,"dispatched":9613542,
     "supervised":true,"runattempt":3,"lastsignal":17,"threads":44,"workers":13,"mutexes":335,"semaphores":3,"acceptcalls":"accept","congestion":0
   },
   "uptime":{
     "wall":531208,
     "user":29450,
     "kernel":27682
   },
   "smsc_cli":{
     "stored":46889,
     "delivered":65459,
     "waiting":30,
     "failed":81815,
     "received":147304
   },
   "smsc_map":{
     "routers":8,
     "errors":67783,
     "recv_mo":118108,
     "sent_map":244937,
     "recv_mt":122198,
     "reports":4354,
     "alerts":626,
     "routing":6
   },
   "smsc_ati":{
     "sent":122198,
     "recv":122198,
     "errs":0,
     "fail":0
   },
   "smsc_gtt":{
     "local":955545,
     "stp":670173,
     "back":0,
     "fail":20,
     "stp_101":"up",
     "stp_102":"up"
   },
   "sig_routers":{
     "count":1,
     "operational":1
   },
   "sig_links":{
     "count":2,
     "operational":1
   },
   "sig_sccp":{
     "sent":172,
     "received":159,
     "translations":312,
     "errors":7
   }
 }
}


Request: query_messages

Retrieve waiting messages counters for a subscriber.

The subscriber should be identified by MSISDN since this is the primary identity for a SMSC. Identification by IMSI works only for own subscribers and not even always.

Request

{ "request":"query_messages",
  "params":{
    "msisdn":"NNNNNNN",
      // or
    "imsi":"NNNNNNNNNNNNNNN",
    "details": true/false     // optional, default false
  }
}

Response:

{ "code":0,
  "waiting":{
    "imsi":"NNNNNNNNNNNNNNN", // only if known and identified by MSISDN
    "msisdn":"NNNNNNN",       // only if subscriber was identified by IMSI
    "sending":{               // only present if there are MO-SMS from this subscriber
      "destinations":NN,      // distinct destinations waiting for delivery
      "messages":NNN          // total number of MO-SMS waiting in SMSC
      "list":[                // only if details were requested and there are messages
        {
          "id":NNN,                 // unique numeric message ID
          "ref":NNN,                // TP-MR reference if available
          "billid":"",              // billing ID
          "retries":N,              // number of retries left
          "destination":"NNNNNNN",  // MSISDN of destination
          "submit_info":"",         // protocol and address used to insert message in SMSC
          "last_error":"",          // text of last delivery attempt error
        },
        ...
      ]
    },
    "receiving":{             // only present if there are MT-SMS for this subscriber
      "originators":NN,       // distinct originators for waiting messages
      "messages":NNN,         // total number of MT-SMS waiting in SMSC
      "list":[                // only if details were requested and there are messages
        {
          "id":NNN,                 // unique numeric message ID
          "ref":NNN,                // TP-MR reference if available
          "billid":"",              // billing ID
          "retries":N,              // number of retries left
          "originator":"NNNNNNN",   // MSISDN or name of sender
          "submit_info":"",         // protocol and address used to insert message in SMSC
          "last_error":"",          // text of last delivery attempt error
        },
        ...
      ]
    }
  }
}

Request: query_subscriber_all

Retrieve from HLR information about a subscriber using all available methods.
For each interrogation type a separate object contains returned information.

CS and PS information is retrieved via AnyTimeInterrogation while SMS information uses SendRoutingInfoForSM.

The subscriber should be identified by MSISDN since this is the primary identity for a SMSC. Identification by IMSI works only if HLR is specified or configured.

Request

{ "request":"query_subscriber_all",
  "params":{
    "msisdn":"NNNNNNN",
      // or
    "imsi":"NNNNNNNNNNNNNNN",
    "hlr":""NNNNNNN"                // Optional GT of the HLR to query
  }
}

Response:

{ "code":0,
  "subscriber_info": {
    "cs": {
       "msisdn": "NNNNNNN",
       "imei": "NNNNNNNNNNNNNNN",   // May be 15 digit IMEI or 16 digit IMEISV
       "imsi": "NNNNNNNNNNNNNNN",
       "hlr": "NNNNNNN",
       "vlr": "NNNNNNN",
       "msc": "NNNNNNN",
       "cellid": "NNNNNXXXX",       // GSM or UMTS Location (5-6 digits PLMN + 4 xdigits LAC + optional 4 xdigits CellID or SAC)
       "loc_age": NNNN,             // For MSC information
       "eps_age": NNNN,             // EPS information may be present in case of LTE combined attach
       "eps_tai": "NNNNNXXXX",
       "eps_cell": "NNNNNXXXXXXX"
    },
    "ps": {
       "msisdn": "NNNNNNN",
       "imei": "NNNNNNNNNNNNNNN",   // May be 15 digit IMEI or 16 digit IMEISV
       "rat_type": "TYPE",          // One of: geran, utran, e-utran
       "imsi": "NNNNNNNNNNNNNNN",
       "hlr": "NNNNNNN",
       "sgsn": "NNNNNNN",
       "mme": "DIAMETER HOST",      // MME Name from MAP or Diameter OriginHost of MME
       "loc_age": NNNN,             // For SGSN information (GSM or UMTS)
       "eps_age": NNNN,             // For MME information (LTE)
       "eps_tai": "NNNNNXXXX",      // LTE Tracking Area Identity (5-6 digits PLMN + 4 xdigits TAC)
       "eps_cell": "NNNNNXXXXXXX"   // LTE Global Cell Id (5-6 digits PLMN + 7 xdigits CellID)
    },
    "sms": {
       "imsi": "NNNNNNNNNNNNNNN",
       "hlr": "NNNNNNN",
       "msc": "NNNNNNN",
       "sgsn": "NNNNNNN"
    }
  }
}

Any of the information above may be missing if not returned by HLR.


Request: query_subscriber_sms

Retrieve from HLR information about a subscriber using SendRoutingInfoForSM.

The subscriber should be identified by MSISDN since this is the primary identity for a SMSC. Identification by IMSI works only if HLR is specified or configured.

Request

{ "request":"query_subscriber_sms",
  "params":{
    "msisdn":"NNNNNNN",
      // or
    "imsi":"NNNNNNNNNNNNNNN",
    "hlr":""NNNNNNN"             // Optional GT of the HLR to query
  }
}

Response:

{ "code":0,
  "subscriber_info": {
    "imsi": "NNNNNNNNNNNNNNN",
    "hlr": "NNNNNNN",
    "msc": "NNNNNNN",
    "sgsn": "NNNNNNN"
  }
}

Any of the information above may be missing if not returned by HLR.


Request: query_subscriber_cs

Retrieve from HLR the CS information about a subscriber using AnyTimeInterrogation.

The subscriber should be identified by MSISDN. Identification by IMSI works only if HLR is specified or configured.

Request

{ "request":"query_subscriber_cs",
  "params":{
    "msisdn":"NNNNNNN",
      // or
    "imsi":"NNNNNNNNNNNNNNN",
    "hlr":""NNNNNNN"             // Optional GT of the HLR to query
  }
}

Response:

{ "code":0,
  "subscriber_info": {
    "msisdn": "NNNNNNN",
    "imei": "NNNNNNNNNNNNNNN",   // May be 15 digit IMEI or 16 digit IMEISV
    "imsi": "NNNNNNNNNNNNNNN",
    "hlr": "NNNNNNN",
    "vlr": "NNNNNNN",
    "msc": "NNNNNNN",
    "cellid": "NNNNNXXXX",       // GSM or UMTS Location (5-6 digits PLMN + 4 xdigits LAC + optional 4 xdigits CellID or SAC)
    "loc_age": NNNN,             // For MSC information
    "eps_age": NNNN,             // EPS information may be present in case of LTE combined attach
    "eps_tai": "NNNNNXXXX",
    "eps_cell": "NNNNNXXXXXXX"
  }
}

Any of the information above may be missing if not returned by HLR.


Request: query_subscriber_ps

Retrieve from HLR the PS or EPS information about a subscriber using AnyTimeInterrogation.

The subscriber should be identified by MSISDN. Identification by IMSI works only if HLR is specified or configured.

Request

{ "request":"query_subscriber_ps",
  "params":{
    "msisdn":"NNNNNNN",
      // or
    "imsi":"NNNNNNNNNNNNNNN",
    "hlr":""NNNNNNN"             // Optional GT of the HLR to query
  }
}

Response:

{ "code":0,
  "subscriber_info": {
    "msisdn": "NNNNNNN",
    "imei": "NNNNNNNNNNNNNNN",   // May be 15 digit IMEI or 16 digit IMEISV
    "rat_type": "TYPE",          // One of: geran, utran, e-utran
    "imsi": "NNNNNNNNNNNNNNN",
    "hlr": "NNNNNNN",
    "sgsn": "NNNNNNN",
    "mme": "DIAMETER HOST",      // Diameter OriginHost of MME
    "loc_age": NNNN,             // For SGSN information (GSM or UMTS)
    "eps_age": NNNN,
    "eps_tai": "NNNNNXXXX",      // LTE Tracking Area Identity (5-6 digits PLMN + 4 xdigits TAC)
    "eps_cell": "NNNNNXXXXXXX"   // LTE Global Cell Id (5-6 digits PLMN + 7 xdigits CellID)
  }
}

Any of the information above may be missing if not returned by HLR.


Request: schedule_sms

Request delivery of text message/partially encoded message/ custom PDU in MT format. If custom TPDU is sent, it must be formatted as a full MT SMS in hex format.
When sending a text message it will be encoded as gsm7bit (default charset/utf8) or ucs2.

You can deliver to single receiver or to multiple receivers (if array or msisdns is given instead of single msisdn).

Request params:

{
  "originator": "",              // Sender of the SMS. If "tpdu" is provided this is not used and remains for informational purpose. The sender should be encoded in the PDU already
  "destination": ["",""] or "",  // REQUIRED. Receiver(s) of the SMS. Must be a valid MSISDN or an Array of valid MSISDNs 

  "orignumtype": "international"/"national"/"alphanumeric",  // Optional. Defaults to "international"
  "orignumplan": "isdn"/"national"/"unknown" // Optional. Defaults to "isdn" if "orignumtype" is not "alphanumeric", or "unknown" if "orignumtype" is "alphanumeric"
  "destnumtype": "international"/"national", // Optional. The SMSC tries to guess the destination based of number and my_cc (country code) set in smsc. 

  "scheduled_time": NNNNNNNNNN,              // Optional. Deliver sms(s) starting from that UNIX timestamp, no more than 2678400 seconds (31 days) in the future
  "expires": NNNN,                           // Optional. Expire interval (maximum 38102400 seconds = 63 weeks) or absolute UNIX timestamp of expiration
  "retries": NN,                             // Optional. Number of delivery attempts to make, 1 to 30
  "return_billid": true/false,               // Optional. Return an Array of billids instead of the count of scheduled messages.
  "ref": NNN,                                // Optional. TP-MR message reference (0-255) to use for status reports, by default no reports are returned

  // Use one of this options:

  // text that the smsc should try to encode
  "text": "",

  // OR already encoded ud in hex format, specify de data coding scheme that should be sent
  "encoded_ud":"",
  "dcs": "",
  "udhi": true/false,  // Optional. User data Header Indicator, default false 

  // OR completely custom tpdu: String representation of a full MT SMS in hex format
  "tpdu": ""
}

Response:

{ "code":0, "scheduled_sms": N }                 // Count of message (fragments) by default
  or
{ "code":0, "scheduled_sms": ["id1","id2",...] } // Billing ID of each message if "return_billid" is true

Examples:

{"request":"schedule_sms", "node":"smsc", "params":{"originator":"40744334433","destination":"+88250001","text":"sms test enconding"}}
{"request":"schedule_sms", "node":"smsc", "params":{"originator":"monica","orignumtype":"alphanumeric","destination":"+88250001","text":"sms test enconding abc caller 3 "}}
{"request":"schedule_sms", "node":"smsc", "params":{"originator":"40744334444", "orignumtype":"international", "destination":"50001", "destnumtype":"national" ,"text":"sms test enconding"}}
{"request":"schedule_sms", "node":"smsc", "params":{"originator":"+40744334444", "destination":["88350001","40744334411"], "destnumtype":"international","text":"sms test enconding" }}
{"request":"schedule_sms", "node":"smsc", "params":{"originator":"407443344011", "orignumtype":"international", "destination":"88250001", "destnumtype":"international","encoded_ud":"F3F61C442FCFE9A0B27BFC7693D3EE33282C1E83C66136BB2C07CD40", "dcs":"gsm7bit"}}
{"request":"schedule_sms", "node":"smsc", "params":{"originator":"407443344011", "orignumtype":"international", "destination":"88250001", "destnumtype":"international","tpdu":"000ba17044334410f100006111304175838020f3f61c442fcfe9a0b27bfc7693d3ee33282c1e83c66136bb2c07cd40"}}

Please see the Send SMS Form sample for an example of how to use this request in a middleware application.

Request: hurry_sms

Request an immediate delivery attempt of a waiting SMS.
These attempts do count against the maximum number of retries!

Request

{ "request":"hurry_sms",
  "params":{
    "id":NNNN              // numeric ID of the message to hurry up
                           // or,
    "billid":""            // billing ID of the message to hurry up
  }
}

Response:

{ "code":0,
  "hurried_sms":NNNN       // ID of the message
}


Request: cancel_sms

Request cancellation of a waiting SMS.

Request

{ "request":"cancel_sms",
  "params":{
    "id":NNNN,             // numeric ID of the message to cancel
                           // or,
    "billid":""            // billing ID of the message to cancel
    "reason":"Whatever"    // optional reason to be written in CDR, default "Cancelled-by-Operator"
  }
}

Response:

{ "code":0,
  "canceled_sms":NNNN       // ID of the message
}