The Home Location Register (HLR) is the main database of permanent subscriber information for a mobile network. The HLR is an integral component of CDMA (code division multiple access), TDMA (time division multiple access), and GSM (Global System for Mobile communications) networks.
System Requests can be made by following two methods:
SMPP
HTTP
The Short Message Peer-to-Peer (SMPP) is a protocol used by the telecommunications industry for exchanging SMS messages between Short Message Service Centers (SMSC) and External Short Messaging Entities (ESME). The protocol is a level-7 TCP/IP protocol, which allows fast delivery of SMS messages. The connection between application and AMS SMPP Server is SMPP version 3.4 Using SMPP Account, It is possible to Request for Number Lookup. In order to Use SMPP Lookup Service, User must have valid systemid & password to Set in Bind PDU.
The purpose of the SMPP bind operation is to register an instance of an ESME with the SMSC system and request an SMPP session over this network connection for the submission or delivery of messages. Thus, the Bind operation may be viewed as a form of SMSC login request to authenticate the ESME entity wishing to establish a connection.
Requested Parameters:
System_id = Provided System Id
Password = Provided Password
System_type = HLRUser may bind as either Tx (Transmitter), Rx (Receiver) or TRx (Transceiver).
Tx: User bound as a Transmitter is authorized to send short messages and to receive the corresponding SMPP responses.
Rx:User bound as a Receiver is authorized to receive short messages and to return the corresponding SMPP message responses.
TRx: User bound as a Transceiver is allowed to send & receive messages over a single SMPP session.
Users are allowed to bound as only 1 TRx/Rx with multiple Tx Session.
SubmitSM PDU is used for submitting the number context Request, having destAddress parameter set to the required destination address. All other parameters (srcAddress, esm, ton/npi) will be ignored.
submitSMResp PDU will be used as Response containing responseid (Unique Number to Identify Request) on Successful Submission or Submit_Error in case of any Error. The command_status field of an SMPP message response indicates the success or failure of an SMPP request.
SMPP Error Codes and their associated values are defined in the following table:
| Code | Name | Description |
|---|---|---|
| 0x00000000 | ESME_ROK | No Error |
| 0x00000003 | ESME_RINVCMDID | Invalid Command ID |
| 0x00000008 | ESME_RSYSERR | System Error |
| 0x00000010 | ESME_RINSBAL | Insufficient Balance |
| 0x0000000B | ESME_RINVDSTADR | Invalid Destination Address |
| 0x0000000D | ESME_RBINDFAIL | Bind Failed |
| 0x0000000E | ESME_RINVPASWD | Invalid Password |
| 0x0000000F | ESME_RINVSYSID | Invalid System ID |
| 0x00000012 | ESME_RCOVERR | No Coverage For Requested Destination |
| 0x00000016 | ESME_RACCEXPIRY | Account Expired |
Once the Lookup request is being finalized on our System, deliverSM PDU is sent as a lookup Result containing the Status & other required information included in the short_message field of the deliverSM for the requested destination number.
Example:
(deliver: (pdu: 224 5 0 5001) (addr: 0 0 HLR) (addr: 0 0 919589xxxxxx) (sm: msg: id:6002 sub:001 dlvrd:001 submit date:1507140141 done date:1507140142 stat:DELIVRD err:000 cc:91 nnc:40493 isPorted:false p_nnc: isRoaming:false r_cc: r_nnc: text:dlr ) (opt: (str: (tlv: 30) 6002) ) )
If Number is INVALID/ABSENT_SUBSCRIBER etc, The DeliverSm will be as follow:
(deliver: (pdu: 224 5 0 5000) (addr: 0 0 HLR) (addr: 0 0 919589xxxxxx) (sm: msg: id:6000 sub:001 dlvrd:001 submit date:1507141154 done date:1507141225 stat:UNDELIV err:011 cc:91 nnc:40493 isPorted:false p_nnc: isRoaming:false r_cc: r_nnc: text:dlr ) (opt: (str: (tlv: 30) 6000) ) )
Here err: 011 is the status code of the Lookup. See the status code table for description.
Users can Use Following Services via HTTP API:
1) Number Lookup
2) Status Enquiry
Number Lookup HTTP API supports both GET and POST Methods. Using HTTP Method limit of upto 100 numbers is allowed in a single request.
Description:
URL For Lookup Request:
http://ip:port/websmpp/hlr/lookup?username=xxxx&password=xxxx &destination=919589xxxxxx
Requested Parameters:
username = Provided System Id
Password = Provided Password
Destination = Destination Number or Comma separated Destination Numbers
Response Format
On Successful Lookup:
BatchId: 140715134158696
On Failed:
ERROR - HTTP01 --> Invalid HTTP URL Format
After Successful Lookup, User can get Result via Following URL:
http://ip:port/websmpp/hlr/report?batchid=140715134158696
Result Format will be JSON (JavaScript Object Notation):
{"cc":"91","nnc":"40493","isRoaming":"No","isPorted":"No","destination":"919 589xxxxxx","error_code":"000","id":6002,"time":"2015-07-14 13:41:59","batchid":"140715134158696","status":"DELIVRD"}
Parameter Description:
Id : Unique Id to Identify this request
batchid: Batch id provided at request time
destination: Requested Destination Number
time: lookup request time
status: status of the number
error_code: error code if lookup failed/number error
error: error description if lookup failed/number error
cc: Country code of destination number
nnc: Network code
isPorted: Yes/No
p_nnc: ported network code if ported
isRoaming: Yes/No
r_cc: Roaming Country code if roaming
r_nnc: Roaming Network code if roaming
This section Describes Errors Returned as Response On Submission (if Failed):
| Code | Name | Description |
|---|---|---|
| 001 | INVALID_LOGIN | Either Systemid or password is incorrect |
| 002 | INVALID_REQUEST | Required parameters are missing or Invalid parameters or invalid values of parameters |
| 003 | ACCOUNT_EXPIRED | The Account has been Expired |
| 004 | INSUF_BALANCE | Insufficient Balance to fulfill the Request |
| 005 | INVALID_DEST_ADDR | Invalid Destination Address |
| 006 | NO_COVERAGE | No Coverage for Requested Destination |
| 007 | SYSTEM_ERROR | System Error Occurred |
This section describes Status of the Lookup Result returned by the system.
| Code | Name | Description |
|---|---|---|
| 011 | ABSENT_SUBSCRIBER | The Subscriber is absent |
| 012 | UNKNOWN_SUBSCRIBER | The subscriber is unknown |
| 013 | UNIDENTIFIED_SUBSCRIBER | The Subscriber is unindentified |
| 014 | TIMEOUT | Timeout occurred |
| 015 | PROVIDER_GENERAL_ERROR | General Error From Provider |
| 016 | NO_RESPONSE | No Status From Provider |
| 017 | SYSTEM_FAILURE | A system failure occurred. |
| 018 | INVALID_MSISDN | Invalid msisdn |
| 019 | CALL_BARRED | Call Barred |
| 020 | ILLEGAL_SUBSCRIBER | Illegal Subscriber |
| 021 | TELESERVICE_NOT_PROVISIONED | Teleservice not provisioned |
| 022 | FACILITY_NOT_SUPPORTED | No facility |
| 023 | SUBSCRIBER_BUSY_FOR_MT_SMS | Subscriber Busy |
| 024 | UNEXPECTED_DATA_VALUE | Unexpected data |