Developers

  1. Home
  2. Documenti
  3. Developers

Developers

Authentication

To authenticate with eNgY Solutions HTTP API you need to pass your API key.

Either as header or (not so secure) via URL query parameter.

Header name:X-ApiKey
Parameter name: ApiKey

Send SMS

Used to send an SMS to a specific destination.

Host:api.engy.solutions
Url:/outbound/sms
Methods:GET , POST
Formats:JSON , XML

Request parameters

Either as query parameters (when using GET) or in POST body document.

ParameterTypeMandatoryDescription
FromstringxThe sender ID to be used for the SMS. See Sender IDs for restrictions.
TostringxThe receiver MSISDN where the SMS should be sent to.
TextstringxThe content of the SMS. See Text and Encoding Restrictions for further information.
EncodingstringThe encoding of the SMS content (Allowed values: GSM7 , Binary , UCS2 ; default: GSM7 ). See Text and Encoding Restrictions for further information.
ReceiveDeliveryStatusbooltrue if you want to receive delivery status
information (default: false ; a callback url has to be defined in your account to receive
delivery status information).
RefIdstringAn optional reference id which will be included in corresponding delivery status
information callbacks.
UdhstringThe user data header in hex digits (e.g. 0605040C7242A3 ). Not required for long (concatenated) messages; texts are split automatically.
Flashbooltrue if you want to send the SMS as flash message; it will be displayed instantly on the display of the target device (default: false ).

Responsive parameters

Beside HTTP Status Codes each successful response will contain:

FieldTypeDescription
StatusCodeintThe status code for the call. See Status Codes.
MessageIdsstring[]An array containing the IDs of all messages which were generated. Willcontain > 1 IDs for long (concatenated) messages.

Phone Number

The length of the phone number depends on the country restrictions, usually it is between 8 and 16 digits. For best support, we suggest you put a+ in front of the phone number.

Short Code

The length of the short code is also depending on the country restrictions. Usually it is between 3 and 6 digits. Don’t put any + in front and only use digits!

Alpha Numeric

An alpha numeric sender ID can contain letters, spaces, digits and special characters, like ,_,&,,,|,+. The maximum length of an alpha numeric sender ID is 11 characters. Not every country and network support alpha numeric sender IDs and also not each special character is supported everywhere.

Default / GSM7 encoding

A default (GSM7) encoded message can have a length of max 160 characters. If you put more characters in, the message will be split up into several parts. This kind of message is called long messageor concatenated message. Each part can of a concatenated message can consist of 153 characters at max. This shorter amount is due to the fact, that the other 7 characters are “eaten up” by informational bytes which tell the end user device that its a concatenated message and further information, like total part count, current part count, etc…

UCS2 / Unicode encoding

A UCS2 or Unicode encoded message can have a length of max 70 unicode characters (fyi, each one is worth 2 bytes). If you put more characters in, the message will be split up into several parts. This kind of message is called long message or concatenated message. Each part can of a concatenated message can consist of 67 characters at max. This shorter amount is due to the fact, that the other 3 unicode characters are “eaten up” by informational bytes which tell the end user device that its a concatenated message and further information, like total part count, current part count, etc…

Binary encoding

A Binary encoded message can have a length of max 140 characters/bytes. For the Text parameter please only use ASCII-Characters (8-bit). See Binary SMS for a vCard example.

Binary messages can also contain more than 140 characters/bytes and are then, similar toGSM7 and UCS2 messages, split up into multiple parts. Each part can then contain at max 134 characters/bytes.

Cost Remarks

If a message will be split up into several parts (concatenated message) you will be charged for each part, as each part is a real SMS. If a message has been split up you can determine by examining the messageIds return parameter; it will contain more than 1 ID if the message had to be split.

HTTP Status Codes

CodeDescription
200OK – The HTTP request was successful
401Unauthorized – You either did not specify an API Key, the key is invalid or your originating IP was not whitelisted in your account
500Internal Server Error– We hope you never receive this; if you still will ever see this, it means that we have a temporary issue in our API and we are already working on a solution.

Delivery Status Codes

