Send message
Send Message
The SMS API enables you to send an SMS using an API and terminate to the Mobile Network Operators via an http POST request using the Base url https://sms.voxbone.com:4443/sms/v1/ and append the destination E164 and place a JSON body with the information to terminate the SMS.
Authentication
The authentication against the Voxbone SMS API is done with Digest Auth. This type of authentication should be a straightforward operation in your language of choice, there are plenty of libraries available for many languages. If you cannot find a suitable library, or are simply curious about how it works, here’s a quick summary : It applies a hash function to a password before sending it over the network, which is safer than basic access authentication, which sends plaintext.
Login/Password
The login and password that should be used is distinct from the global account password, it can be set on the sms link you configured with the Voxbone portal under Configure URI > VoxSMS (tab) > Link Creation > or the API.
Request
Base URL
Request
Path | Method | Description |
---|---|---|
/{to_e164} |
POST | Sending a message to the following phone number. |
Request body parameters
Path | Type | Description |
---|---|---|
from (mandatory) |
String | E164 with a + corresponding to the sender of the sms. Has to be a VoxSMS Voxbone DID. |
msg (mandatory) |
String | Body of the text message. Maximum available characters will vary on the charset of the message (UCS, Latin-1, GSM). Additionally, if fragmentation is used, your maximum characters allowed on the msg body will decrease. Check out our how-to guide on fragmentation for more info. |
frag->frag_ref |
Integer | Id of group of fragments. Limited to [0-65535]. This is mandatory if frag is not null. |
frag->frag_total |
Integer | Total number of fragments sms was split into. Limited to [1-255] |
frag->frag_num |
Integer | Sequence number of which fragment in group this message is in. Limited to [1 up to frag_total]. This is mandatory is frag is not null |
delivery_report |
String | Accepted values: none (No Report Requested), success (Send Delivery Report on Success Only), failure (Send Delivery Report on Failure Only), all (Send Delivery Report in all cases). Will be always “none” if delivery_report is not enabled on the link |
Sample Request
curl -X POST 'https://sms.voxbone.com:4443/sms/v1/14150000000' --digest -u username:password -H 'Content-Type: application/json' -H 'Accept: application/json' --data-binary $'{"from" : "+14151111111", "msg" : "Hello dolly!", "frag": null}'
Sample Request Body
{
"from" : "+14151111111",
"msg" : "Hello dolly!",
"frag" : null,
"delivery_report" : "none"
}
Response Values
Field | Type | Description |
---|---|---|
transaction_id | Integer | The ID of the message that was submitted (Up to 36 characters). Must be saved if you want to generate a delivery report later |
Sample Response
{
"transaction_id" : 12345
}
"transaction_id" : 12345
}
Error Codes
Technical Name | Code | Message |
---|---|---|
Postponed Delivery | 202 | Message has been accepted for later delivery |
Delivery Error | 4XX | Delivery error message |
Delivery Error | 5XX | Delivery error message |
If delivery error occurs, VoxSMS will try send the message again a every 15 minutes for up to 48 hours)