Bericht versturen
Met onze SMS API kan je jouw eigen software verbinden met onze SMS gateway.
Testomgeving nodig? Je kan als nummer 3211111111 gebruiken om onze API te testen, zonder dat er effectief een SMS verzonden wordt.
Base URL:
POST: https://core.smsbox.be/api/v1/sendsms
Parameters:
| Parameter | Input | Omschrijving |
|---|
Required
(2 mogelijkheden) | apikey
POST parameter
X-Api-Key
request header | apikey (urlencoded)
X-Api-Key: apikey | SMSBOX apikey, deze apikey kan je aanmaken door in te loggen in je SMSBOX account. |
Required | numbers | 32496123456,32479123456 | mobiele nummers gescheiden door een komma (countrycode+nummer) |
Required | message | uw bericht (urlencoded) | max. 160 tekens, zie uitzonderingen |
Optional | from | alphanumeriek tot max. 11 tekens, numeriek 16 tekens | Enkel van toepassing voor NIET BE bestemmelingen. BE = geen eigen afzender mogelijk. |
Optional | longsms | 0/1 | longsms max. 459 tekens (opgelet : 1 sms-kost = 160 tekens). Zie uitzonderingen |
Optional | noti | https://www.domein.be/script.php | doorsturen van afleverrapporten naar uw webserver via HTTP-POST met velden msgid,status. Zie de statuscodes in het tab Response |
Optional | tts | 0/1 | Text To Speech (SMS to voice call) |
Optional | ttslng | 0 = NL (Nederlands), 1 = EN (Engels), 2 = FR (Frans) | Text To Speech taal |
Ik tel 160 tekens via notepad/word, maar er wordt een dubbele sms kost aangerekend? Sommige tekens tellen voor meerdere tekens in een sms bericht. Dit heeft te maken met GSM encoding. De volgende tekens tellen voor 2 tekens \r\n, [, \, ], ^, {, |, }, ~, €. Dit kan resulteren in een hogere sms-kost.
| Name | | Name | | Name |
|---|
| € | Euro symbol | \ | Backslash | } | Right brace |
| [ | Open bracket | ^ | Caret | ~ | Tilde |
| ] | Close bracket | { | Left brace | | | Vertical bar |
| Code | Messsage | Omschrijving |
|---|
| 100 | [{"number":32412345678","msgid":123}] | SMS verzonden, in message ontvangt u het nummer en msgid. Msgid is de referentie van het afleverrapport die naar noti wordt verstuurd. |
| 01 | Sender not ok | Afzender NOK |
| 04 | Apikey not allowed | ApiKey niet correct |
| 05 | No prefix | Geen prefix opgegeven |
| 06 | No message | Geen bericht opgegeven |
| 07 | Max char reached | longsms=0, bericht max. 160 tekens
longsms=1, bericht max. 459 tekens |
| 08 | No number | Geen GSM-nummer opgegeven |
| 09 | No valid number | Geen geldig GSM-nummer |
| 10 | Not enough credits | Geen genoeg credits meer |
| 11 | Max 500 number allowed | > 500 gsm-nummers opgegeven |
| 13 | Sender too long | Afzender te lang. max. 16 tekens voor numeriek, 11 tekens voor alphanumeriek |
| Status | Omschrijving |
|---|
| 10 | Sent |
| 11 | Delivered |
| 12 | Buffered |
| 13 | Undelivered |
| 14 | Expired |
| 15 | Rejected |
| 16 | Unknown |
| 20 | Blacklist |
| 01 | Error |
Example PHP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<?php
header("content-type: text/plain");
$headerauth = true; // True/False chose for header authentication (more secure) or submit apikey in query
$apikey = ""; // Your smsbox api token
$numbers = ""; // 32496123456, multiple numbers are divided by a comma
$message = "This is a test message from smsbox";
// SendSMS
print_r(sendsms($apikey, $numbers, $message));
function sendsms($apikey, $numbers, $message) {
global $headerauth;
$data = 'numbers='.urlencode($numbers).
'&message='.urlencode($message);
if (!$headerauth) { $data .= '&apikey='.urlencode($apikey); }
$response = sendToHost($apikey, "https://core.smsbox.be/api/v1/sendsms", $data, $headerauth);
return $response;
}
function sendToHost($apikey, $url, $data, $headerauth = true) {
$headers = array();
if ($headerauth) { $headers[] = "X-Api-Key: " . $apikey; }
$headers[] = "Content-Type: application/x-www-form-urlencoded";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_FORBID_REUSE, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HEADER, 1); // Set to 0 to remove the headers from response
$response = curl_exec($ch);
return $response;
}
?>
Response:
1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200 OK
Content-Type: application/json
{
"code":100,
"message":[{
"number":"32498765432",
"msgid":15547355
}]
}
Example .NET: (required .NET Framework > 4.5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
//on top of your .cs file
using System.Net.Http;
using Newtonsoft.Json.Linq;
//call this code inside your function
var response = await sendSMS("324xxxxxxxx","This is a test message from smsbox");
//parse JSON response
JObject json = JObject.Parse(response);
int code = (int)json.GetValue("code");
if (code == 100)
{
// OK, message has been send
// if necessary you can parse the message field to retrieve the number and msgid (= message ID)
// this message ID will also be send to the "noti" variable, see documentation for more info
JArray message = (JArray)json.GetValue("message");
// Loop through the array
// [{"number":324xxxxxxxx","msgid":123}]
}
else
{
// Send message has failed, check documentation to get the description of the code.
}
private async Task<string> sendSMS(string number, string message)
{
var token = "ENTER_YOUR_APIKEY";
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", token);
var values = new Dictionary<string, string>
{
{ "numbers", number },
{ "message", message },
};
var content = new FormUrlEncodedContent(values);
var response = await client.PostAsync("https://core.smsbox.be/api/v1/sendsms", content);
var responseString = await response.Content.ReadAsStringAsync();
return responseString;
}
Saldo opvragen
Met deze API kan je het resterend aantal credits opvragen.
Base URL:
GET: https://core.smsbox.be/api/v1/balance
Parameters:
| Parameter | Input | Omschrijving |
|---|
Required
(2 mogelijkheden) | apikey
POST parameter
X-Api-Key
request header | apikey (urlencoded)
X-Api-Key: apikey | SMSBOX apikey, deze apikey kan je aanmaken door in te loggen in je SMSBOX account. |
| Code | Messsage |
|---|
| 04 | Apikey not allowed |
| 100 | Success, credits are shown in the message tag |
Example PHP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<?php
header("content-type: text/plain");
$headerauth = true; // True/False chose for header authentication (more secure) or submit apikey in query
$apikey = ""; // Your smsbox api token
// Get balance
print_r(getBalance($apikey));
function getBalance($apikey) {
global $headerauth;
if (!$headerauth) { $data = '?apikey='.urlencode($apikey); } else { $data = ''; }
$response = sendToHost($apikey, "https://core.smsbox.be/api/v1/balance" . $data, $headerauth);
return $response;
}
function sendToHost($apikey, $url, $headerauth = true) {
$headers = array();
if ($headerauth) { $headers[] = "X-Api-Key: " . $apikey; }
$headers[] = "Content-Type: application/x-www-form-urlencoded";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_FORBID_REUSE, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HEADER, 1); // Set to 0 to remove the headers from response
$response = curl_exec($ch);
return $response;
}
?>
Response:
1
2
3
4
5
6
7
HTTP/1.1 200 OK
Content-Type: application/json
{
"code":100,
"message":"1630.38"
}
One Time Passwords (OTP) versturen
Twee-Factor Authenticatie API om je gegevens, accounts en gebruikerstransacties te beveiligen.
Een handige test tool is beschikbaar in uw account onder Developers => OTP Service
Base URL:
POST: https://core.smsbox.be/api/v1/otp
Parameters:
| Parameter | Input | Omschrijving |
|---|
Required
(2 mogelijkheden) | apikey
POST parameter
X-Api-Key
request header | apikey (urlencoded)
X-Api-Key: apikey | SMSBOX apikey, deze apikey kan je aanmaken door in te loggen in je SMSBOX account. |
Required | action | send (send OTP),
verify (verify OTP) | OTP action |
Required
ACTION send | number | 32496123456 | 1 mobiele nummer, enkel bij action send |
Required
ACTION verify | otp | 123456 | OTP code, enkel bij action verify |
Optional | text | {OTP} | gebruik je eigen tekst ipv de standaard tekst. Gebruik {OTP} om de plaats van de code aan te geven in de tekst.
Voorbeeld: Beste klant, uw code is {OTP}. Vul deze in op de website.
{OTP} wordt vervangen door een OTP code.
Indien je geen {OTP} tag meegeeft in de tekst wordt de standaard tekst verzonden. |
| Code | Messsage | Number |
|---|
| 10 | Code has been sent | The recipient number |
| 11 | Number is verified | The recipient number |
| 20 | Apikey not provided |
| 21 | Apikey not allowed |
| 30 | Action not provided |
| 40 | Number verification failed |
| 41 | Number not provided |
| 42 | Only one number allowed |
| 50 | OTP not provided |
| 51 | OTP not correct |
| 60 | Credits to low |
| 90 | Custom error |
| 98 | Try again later |
| 99 | Unknown status, contact support |
Example PHP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
<?php
header("content-type: text/plain");
$headerauth = true; // True/False chose for header authentication (more secure) or submit apikey in query
$apikey = ""; // Your smsbox api token
$number = ""; // 32496123456
// Send OTP
print_r(testOTP($apikey, $number));
// Verify OTP
// print_r(testOTP($apikey, $number, 'verify', '858083'));
function testOTP($apikey, $number, $action = 'send', $otp = '') {
global $headerauth;
$data = 'action='.urlencode($action).
'&number='.urlencode($number).
'&otp='.urlencode($otp);
if (!$headerauth) { $data .= '&apikey='.urlencode($apikey); }
$response = sendToHost($apikey, "https://core.smsbox.be/api/v1/otp", $data, $headerauth);
return $response;
}
function sendToHost($apikey, $url, $data, $headerauth = true) {
$headers = array();
if ($headerauth) { $headers[] = "X-Api-Key: " . $apikey; }
$headers[] = "Content-Type: application/x-www-form-urlencoded";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_FORBID_REUSE, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HEADER, 1); // Set to 0 to remove the headers from response
$response = curl_exec($ch);
return $response;
}
?>
Response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
ACTION send:
HTTP/1.1 200 OK
Content-Type: application/json
{
"code" : 10,
"message" : "Code has been sent",
"number" : "32496123456" //your reference, always use this value instead of the provided POST number
}
ACTION verify:
HTTP/1.1 200 OK
Content-Type: application/json
{
"code" : 11,
"message" : "Number is verified",
"number" : "32496123456" //your reference
}
Mobiele nummer validatie
Met onze Mobiele nummer validatie API kan je het "Home Location Register" (HLR) opvragen van een mobiel nummer en weet je direct of een nummer 100% geldig en aangesloten/actief is op het netwerk van de GSM operator. Prijs per aanvraag is 0.25 credits.
Door regelmatig te valideren, blijft jouw telefoonlijst altijd up2date en verstuur je nooit een SMS naar een ongeldig nummer (=kostenbesparend)
Base URL:
GET: https://core.smsbox.be/api/v1/hlr
Parameters:
| Parameter | Input | Omschrijving |
|---|
Required
(2 mogelijkheden) | apikey
POST parameter
X-Api-Key
request header | apikey (urlencoded)
X-Api-Key: apikey | SMSBOX apikey, deze apikey kan je aanmaken door in te loggen in je SMSBOX account. |
Required | number | 32496123456 | mobiele nummer (countrycode+nummer) |
| Code | Messsage |
|---|
| 10 | Success, lookup array is shown in message tag |
| 20 | Apikey not provided |
| 21 | Apikey not allowed |
| 30 | Number not provided |
| 40 | Lookup failed |
| 60 | Credits low |
Example PHP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
<?php
header("content-type: text/plain");
$headerauth = true; // True/False chose for header authentication (more secure) or submit apikey in query
$apikey = ""; // Your smsbox api token
$number = ""; // The mobile number that you want to lookup
// Get hlr
print_r(getHlr($apikey, $number));
function getHlr($apikey, $number) {
global $headerauth;
if (!$headerauth) { $data = '?apikey='.urlencode($apikey)."&number=".$number; } else { $data = ''; }
$response = sendToHost($apikey, "https://core.smsbox.be/api/v1/hlr" . $data, $headerauth);
return $response;
}
function sendToHost($apikey, $url, $headerauth = true) {
$headers = array();
if ($headerauth) { $headers[] = "X-Api-Key: " . $apikey; }
$headers[] = "Content-Type: application/x-www-form-urlencoded";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_FORBID_REUSE, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HEADER, 1); // Set to 0 to remove the headers from response
$response = curl_exec($ch);
return $response;
}
?>
Response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
HTTP/1.1 200 OK
Content-Type: application/json
{
"code":10,
"message":
{
"issueing_info":
{
"verified":true,
"timezone":"Europe/Brussels",
"location":"Belgium",
"network_name":"Orange",
"country_code":32,
"area":"Belgium"
},
"home_info":
{
"verified":true,
"timezone":"Europe/Brussels",
"location":"Belgium",
"network_name":"Proximus",
"country_code":32,
"area":"Belgium"
},
"type":"Mobile",
"msisdn":"32498765432",
"error_code":0,
"error_text":"Live",
"status":"Delivered",
"mccmnc":"20601",
"is_ported":true,
"is_roaming":false
},
"number":"32498765432"
}
Voice bericht versturen
Met onze VOICE API kan je jouw eigen software verbinden met onze VOICE gateway.
Base URL:
POST: https://core.smsbox.be/api/v1/voice/send
Parameters:
| Parameter | Input | Omschrijving |
|---|
Required
(2 mogelijkheden) | apikey
POST parameter
X-Api-Key
request header | apikey (urlencoded)
X-Api-Key: apikey | SMSBOX apikey, deze apikey kan je aanmaken door in te loggen in je SMSBOX account. |
Required | number | 32496123456 | mobiele nummer (countrycode+nummer) |
Required | message | uw bericht (urlencoded) |
Optional | lang | NL/FR/EN | De taal van het bericht. Standaard: NL |
Optional | gender | M/F | Vrouw of mannelijke stem. Standaard: M |
| Code | Messsage |
|---|
| 10 | Success, voicecall is sent |
| 20 | Apikey not provided |
| 21 | Apikey not allowed |
| 30 | Number not provided |
| 40 | Message not provided |
| 50 | Send voice failed |
| 60 | Credits low |
Example PHP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<?php
header("content-type: text/plain");
$headerauth = true; // True/False chose for header authentication (more secure) or submit apikey in query
$apikey = ""; // Your smsbox api token
$number = ""; // 32496123456
$message = "This is a test message from smsbox";
// SendVoice
print_r(sendVoice($apikey, $number, $message));
function sendVoice($apikey, $number, $message) {
global $headerauth;
$data = 'number='.urlencode($number).
'&message='.urlencode($message);
if (!$headerauth) { $data .= '&apikey='.urlencode($apikey); }
$response = sendToHost($apikey, "https://core.smsbox.be/api/v1/voice", $data, $headerauth);
return $response;
}
function sendToHost($apikey, $url, $data, $headerauth = true) {
$headers = array();
if ($headerauth) { $headers[] = "X-Api-Key: " . $apikey; }
$headers[] = "Content-Type: application/x-www-form-urlencoded";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_FORBID_REUSE, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HEADER, 1); // Set to 0 to remove the headers from response
$response = curl_exec($ch);
return $response;
}
?>
Response:
1
2
3
4
5
6
7
8
HTTP/1.1 200 OK
Content-Type: application/json
{
"code":10,
"message":"Voice is sent",
"number":"32498765432"
}