CodeTitleDescription
DECHEX
000000No errorNo error / success
001001Unassigned (unallocated) numberThis cause indicates that the destination requested by the Mobile Station cannot be reached because, although the number is in a valid format, it is not currently assigned (allocated).
01000ACall barredThis cause indicates that the outgoing call barred service applies to the short message service for the called destination.
017011Network failureThis cause is sent to the Mobile Station if the MSC cannot service a Mobile Station generated request because of PLMN failures, e.g. problems in MAP.
021015Short message transfer rejectedThis cause indicates that the equipment sending this cause does not wish to accept this short message, although it could have accepted the short message since the equipment sending this cause is neither busy nor incompatible.
022016CongestionThis cause is sent if the service request cannot be actioned because of congestion (e.g. no channel, facility busy/congested etc.).
023017Memory capacity exceededThis cause indicates that the mobile station cannot store the incoming short message due to lack of storage capacity.
02701BAbsent subscriberThis cause indicates that the destination indicated by the Mobile Station cannot be reached because the interface to the destination is not functioning correctly. The term “not functioning correctly” indicates that a signalling message was unable to be delivered to the remote user; e.g., a physical layer or data link layer failure at the remote user, user equipment off-line, etc.
02801CUnidentified subscriberThis cause indicates that the subscriber is not registered in the PLMN (i.e. IMSI not known).
02901DFacility rejectedThis cause indicates that the facility requested by the Mobile Station is not supported by the PLMN.
03001EUnknown subscriberThis cause indicates that the subscriber is not registered in the HLR (i.e. IMSI or directory number is not allocated to a subscriber).
038026Network out of orderThis cause indicates that the network is not functioning correctly and that the condition is likely to last a relatively long period of time; e.g., immediately reattempting the short message transfer is not likely to be successful.
041029Temporary failureThis cause indicates that the network is not functioning correctly and that the condition is not likely to last a long period of time; e.g., the Mobile Station may wish to try another short message transfer attempt almost immediately.
04202ACongestionThis cause indicates that the short message service cannot be serviced because of high traffic.
069045Requested facility not implementedThis cause indicates that the network is unable to provide the requested short message service.
2550FFUnspecified error causeThis cause indicates that there has been an unidentified or unspecified error provided from the next hop.
800320Insufficient fundsEither no prepaid credits anymore or post-pay credit limit reached.
801321Anti-Spam rejectionThis cause indicates that the message was rejected due to anti-spam protection regulations.
802322Empty messageThe message was blocked due to the reason that it had no content.
803323Anti-Loop rejectionThis cause indicates that the message was rejected due to anti-loop protection mechanism.
804324No route availableThis cause indicates that temporary no supporting route is available.
805325Multi-Sent rejectionThis cause indicates that the message was rejected due to the fact that it was sent several times in a very short time frame.
806326Invalid recipient formatThis cause indicates that the message was rejected due to an invalid recipient format; e.g. invalid length.
807327Invalid senderThis cause indicates that the message was rejected due an invalid sender; e.g. wrong alpha-numeric format or invalid characters.
808328Number lookup failedThis cause indicates that the message could not be routed because the number lookup (e.g. MNP or HLR/SRI) failed or returned an unknown error.
809329PrivacyThis cause indicates that the message was blocked due to privacy protection of the subscriber (e.g. when trying to send a silent message without permission)
81032ADestination not coveredThis cause indicates that the message was rejected because the destination network is not on the coverage list for the current account. The message will not be charged. We advise to re-check the latest coverage sheet provided by either your account manager or pricing team.
81132BInvalid message lengthThis cause indicates that the message was rejected because the content length exploits the allowed standards (e.g. concat or wap exploits).
81232CQueue fullThis cause indicates that the message was rejected because the queue towards the next hop seems to be full. We advise to either retry a few seconds later or to use a backup account / gateway. This error is also typical for SIM routes where the TPS is reached over a longer period.
81332DQueue on device fullThis cause indicates that the incoming message queue on the handset or modem is full. Usually we will retry several times to redeliver.
81432EBlocked recipientThis cause indicates that the message toward the recipient was blocked. This can have several reasons, e.g. blacklisted sender, blacklisted receiver, content filter, etc.
81532FRelay route usedThis indicates that a relay or backup route was taken, e.g. due to the fact that primary route was queuing or had similar capacity issues. Usually a backup or relay route is of equal or better quality as the primary route.
816330Validity ExpiredThis indicates that the validity period of the message was expired before the message could actually be delivered.
899383Temporary platform failureThis cause indicates that the message was rejected because we have temporary platform issue where the engineers will be working on immediately.

Delivery Status Callback Templates

In your account you can define a template of a URL to be called when new delivery status information area vailable.
To the URL several parameters can be passed. Put the corresponding parameter name in curly braces, e.g. {MessageId} .

ParameterTypeDescription
MessageIdstringThe ID of the corresponding message. It is the ID returned by the initial http request.
MessageStatestringThe state of the message. Possible values see Message States
ClientReferencestringThe optional custom reference you passed in the original http request in the RefId parameter.
TostringThe receiver of the delivery status information. Usually the from parameter value of the original request.
FromstringThe sender of the delivery status information. Usually the to parameter value of the original request.
SentDateTimeDateTimeThe date and time when the original message has been sent. In ISO-8859 format (e.g. 2018-03-10T17:23:15Z)
ReceivedDateTimeDateTimeThe date and time when the delivery status information was generated. In ISO-8859 format.
DeliveryStatusCodestringThe delivery status code which gives you also more information why a message is pending or could not be delivered.

Remark: The values of the several parameters will be correctly URL encoded.

Message States

CodeDescription
DELIVEREDThe message has been delivered to the end user device.
UNDELIVEREDThe message could not be delivered to the end user device.
WAITINGThe message is on it’s way to the end user device. Possible reason for this state can be that the device is temporarily turned off or the device is in an area with low
coverage.
REJECTEDThe message was rejected. Possible reason can be that some restrictions of the target country did not match.

Simple Text SMS

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 86
X-ApiKey: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "text": "Hi Bro, whats up?"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 83

