Difference between revisions of "JSON API for YateSMSC Control"

From YateBTS
Jump to: navigation, search
(Request: schedule_sms)
Line 295: Line 295:
 
   
 
   
 
   "scheduled_time": "",  // unix timestamp. Optional. Deliver sms(s) starting from that time
 
   "scheduled_time": "",  // unix timestamp. Optional. Deliver sms(s) starting from that time
 +
 +
  "ref":NNN,            // Optional. Message reference (0-255) to use for status reports, by default no reports are returned
 
   
 
   
 
   // Use one of this options:
 
   // Use one of this options:
Line 304: Line 306:
 
   "encoded_ud":"",
 
   "encoded_ud":"",
 
   "dcs": "",
 
   "dcs": "",
   "udhi": true/false,  // Optional. Default false  
+
   "udhi": true/false,  // Optional. User data Header Indicator, default false  
 
   
 
   
 
   // OR completely custom tpdu: String representation of a full MT SMS in hex format
 
   // OR completely custom tpdu: String representation of a full MT SMS in hex format
Line 319: Line 321:
  
 
Please see the [[Send SMS Form sample]] for an example of how to use this request in a middleware application.
 
Please see the [[Send SMS Form sample]] for an example of how to use this request in a middleware application.
 
  
 
== Request: '''hurry_sms''' ==
 
== Request: '''hurry_sms''' ==

Revision as of 16:59, 16 July 2018

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
          "billid":"",              // billing ID
          "retries":N,              // number of retries left
          "destination":"NNNNNNN",  // MSISDN of destination
          "submit_info":"",         // protocol 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
          "billid":"",              // billing ID
          "retries":N,              // number of retries left
          "originator":"NNNNNNN",   // MSISDN or name of sender
          "submit_info":"",         // protocol 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).

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

  "ref":NNN,             // Optional. 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 send
  "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": ""
}
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
  }
}

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
    "reason":"Whatever"    // optional reason to be written in CDR, default "Cancelled-by-Operator"
  }
}

Response:

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