API Guide

Home     API Guide

Short Message Peer-to-Peer (SMPP) is an open standard in the telecommunications industry. For customers who wish to connect via our SMPP API, please contact our sales team to setup your account credentials. Currently our SMPP Gateway only supports SMPP version 3.4. For more information regarding SMPP, please refer to https://en.wikipedia.org/wiki/Short_Message_Peer-to-Peer

Host smpp.geniqtech.com
Port 2775
system_id [your_assigned_system_id]
password [your_assigned_password]
system_type Ignored

All SMPP accounts created will have the following defaults: -

Binds per system_id 2
Maximum Throughput 10 messages per second

To access our SMPP Gateway, all SMPP client IP address range must be whitelisted by GENIQ.


PDU Name command_id
bind_receiver 0x00000001
bind_receiver_resp 0x80000001
bind_transmitter 0x00000002
bind_transmitter_resp 0x80000002
bind_transceiver 0x00000009
bind_transceiver_resp 0x80000009
submit_sm 0x00000004
submit_sm_resp 0x80000004
deliver_sm 0x00000005
deliver_sm_resp 0x80000005
unbind 0x00000006
unbind_resp 0x80000006
enquire_link 0x00000015
enquire_link_resp 0x80000015
generic_nack 0x80000000
Value Encoding
0 GSM7
1 GSM7
2 8 Bit
8 UTF-16BE (UCS2)

You can send a concatenated SMS either by setting appropriate values in User Data Header (UDH) or Optional Parameter Tag (TLV).


Tag Value
sar_msg_ref_num 0x020C
sar_total_segments 0x020E
sar_segment_seqnum 0x020F

All error codes will be based on SMPP v3.4 (5.1.3 command_status) with the exception of the following extended error codes:-


Error Code Description
0x00000410 Account does not have sufficient credit balance
0x00000411 Prepaid Account has expired
0x00000414 Could not route message due to account limitations
0x00000415 Could not route message

GENIQ provides an RESTful API to send and receive SMS messages.

Each SMS message will be uniquely identified by a messageId and you can use this Id to check the delivery status of the message.

Username and password are submitted in every request using HTTP Basic Authentication Scheme.

For example, if the username is user1 and password is pass1 then the resulting Authorization header will be: -


Authorization: Basic dXNlcjE6cGFzczE=

API URL Endpoint:
https://api.geniqtech.com/rest/v1/sms


PARAMETER FORMAT REQUIRED DESCRIPTION DEFAULT
message string Yes Body of the SMS message
recipient integer Yes Recipient's mobile number including country code without "+" prefix
reference string optional A unique reference ID for keeping track of requests and responses
originator string Yes The originating address for the outgoing SMS message.
originatorTon string Optional The originating address's type of number (TON).

auto: Auto detect
national: Short number (Max. length=15)
alpha: Alphanumeric (Max. length=11)
international: MSISDN (Max. length: 15)
Auto
udh string Optional User Data Header for setting concatenated or binary SMS
dataCoding string Optional Data coding use for the SMS message.

auto: Auto detect
text: GSM 03.38 character set
unicode: Unicode character set
Auto
validity integer Optional Relative validity time in seconds. If message is not delivered within this value, it will be discarded.

Example request using CURL: -


$ curl -X POST https://api.geniqtech.com/rest/v1/sms \
-H 'Authorization: Basic dXNlcjE6cGFzczE=' \
-d "recipient=6591234567" \
-d "originator=Hello" \
-d "message=Test"



Parameters returned in the API response


PARAMETER FORMAT DESCRIPTION
reference string If reference parameter is submitted during SMS API request, the same value will be returned.
responseMessage string Response message returned from the API call
responseCode integer Response code returned from the API call. Refer to section "Response Codes" for list of possible values.
messageIds array A list of unique Ids for each SMS sent. If the SMS message length is too long, the API will automatically split it into multiple SMS parts and return the list of messageIds.

Example Response: -


{
"responseMessage":"Success",
"responseCode":"0",
"messageIds":["76CEEFFFD89C9193391D631A9EE74E27"]
}

Incoming SMS messages will be sent to a configured callback URL with the following parameters: -


PARAMETER FORMAT DESCRIPTION
messageId string A unique Id assigned to this message
recipient integer The recipient for this message
originator integer RThe sender for this message
udh string User Data Header. Will only be present if message is concatenated.
message string Body of the SMS message.
messageTimestamp string The creation date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)

Example Request using HTTP GET Method:-


http://your_domain.com/your_script
?messageId=43BC206B4610B25F41E7C3E050035473
&recipient=88888
&originator=6591234567
&message=hello
&messageTimestamp=2017-01-03T14:31:28+08:00



  You platform should respond with HTTP Status Code 200 (OK). Otherwise the same message will be delivered again.

SMS Delivery Reports will be sent to a configured callback URL with the following parameters: -

PARAMETER FORMAT DESCRIPTION
messageId string A unique Id assigned to this message
recipient integer The recipient's mobile number
status string The status of the message sent to the recipient.

Possible values:
pending
processed
delivered
expired
deleted
undeliverable
rejected
unknown
reasonCode integer If the message failed to deliver, this parameter will provide additional information on the failure.
messageTimestamp string The creation date and time of this report on GENIQ platform in RFC3339 format (Y-m-d\TH:i:sP)
operatorTimestamp string The creation date and time of this report on the SMSC in RFC3339 format (Y-m-d\TH:i:sP)

Example Request using HTTP GET Method: -


http://your_domain.com/your_script
?messageId=43BC206B4610B25F41E7C3E050035473
&recipient=6591234567
&status=delivered
&messageTimestamp=2017-01-03T14:31:28+08:00
&operatorTimestamp=2017-01-03T14:31:00+08:00



  You platform should respond with HTTP Status Code 200 (OK). Otherwise the same message will be delivered again.

API URL Endpoint:
https://api.geniqtech.com/rest/v1/balance


Example Request using CURL: -


$ curl https://api.geniqtech.com/rest/v1/balance \
-H 'Authorization: Basic dXNlcjE6cGFzczE='



Parameters returned in the API response: -

PARAMETER FORMAT DESCRIPTION
currency string Currency Code in ISO 4217 format.
type string Prepaid or Postpaid
responseCode integer Response Code returned from the API call. Refer to section "Response Codes" for the list of possible values.
responseMessage string Response Message for the API call.
balance decimal The amount of balance remaining.

Example Response: -


{
"currency":"EUR",
"type":"Prepaid",
"responseCode":"0",
"balance":19.2594,
"responseMessage":"Success"
}

responseCode Description
0 Success
1 Invalid Username or Password
2 Invalid IP request
3 Account has expired
4 Account is disabled
5 Account maximum throttling rate is exceeded
6 Account does not have sufficient credit balance
7 Prepaid Account has expired
10 Could not route message
11 Invalid recipient address
12 Invalid originating address
13 Invalid alphanumeric originating address
14 Could not route message due to account limitations
15 Subscriber has blocked this service
reasonCode Description
0 Not Applicable
1 Base Station Unknown
2 MSC Unknown
3 Format Error
4 Other Error
5 Subscriber Unknown
6 Subscriber Barred
7 Subscriber Not Provisioned
8 Subscriber Absent
9 SMSC Failure
10 SMSC Congestion
11 SMSC Roaming
12 Handset Error
13 Handset Memory Exceeded