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"
  }
}

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
    },
    "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
    }
  }
}


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).

Format:
{
  "originator": "",       // Sender of the SMS. This is not used in any way, just 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 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": "",  // unix timestamp. Optional. Deliver sms(s) starting from that time

  // 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 send
  "encoded_ud":"",
  "dcs": "",
  "udhi": true/false,  // Optional. Default false 

  // OR completely custom tpdu: String representation of a full MT SMS in hex format
  "tpdu": ""
}
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.