v1
latestSwagger 2.02026-07-13151175.7 KBSend Messages
Send messages to one or more recipients.
You can post up to 50,000 messages in a batch. But note that the deduplication-id is set per submission, so it is recommended that you use a smaller number, like 4000 per submission in order to make resubmissions on network failures more practical.
Repliability
When a sent message is repliable, the BulkSMS system can process an SMS response sent by your recipient.
The message sent by your customer is called a mobile originating (MO) message and would be available under RECEIVED messages. You can obtain a list of MOs using the retrieve messages API call. In addition you can also get a list of the MOs that are associated with a specific sent message (see the list related messages API call).
If you use a specific sender id in the from property of the send message, the message will not be repliable. If you want a message to be repliable, you need to specify REPLIABLE in the from.type property.
If you do not set the from property, your account settings are considered to determine whether or not the message is repliable. If the default repliable setting on your account is yes then the message will be repliable. If this setting is no, the message will not be repliable.
Body templates
When sending a message you can use template fields to customise the message text.
Field based templates allow you to create a message with place-holders for custom fields. Fields are identified by a zero based index; the first field is F0, the second is F1 and so on.
For example, let's say you want to send a daily SMS message to all your clients that tell them what their current balance is. The body of the message could look something like this
Good morning {F0######}, your balance is {F1######}
In this message, the first field, F0, is the name of the customer and he second field F1 is the balance for that customer. The # used to specify the maximum length of the field. Note that the maximum length allowed for the value includes the space taken by the braces, template name and hash symbol. For example, the value {F0#} specifies a maximum length of 5. If the data is longer than this length, the data will be truncated when the message body is constructed.
The data fields are provided in the property named fields in the to element. Here is a complete example of how this might look
{
"body": "Good morning {F0######}, your balance is {F1######}",
"to": [
{"address": "27456789","fields": ["Harry", "$1345.23"] },
{"address": "27456785","fields": ["Sally", "$2345.58"] }
]
}
If you are sending to contacts (or to groups) in your phonebook, you can use the Phonebook based templates. These are similar to the templates described above, but they have specific names. The template for the contact's first name is identified by fn and the template for the contact's surname is identified by sn. Below in an example that will work if the numbers are registered in your phonebook.
{
"body": "Hi {fn######} {sn######}, have a great day!",
"to": [
{"address": "27456789" },
{"address": "27456785" }
]
}
Query parameters
Safeguards against the possibility of sending the same messages more than once.
If a communication failure occurs during a submission, you cannot be sure that the submission was processed; therefore you would have to submit it again. When you post the retry, you must use the deduplication-id of the original post. The BulkSMS system uses this ID to check that the request was not previously processed. (If it was previously processed, the submission will succeed, and the behaviour will be indistinguishable to you from a non-duplicated submission). The ID expires after about 12 hours.
Specifies how to deal with message text that contains characters not present in the GSM 03.38 character set.
Messages that contain only GSM 03.38 characters are not affected by this setting. If the value is true then a message containing non-GSM 03.38 characters will be transmitted as a Unicode SMS (which is most likely more costly).
Please note: when auto-unicode is true and the value of the encoding property is specified as UNICODE, the message will always be sent as UNICODE.
If the value is false and the encoding property is TEXT then non-GSM 03.38 characters will be replaced by the ? character.
When using this setting on the API, you should take case to ensure that your message is clean.
Invisible unicode and unexpected characters could unintentionally convert an message to UNICODE. A common mistake is to use the backtick character (`) which is unicode and will turn your TEXT message into a UNICODE message.
Allows you to send a message in the future.
An example value is 2019-02-18T13:00:00+02:00. It encodes to 2019-02-18T13%3A00%3A00%2B02%3A00. Credits are deducted from your account immediately. Once submitted, scheduled messages cannot be changed or cancelled. The date can be a maximum of two years in the future. If the value is in the past, the message will be sent immediately. The date format requires you to supply an offset from UTC. You can decide to use the offset of your timezone, or maybe the zone of the recipient's location is more appropriate. If the destination is a group, the group members are determined at the time that you submit the message; not the time the message is scheduled to be sent.
A note that is stored together with a scheduled submission, which could be used to more easily identify the scheduled submission at a later date.
The value of this field is ignored if the schedule-date is not provided. A value that is longer than 256 characters is truncated.
Request body
Example request
[
{
"from": {
"address": "1111111"
},
"to": [
{
"type": "INTERNATIONAL",
"address": "1111111",
"fields": [
"Jack",
"$200.00"
]
}
],
"longMessageMaxParts": 99,
"body": "Hi there!",
"userSuppliedId": "submission-12765"
}
]Response
An array of the messages that were created from the request