{
    "statusCode": 0,
    "messageIds": ["4a57b5a9-59f8-48cc-a21e-3e29cef3d7c4"]
}

Long Text SMS

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 234
X-ApiKey: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "text": "Hi my best friend, what's up on your end?\nI wanna tell you the latest gossip, so get up and drop me a call! I promise, you won't trust your ears when you hear that!"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 145

{
    "statusCode": 0,
    "messageIds": [
        "f44afb66-04d4-4d24-962c-2ad63eba3c11",
        "14483b80-e521-4065-bfea-d55e63c37007"
    ]
}

Flash SMS

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 105
X-Api-Key: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "text": "Hi Bro, whats up?",
    "flash": true
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 83

{
    "statusCode": 0,
    "messageIds": ["8b3b9415-c33b-464c-ae57-427e312435a5"]
}

Unicode Text SMS

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 109
X-Api-Key: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "encoding": "UCS2",
    "text": "Привет мой друг!"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 83

{
    "statusCode": 0,
    "messageIds": ["68f3740d-46f9-44d2-bcf4-a696d318ec71"]
}

Binary SMS

In this example we send a vCard.

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 254
X-Api-Key: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "encoding": "Binary",
    "udh": "06050423F40000",
    "text": "BEGIN:VCARD\nVERSION:2.1\nN:Gump;Forrest\nFN:Forrest Gump\nORG:Bubba Gump Shrimps Ltd.\nTEL;type=WORK:+49 171 234 567 8\nEND:VCARD"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 83

{
    "statusCode": 0,
    "messageIds": ["68f3740d-46f9-44d2-bcf4-a696d318ec71"]
}

Request Delivery Status Information

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 121
X-Api-Key: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "receiveDeliveryStatus": true,
    "text": "Hi Bro, whats up?"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 83

{
    "statusCode": 0,
    "messageIds": ["3d00cd29-d9b6-4683-b424-12af6fd6da60"]
}

Callback

Given a callback template defined in your account, like this:

https://myapi.example.com/dlr?msgId={MessageId}&state={MessageState}&to={To}&from={From}&received={ReceivedDateTime}

The following GET URL will be called if new delivery states are available:

GET /dlr?msgId=3d00cd29-d9b6-4683-b424-12af6fd6da60&state=DELIVERED&to=Buddy%20Holly&from=4&received=2018-03-10T17%3A23%3A15Z
Host: myapi.example.com

Request Delivery Status Information with Client Reference

Request

POST /outbound/sms HTTP/1.1
Host: api.engy.solutions
Accept: application/json
Content-Type: application/json
Content-Length: 158
X-Api-Key: YOUR-API-KEY

{
    "from": "Buddy Holly",
    "to": 491712345678,
    "receiveDeliveryStatus": true,
    "refId": "My-Reference-Id-1234",
    "text": "Hi Bro, whats up?"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 83

{
    "statusCode": 0,
    "messageIds": ["854873a6-74ad-435a-ab1a-670e6207fd5b"]
}

Callback

Given a callback template defined in your account, like this:

https://myapi.example.com/dlr?msgId={MessageId}&state={MessageState}&to={To}&from={From}&received={ReceivedDateTime}&ref={ClientReference}

The following GET URL will be called if new delivery states are available:

GET /dlr?msgId=854873a6-74ad-435a-ab1a-670e6207fd5b&state=DELIVERED&to=Buddy%20Holly&from=4&received=2018-03-10T17%3A23%3A15Z&ref=My-Reference-Id-1234
Host: myapi.example.com

with Client Reference

Request Parameters

Either as query parameters (when using GET ) or in  POST  body document.

ParameterTypeMandatoryDescription
UserNamestringFor SMPP accounts the username, for HTTP accounts leave blank.
PasswordstringxFor SMPP accounts the password, for HTTP accounts the ApiKey.
WithDestinationNamesboolWhen true, the response body will contain the two additional fields country and network. Default: false

Response Body

Beside HTTP Status Codes each successful response will contain:

FieldTypeDescription
AccountNamestringThe descriptive name of the account.
CurrencystringThe currency for the account.
CurrentRatesRateSheetItem[]An array containing the current coverage items.
ScheduledRatesScheduledRateSheetItem[]An array containing upcoming rate/coverage changes.

RateSheetItem

FieldTypeDescription
CountrystringName of the country.
NetworkstringName of the network.
MCCstringMobile Country Code
MNCstringMobile Network Code
MCCMNCstringMobile Country Code and Mobile Network Code
RatedecimalThe current rate in the account currency.

ScheduledRateSheetItem

FieldTypeDescription
CountrystringName of the country.
NetworkstringName of the network.
MCCstringMobile Country Code
MNCstringMobile Network Code
MCCMNCstringMobile Country Code and Mobile Network Code
RatedecimalThe current rate in the account currency.
ValidFromdatetimeThe date and time from when on the change will be active. The format is ISO8601, e.g. “2018-08-23T14:00:00.0000000Z”
Hai trovato utile questo articolo? No

Come possiamo aiutarti?