Send SMS

Description
Using that type of API gives you the flexibility to send to a single or multiple destinations SMS by calling the web-service once. Also you are dealing with a JSON object (as a payload), which is much more straight-forward to a programer.
Note
you can send a different text to each destination as you may have noticed below
Endpoint URL
https://sms.liveall.eu/apiext/Sendout/SendJSMS
curl example
curl --location --request POST 'https://sms.liveall.eu/apiext/Sendout/SendJSMS' \
--header 'Content-Type: application/json' \
--data-raw ' {
"apitoken": "7ace3e49cae13ae4f5ccb8a6a8a0d6a8fe120aa82ae46ad6ee4c9d8",
"senderid": "mySender",
"messages": [
{
"destination": "306912345678",
"message": "Test message A"
},
{
"destination": "306912345677",
"message": "Test message B"
}
]
}
'
JSON object example
{
"apitoken": "7ace3e49cae13ae4f5ccb8a6a8a0d6a8fe120aa82ae46ad6ee4c9d8",
"senderid": "mySender",
"messages": [
{
"destination": "306912345678",
"message": "Test message A"
},
{
"destination": "306912345677",
"message": "Test message B"
}
]
}
JSON Object variables
- apitoken
string
a unique hash code for each account that authorizes each web request. That code you can find it on your account’s page- senderid
string
the sender name of the SMS. There is a limit to 11 characters (latin characters). Allowed characters are:[A-Za-z0-9\-\.\!\#\%\&\(\)\<\>]
- messages
object
is an array of objects that holds the data of the message, as shown in the above example. Object consists of 2 properties: destination (the cell’s number (without leading zeros or + sign), for example for Greece: 306912345678), and message (the message’s text)- sendon
(optional) - unsigned integer
an optional scheduling parameter. You can define a future datetime a message to be sent. This variable is a type of unsigned integer - unix timestamp. You can find more reference on https://dev.mysql.com/doc/refman/5.5/en/date-and-time-functions.html#function_unix-timestamp That is, in case you want to send the message on 2016-07-06 12:17:45 you must provide the value 1467796665- pricecat
(optional) - unsigned integer
by setting that parameter you can choose between normal and low cost price category (where applicable). Set 1 in case you want to send the message with low cost, or ignore it or set the value to 0, in case you want to send with normal cost
Error Response
In case of error, we get something like the below:
{
"success": false,
"OperationErrors": [
{
"errorCode": 13,
"errorMessage": "Invalid destination number",
"SMSErrorType": 3,
"valueOfError": "3069"
}
],
"SubmissionID": 0,
"data": null
}
[success] will be false and you’ll find the object [OperationErrors] with error details
For more details see the APPENDIX
Successful Response
{
"success": true,
"OperationErrors": null,
"SubmissionID": 0,
"data": [
{
"destination": "306912345678",
"smsid": 20818588
},
{
"destination": "306912345677",
"smsid": 20818589
},
{
"destination": "306912345676",
"smsid": 20818590
}
]
}
[success] is true and the [data] property contains the [smsid] for each SMS
Case of scheduled SMS
In cases we send scheduled SMS the batch is not stored in the SMS log tables, but in the buffer tables.
For this reason, the API does not return as above (providing the SMS id to be used by the Check the status of a submitted message) but only returns the datetime of the schedule.
To overcome this, you can use an extra property on each message, with the name [user_ref_id
]. Your request may seem like the below example:
{
"apitoken": "7ace3e49cae13ae4f5ccb8a6a8a0d6a8fe120aa82ae46ad6ee4c9d8",
"senderid": "mySender",
"sendon": 1729251298,
"messages": [
{
"destination": "306912345678",
"message": "Test message A",
"user_ref_id": "744f6643-eaed-4ea8-a3b9-7361d80a4fb0"
},
{
"destination": "306912345677",
"message": "Test message B",
"user_ref_id": "7d8fb7ab-4f7a-455a-9282-73ad556933f4"
}
]
}
- user_ref_id
string
(max 50 character) This property must have a unique value, to be distinguished among the other messages. It is recommended to use a guid, but you can also use another type of unique id
When sending scheduled SMS by providing the user_ref_id
property with a value, then the API returns with something like the below example:
{
"success": true,
"OperationErrors": null,
"SubmissionID": 0,
"data": [
{
"destination": "306912345678",
"smsid": null,
"user_ref_id": "744f6643-eaed-4ea8-a3b9-7361d80a4fb0"
},
{
"destination": "306912345677",
"smsid": null,
"user_ref_id": "7d8fb7ab-4f7a-455a-9282-73ad556933f4"
}
]
}
APPENDIX
Response properties
Name |
Description |
---|---|
success |
when false, then no message sent and the whole request is considered failed |
OperationErrors |
when success is false, we get an array of objects with errors.
Each object has 4 properties:
errorCode: the error code (integer) of the error,
errorMessage: the descriptive text of the error and
SMSErrorType: this indicates the source of the problem (please see below)
valueOfError: the value that caused the error (for debugging or troubleshooting purposes)
|
data |
in case of success, web-service is returning an array ob objects -
one for each destination, having 2 properties:
destination: the cell’s number and
smsid: the unique id of the SMS
|
OperationErrors
This is an array with objects having the properties errorCode
, errorMessage
, SMSErrorType
, valueOfError
.
In case of success this object is null
- tabid:
errCD
public enum SMS_SERVICE_ERROR_CODES
{
NO_ERROR = 0,
EMPTY_SENDERID = 1,
INVALID_SENDERID = 2,
UNAUTHORIZED_NUM_SENDER_ID = 3,
ALPHA_SENDERID_TOO_LONG = 4,
NUM_SENDERID_TOO_LONG = 5,
INTERR_NO_SMS_TYPE_PROV = 6,
INTERR_NO_SMS_TEXT = 7,
INTERNAL_ERROR = 8,
ILLEGAL_SENDERID = 9,
SMS_TEXT_EMPTY = 10,
SMS_TEXT_LEN_TOO_LONG = 11,
NO_DESTINATION_NUMBERS_PROVIDED = 12,
INVALID_DESTINATION_NUMBER = 13,
INVALID_GREEK_DEST_NUM = 14,
INVALID_CYPR_DEST_NUM = 15,
INVALID_ITALIAN_DEST_NUM = 16,
NOTFOUND_BUFFERED_BATCH_HEAD = 17,
INSUFFICIENT_USER_BALANCE = 18,
INTERR_COULDNT_FOUND_BUFFBATCH = 19,
INVALID_BATCHID_GIVEN = 20,
ERROR_CREATING_SMSLOGFILE = 21,
ERROR_WHEN_TRYING_TO_BLACKLIST = 22,
ERROR_ON_GETTING_CONTACTS = 23,
ERROR_NO_CONTACT_TO_DELETE = 24,
RECORD_ALREADY_EXISTS = 25,
RECORD_DOES_NOT_EXISTS = 26,
RECORD_CHANGE_FROM_DIFF_SESSION = 27,
PBOOK_CONTACT_CELL_EMPTY = 28,
PBOOK_CONTACT_NAME_EMPTY = 29,
PBOOK_INVLD_CELL = 30,
PBOOKGRP_NO_GROUP_PRVD_TO_DEL = 31,
ACCSETT_EMPTY_SETTINGS = 32,
INVALID_IMPORT_FILE = 33,
INSUFFICIENT_INVLD_PARAMETER_DATA = 34,
ERROR_IMPORTING_CONTACTS = 35,
INS_UPD_DUPLICATE_CELL_FOUND = 36,
NOT_ENOUGH_CREDITS_FOR_HLR_QUERY = 37,
ERROR_WHEN_TRYING_SUBMIT_USERHLR = 38,
API_TOKEN_NOT_PROVIDED = 39,
API_TOKEN_MISMATCH = 40,
INVALID_SCHEDULED_SENDOUT_DATE = 41,
SMSIDS_PARAMETER_INVALID = 42,
NO_SUBMITTED_SMS_FOUND = 43,
INVALID_API_TOKEN = 44,
VOUCHER_FROM_DIFFERENT_DOMAIN = 45,
VOUCHER_NOT_FOUND_OR_NON_FREE = 46,
VOUCHER_AMOUNT_CREDIT_FAILED = 47,
ERROR_UPDATING_CHARGED_VOUCHER = 48,
ERROR_DATA_NOT_FOUND = 49,
APITOKEN_USR_BELONGS_OTHER_MASTER = 50,
SUBACCOUNT_ALREADY_ASSIGNED = 51,
SENDERID_TOO_SHORT = 52,
ERROR_CREATING_FILE = 53,
IM_TEXT_EMPTY = 54,
IM_TEXT_LONGER_THAN_EXPECTED = 55,
IM_SENDERID_NOT_APPROVED = 56,
IM_IMAGE_INVALID = 57,
IM_ACTION_INVALID = 58,
EMPTY_OR_INVALID_PARAMETERS = 59,
DATA_VERIFICATION_ERROR = 60,
SENDERID_INJ_NUMERIC_DETECTED = 61,
SMSFORM_NO_VALUETOKEN_FOUND = 62,
SMSFORM_NO_FORM_DATA_FOUND = 63,
}
- tabid:
SMSErrType
public enum SMS_INGRENTIENT_TYPES
{
SENDERID = 1,
TEXT = 2,
DESTINATION_NUM = 3,
OTHER = 4,
}