SMS API Documentation - 1. Introduction
SMSAPI is a high-quality SMS platform, enabling you to integrate any of your applications with our SMS message sending and receiving system. The main advantage of our system is its simplicity of implementation. The SMS message may have your company name or any phone number you own as sender name. Every message sent from our system has its own unique id, which allows you to receive confirmation of its delivery.
How to start
To start using SMSAPI, you need to create an account on the SMSAPI website. Registration is completely free of charge. Your account is ready to use immediately after registration, but we recommend you to verify at least one sender name or number. The default name for all messages sent before verification is “Test”.
IP filter for API interface
In order to improve the security of the API interface, you may create a whitelist of IP addresses: IP addresses filter. Sending messages will be possible only from the whitelisted IP addresses (attempts at sending messages from other IPs will result in the following response: ERROR:105). IP addresses should be separated by semicolons.
Authentication
Example:
POST /sms.do HTTP/1.1
Host: api.smsapi.com
Authorization: Bearer token_api_oauth
We recommend OAuth 2.0 authentication. To use OAuth, please generate a new token with selected scopes in the OAuth Tokens section of the Customer Portal.
Authorization header will be necessary in request to our API.
If your environment doesn't support headers modification, please add the access_token parameter with its value to request. Please note that this is not a recommended authorization alternative and it has an adverse effect on security.
URL Adresses
URL addresses that you need to use to connect to SMSAPI are:
https://api.smsapi.com/- primaryhttps://api2.smsapi.com/- secondary
Libraries
Prepared and developed by our programmers, SMSAPI libraries enable faster and easier integration. All available libraries are hosted at GitHub.
| Programming language | Github link: |
|---|---|
| PHP | PHP library |
| C# .net | C# library |
| Bash | Bash library |
| Python | Python library |
| JavaScript (node.js) | JavaScript (node.js) library |
| Java | Java library |
| Go | Go library |
openAPI resources
SMSAPI has more API resources beyond those mentioned in this documentation. They are documented in an openAPI standard here and are constantly extended and upgraded.
2. Single SMS
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=44123456789&\
message=message_content&\
format=json"
<?php
function sms_send($params, $token, $backup = false)
{
static $content;
if ($backup == true) {
$url = 'https://api2.smsapi.com/sms.do';
} else {
$url = 'https://api.smsapi.com/sms.do';
}
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $params);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
$http_status = curl_getinfo($c, CURLINFO_HTTP_CODE);
if ($http_status != 200 && $backup == false) {
$backup = true;
sms_send($params, $token, $backup);
}
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$params = array(
'to' => '4412334445566', //destination number
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'content of message', //message content
'format' => 'json',
);
echo sms_send($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSms(SendSmsBag::withMessage('48500000000', 'Hello world!'));
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000", message="content of message", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
Example response (JSON format):
a) in case of success:
{
"count":1,
"list": [
{
"id":"1460969715572091219", //message id
"points":0.16, //price of delivery
"number":"44123456789", //recipient number with country prefix
"date_sent":1460969712, //send date
"submitted_number":"44123456789", //phone number in request
"status":"QUEUE" //message status
}
]
}
b) in case of failure:
{
"invalid_numbers":[
{
"number":"44123456789", //recipient number with country prefix
"submitted_number":"44123456789", //phone number in request
"message":"Invalid phone number" //error description
}
],
"error":13, //error code
"message":"No correct phone numbers" //error description
}
Example response (text):
a) in case of success:
OK:<ID>:<POINTS>
OK:1460969715572091219:0.16
b) in case of failure:
ERROR:<ERR>
ERROR:13
-
POST https://api.smsapi.com/sms.do– for SSL secured connections
Messages should be sent as an HTTP POST request to our system:
| Parameter | Description |
|---|---|
| access_token | OAuth token used to authenticate in our system. |
| to | Recipient's mobile phone number (recommended format: 44123456789). |
| group | Name of the group from the contacts database to which message should be sent. |
| message | The message text. Content of one message is normally 160 characters per single SMS or 70 in case of using at least one special character (polish characters are considered to be special characters). The maximal message is set to 918 normal characters or 402 if special chars are used and it is being sent as one block of 6 messages joined together and charged as six messages Detailed information about special characters are given in chapter 9. |
| from | Name of the sender. As a default the sender name is set to „Test”. Only verified names are being accepted (&from=active_name). Sender name may be set after logging into Customer Portal on Sendernames. |
| encoding | This parameter describes the encoding of the message text. UTF-8 is set as default. If another encoding is needed parameter encoding should have following value: for iso-8859-2 (latin2) – it should be &encoding=iso-8859-2 for Windows-1250 – it should be &encoding=windows-1250 |
| flash | Sending a message in flash mode can be activated by setting this parameter to „1”. Flash SMS are automatically presented on the mobile screen and have to be manually saved to be stored in inbox. (&flash=1) |
| test | When parameter test is set to „1” message won't be sent but response will be displayed, there is no charge for such test messages. (&test=1) |
| details | When details parameter is set to „1” more details in response will be displayed (message length and sms count). (&details=1) |
| date | Date in UNIX timestamp (&date=1287734110) or in ISO 8601 (&date=2012-05-10T08:40:27+00:00) when message will be sent (&date=1287734110). Setting a past date will result in sending message instantly. |
| date_validate | When parameter date_validate is set to „1” checks if date if given in proper format. Returns ERROR:54 if not. |
| time_restriction | Sets the behavior when you try to ship in hours / dates that do not match the settings in your account. Available values are follow - act according to settings,ignore - ignore settings and nearest_available - schedule shipment in the nearest allowed time. |
| allow_duplicates | When parameter allow_duplicates is set to „1” allows to send message to duplicated numbers in one request (useful i.e. for parametrized message contents) |
| idx | Optional custom value sent with SMS and sent back in CALLBACK (i.e. &idx=123). |
| check_idx | When parameter check_idx is set to „1” prevents from sending more than one message with the same idx in last 24h. When this parameter is set and message with the same idx was already sent error 53 is returned. |
| max_parts | Defines maximum message parts allowed, maximum value allowed is 6. ERROR:12 will be returned when the message has more parts than defined. Default value can be set in Customer Portal. |
| nounicode | When parameter nounicode is set to „1” prevents from sending messages containing special characters. ERROR: 11 will be returned when the message contains special characters. |
| normalize | When parameter normalize is set to „1” special chars in message will be replaced with their equivalents (ê-e, ñ-n, ý-y ...). |
| fast | Setting this parameter to „1” will result in sending message with the highest priority which ensures the quickest possible time of delivery. Fast messages costs 50% more than normal message. Attention! Mass and marketing messages must not be sent with fast parameter. |
| expiration_date | Message expiration date (in UNIX timestamp or in ISO 8601) is a date after which message won't be delivered if it wasn't delivered yet. The difference between date sent and expiration date shouldn't be less than 15 minutes and more than 72 hours (we recommend using minimum 1 hour and maximum 12 hours difference). Time will be set with tolerance +/- 5 minutes. |
| notify_url | Parameter allows to set CALLBACK URL for message from request. This parameter may be used when there is no default CALLBACK URL for this user or when it should be different than default one (notify_url has higher priority than default callback). |
| format | Parameter &format=json causes, that response is sending in JSON format. |
| ID | Message unique ID. You will need it for delivery confirmation. Length of this parameter in each request may vary, but it won't be more than 32 characters long. |
| POINTS | Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS amount) |
| ERR | Error code (check the error code list Error Codes) |
Fast messages (with highest priority)
-
POST https://api.smsapi.com/sms.do– for SSL secured connections
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=44123456789&\
fast=1&message=Fast_message_content&\
format=json"
<?php
$params = array(
'to' => '4412334445566', //destination number
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'content of message', //message content
'format' => 'json',
'fast' => '1'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmsBag = SendSmsBag::withMessage('48500000000', 'Hello world!');
$sendSmsBag->fast = true;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSms($sendSmsBag);
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send_fast(to="48500000000", message="content of message", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
Example response (JSON format):
a) in case of success:
{
"count":1,
"list": [
{
"id":"1460969715572091219", //message id
"points":0.70, //price of delivery
"number":"44123456789", //recipient number with country prefix
"date_sent":1460969712, //send date
"submitted_number":"44123456789", //phone number in request
"status":"QUEUE" //message status
}
]
}
b) in case of failure:
{
"invalid_numbers":[
{
"number":"44123456789", //recipient number with country prefix
"submitted_number":"44123456789", //phone number in request
"message":"Invalid phone number" //error description
}
],
"error":13, //error code
"message":"No correct phone numbers" //error description
}
Example response (text):
a) in case of success:
OK:<ID>:<POINTS>
OK:17101000090360359:0.70
b) in case of failure:
ERROR:<ERR>
ERROR:13
| ID | Message unique ID. You will need it for delivery confirmation.Length of this parameter in each request may vary, but it won't be more than 32 characters long. |
| POINTS | Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS amount) |
| ERR | Error code (check the error code list Error Codes) |
Setting parameter fast to „1” (&fast=1) will result in sending message with the highest priority which ensures the quickest possible time of delivery. Fast messages costs 50% more than normal message.
Scheduled SMS
-
POST https://api.smsapi.com/sms.do– for SSL secured connections
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
to=44123456789&\
date=1577878200&\
message=scheduled_message_content&\
format=json"
<?php
$params = array(
'to' => '4412334445566', //destination number
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'date' => '1577878200', //date in UNIX timestamp
'message' => 'content of message', //message content
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\ScheduleSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->scheduleSms(ScheduleSmsBag::withMessage(new DateTime(), '48500000000', 'Hello world!'));
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send_fast(to="48500000000", message="content of message", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
To send message at specified date and hour parameter date has to be used. This parameter should be in UNIX timestamp format.
Deleting single scheduled messages
The sch_del parameter allows you to delete a scheduled message based on its ID.
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
sch_del=09040616088106874&\
format=json"
<?php
$params = array(
'sch_del' => '09040616088106874', //message id
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\ScheduleSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->deleteScheduledSms(new DeleteScheduledSmssBag(['id1', 'id2']));
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.remove_scheduled(id='message ID')
for result in send_results:
print(result.id, result.points, result.error)
3. Bulk SMS
POST https://api.smsapi.com/sms.do- for SSL connection
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=48500500500,48501501501,48502502502&\
message=message&\
format=json"
<?php
$params = array(
'to' => '48500500500,48501501501,48502502502', //destination number
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'content of message', //message content
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world!'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="content of message", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
Example response (JSON format):
a) in case of success:
{
"count": 3,
"list": [
{
"id":"1460978572913968440",
"points":0.16,
"number":"48500500500",
"date_sent":1460978579,
"submitted_number":"48500500500",
"status":"QUEUE"
},
{
"id":"1460978572913968450",
"points":0.16,
"number":"48501501501",
"date_sent":1460978579,
"submitted_number":"48501501501",
"status":"QUEUE"
},
{
"id":"1460978572913968460",
"points":0.16,
"number":"48502502502",
"date_sent":1460978579,
"submitted_number":"48502502502",
"status":"QUEUE"
}
]
}
b) in case of failure:
{
"invalid_numbers": [
{
"number":"456456456",
"submitted_number":"456456456",
"message":"Invalid phone number"
},
{
"number":"321321321",
"submitted_number":"321321321",
"message":"Invalid phone number"
}
],
"error":13,
"message":"No correct phone numbers"
}
Example response (text):
a) in case of success:
OK:<ID>:<POINTS>:<PHONE>;...;...;...
OK:1460978572913968440:0.16:48500500500;OK:1460978572913968450:0.16:48501501501;
b) in case of failure:
ERROR:<err>
ERROR:13
| ID | Message unique ID. You will need it for delivery confirmation. Length of this parameter in each request may vary, but it won't be more than 32 characters long. |
| POINTS | Number of used credits (i.e. Text sent in 3 messages will return 3xSMS amount) |
| PHONE | Recipient phone number |
Sending messages to a group of recipients is similar to single submissions (presented in chapter 2). The only difference is filling the “to” field with a set of multiple recipients’ numbers (not only one number). In order to send this type of message successfully, we recommend to submit all parameters in an HTTP POST request just to assure that all recipients numbers are submitted correctly.
If the total cost of sending these messages exceeds the number of credits available in a user's account, the system will respond with a 103 error code and none of the messages will be sent. If some of the recipients’ numbers are invalid (unrecognised by SMSAPI due to a wrong prefix or because they are landline numbers), they will be skipped and not included in the bulk, while messages to the remaining numbers will be sent. The skipped numbers will not be mentioned in delivery reports. If any number appears more than once in one request, the message to such a recipient is only sent once.
Please notice that in multiple SMS sending, recipients’ numbers are present in the response as well, and each message ends with a semicolon (there is a semicolon after the last message as well).
The recommended maximum number of messages sent in one request is 10000 for the POST method.
SMS messages to numbers from contacts database group
POST https://api.smsapi.com/sms.do- for SSL connection
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
group=test_group&\
message=Test message sent to contacts from contacts database – example custom field: [%contact.field name%]\
format=json"
<?php
$params = array(
'group' => 'test_group', //destination group
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'Test message sent to contacts from contacts database', //message content
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsToGroupBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmsToGroup(SendSmsToGroupBag::withMessage('Contacts group name', 'Hello [%name%]!'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send_to_group(group="Group name", message="content of message", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
Example response (JSON format):
a) in case of success:
{
"count": 3,
"list": [
{
"id":"1460978572913968440",
"points":0.16,
"number":"48500500500",
"date_sent":1460978579,
"submitted_number":"48500500500",
"status":"QUEUE"
},
{
"id":"1460978572913968450",
"points":0.16,
"number":"48501501501",
"date_sent":1460978579,
"submitted_number":"48501501501",
"status":"QUEUE"
},
{
"id":"1460978572913968460",
"points":0.16,
"number":"48502502502",
"date_sent":1460978579,
"submitted_number":"48502502502",
"status":"QUEUE"
}
]
}
b) in case of failure:
{
"invalid_numbers": [
{
"number":"456456456",
"submitted_number":"456456456",
"message":"Invalid phone number"
},
{
"number":"321321321",
"submitted_number":"321321321",
"message":"Invalid phone number"
}
],
"error":13,
"message":"No correct phone numbers"
}
Example response (text):
a) in case of success:
OK:<ID>:<POINTS>:<PHONE>;...;...;...
OK:1460978572913968440:0.16:48500500500;OK:1460978572913968450:0.16:48501501501;
b) in case of failure:
ERROR:<err>
ERROR:13
| ID | Message unique ID. You will need it for delivery confirmation. Length of this parameter in each request may vary, but it won't be more than 32 characters long. |
| POINTS | Number of used credits (i.e. Text sent in 3 messages will return 3xSMS amount) |
| PHONE | Recipient phone number |
It is possible to send messages to a group of numbers from contacts database. However, such a group must first be created in the contacts database of our Customer Portal.
You can insert your own custom field into the content of messages intended for particular group members. Custom fields can be defined on Custom fields. To insert custom field into message use [%contact.field name%]. This expression will be replaced with a corresponding value assigned to contact.
Bulk personalized SMS sending using parameters
POST https://api.smsapi.com/sms.do- for SSL connection
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=48600111222,48500111222&\
message=Message content,param1:[%1%]param2:[%2%]&\
param1=John|Ann&\
param2=30|40&\
format=json"
<?php
$params = array(
'to' => '48600111222,48500111222', //destination numbers
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'Message content,parameter1:[%1%]parameter2:[%2%]', //message content
'param1' => 'John|Ann',
'param2' => '30|40',
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmssBag = SendSmssBag::withMessage(['48500000000', '48500000000'], '[%1%] [%2%]!')
->setParams([1 => ['Hello', 'Hello2'], 2 => ['world', 'world2']]);
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmss($sendSmssBag);
var_dump($sms);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to=['48500000000', '48500000001'], message='message test, parameter1:[%1%] parameter2:[%2%]', param1=['Jack', 'Annie'], param2=['30', '40'], from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
Message will have following contents:
Message 1: Message content, parameter1: John parameter2: 30
Message 2: Message content, parameter1: Ann parameter2: 40
It is possible to send up to 100 personalized messages in one request using personalization parameters. Sending more personalized messages requires more than one request. Personalization parameters should be defined in the request as param1, param2, param3, param4, which will replace tags [%1%], [%2%], [%3%] and [%4%] in message content. The values of these parameters have to be separated by pipe char „|” in accordance with the template below:
param1=Ann|Michael|Andrew¶m2=Smith|Thomas|Davis
The number of parameters has to be exactly the same as the number of recipients in the request. Otherwise, ERROR: 18 will be returned and the messages won't be sent.
If one of the numbers is invalid, the message to this number will be skipped and the remaining messages will be sent.
Parameters - After defining parameters the may be used in message content:
| Parameter | Description |
|---|---|
| [%1%] | Value of parameter 1 (param1) |
| [%2%] | Value of parameter 2 (param2) |
| [%3%] | Value of parameter 3 (param3) |
| [%4%] | Value of parameter 4 (param4) |
Bulk SMS using IDX parameter
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmssBag = SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world!');
$sendSmssBag->idx = ['id-1', 'id-2'];
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmss($sendSmssBag);
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to=['48500000000', '48500000001'], message='content of message', idx=['idx1', 'idx2'], from_="sender name")
for result in send_results:
print(result.id, result.points, result.error)
There is a possibility to send mass messages with custom IDX parameters different for each message. Such parameters will be returned in CALLBACK. An additional check_idx parameter (&check_idx=1) may be used with idx parameters. Using the check_idx parameter prevents two messages from being sent with the same idx parameter value within 24h. Example of using the idx parameter:
idx=idx1|idx2|idx3|idx4
The number of IDX parameters must be the same as the number of recipients numbers given in the request.
Discount Codes
POST https://api.smsapi.com/sms.do- for SSL connection
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=48600111222,48500111222&\
discount_group=codes&\
message=Message content with discount code: [%code%]&\
format=json"
<?php
$params = array(
'discount_group' => 'codes', //group of codes
'to' => '48600111222,48500111222', //receive numbers
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'Message content with discount code: [%code%]', //message content
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world! Discount code: [%code%]'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="content of message, Discount code: [%code%]", from_="sender name")
for result in send_results:
print(result.id, result.points, result.error)
The discount code feature allows you to generate/import codes for use in our service. A new group of discount codes can be added in two ways: - by clicking "Import codes" – when you want to add a .csv file containing your own codes (in one column), - by clicking "Generate codes" – our system will then generate a group of codes for you (you may choose the type, length, and amount of codes).
To use discount codes in SMS messaging, simply select the appropriate group of discount codes and then add the [%code%] parameter in the content. To use a group of discount codes they must be active (not expired) and contain a propriate number of characters. When the code is used by a customer it will be displayed as "redeemed".
Messages with cut.li
POST https://api.smsapi.com/sms.do- for SSL connection
Example request:
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=49500500500,42501501501,47502502502&\
message=test_message_with_short_link:_[%goto:www.smsapi.com%]&\
format=json"
<?php
$params = array(
'to' => '48600111222,48500111222', //destination numbers
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'test message with short link: [%goto:www.smsapi.com%]', //message content
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'Hello world! Go: [%goto:www.smsapi.com%]'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="content of message Go: [%goto:www.smsapi.com%]", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
This function enables sending SMS messages with a shortened URL (http://cut.li) redirecting the recipient to a URL added as a parameter. In the SMS message, the URL should be added as a [%goto:url_address%] parameter and it will be displayed e.g. as http://cut.li/ABCD (each recipient will receive a unique end of link "/ABCD"). It's possible to add up to 100 recipients when short link is used.
Individual links are valid for 30 days, while links with the same URL for every recipient are valid for 10 years.
Messages with Opt-out link
POST https://api.smsapi.com/sms.do- for SSL connection
curl -X POST -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=49500500500,42501501501,47502502502&\
message=test_message_with_Opt-out link:_[%opt_out_link%]&\
format=json"
<?php
$params = array(
'to' => '48600111222,48500111222', //destination numbers
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'message' => 'test message with Opt-out link: [%opt_out_link%]', //message content
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmssBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Sms[] $smss */
$smss = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSmss(SendSmssBag::withMessage(['48500000000', '48500000001'], 'test_message_with_Opt-out link:_ [%opt_out_link%]'));
var_dump($smss);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
send_results = client.sms.send(to="48500000000,48500000001,48500000002", message="message test with Opt-out: [%opt_out_link%]", from_="sendername")
for result in send_results:
print(result.id, result.points, result.error)
The Opt-out SMS function allows you to add URL into the SMS message which unsubscribes a given user from the database in the SMSAPI Customer Portal. In order to place the Opt-out link in the message text, add [%opt_out_link%] to the message parameter. The numbers that use the link are on the Opt-out list and will be excluded from future campaigns.
Opt-out links expire after 14 days.
4. SMS templates
Example request:
Template name: Notify
Template content: Hello [%1%], Your order has been sent. The shipment number is [%2%]. You may follow it on our site.
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=49500500500&\
template=Notify&\
param1=Mark&\
param2=BG12344423&\
format=json"
<?php
$params = array(
'to' => '49500111222', //destination numbers
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'template' => 'Notify', //template name
'param1' => 'Mark',
'param2' => 'BG12344423',
'format' => 'json'
);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Sms\Data\Sms;
use Smsapi\Client\Curl\SmsapiHttpClient;
$sendSmsBag = SendSmsBag::withTemplateName('48500000000', 'Notify');
$sendSmsBag->setParams([1 => 'Mark', 2 => 'BG12344423']);
/** @var Sms $sms */
$sms = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->smsFeature()
->sendSms($sendSmsBag);
var_dump($sms);
The content of sent message:
Hello Mark, Your order has been sent. The shipment number is BG12344423. You may follow it on our site.
Templates simplify changing standard notification messages (they may be used in shops, internet services, medical clinics etc.) without changing the php script responsible for SMS sending. Follow these steps to use templates:
- After logging on
https://ssl.smsapi.comyou can add template in Templates - The Places that should be replaced by a parameter should be given [%N%] where N is number between 1 and 4(parameter number)
- To use a template in API request there should appear &templates=template_name in the request
- Apart from all basic parameters while using templates following parameters are available:
| Parameter | Description |
|---|---|
| template | Template name |
| param N | The value of this parameter will replace [%N%]in the template where N is a number between 1 and 4 |
| single | If the message will contain more than 160 chars (single message) it won't be sent and ERROR:12 will be replied (&single=1) |
5. mail2sms
Sending sms with mail2sms requires sending a mail following this pattern:
| TO: | sms.do@smsapi.com |
| SUBJECT: | username@password_hashed_in_md5 |
| CONTENT: | from=sender_name&to=number&message=message_content |
Adding parameter raport=1 will result in sending back e-mail containing request status (sent confirmation or error code – this is useful while testing the service):
| TO: | sms.do@smsapi.com |
| SUBJECT: | username@password_hashed_in_md5 |
| CONTENT: | from=sender_name&to=number&raport=1&message=message_content |
Mail may be sent in plain / quotedprintable / base64 encoding. Sender name (parameter &from=) have to be active.
In addition to the parameters listed in the examples above, mail2sms includes all the parameters listed in chapter 2. Single SMS.
6. Account balance
Example request:
curl -X GET -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/profile"
<?php
function getPoints($token)
{
static $content;
$url = 'https://api.smsapi.com/profile';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo getPoints($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Profile\Data\Profile;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Profile $profile */
$profile = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->profileFeature()
->findProfile();
var_dump($profile->points);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
def get_account_balance():
r = client.account.balance()
print(r.points, r.pro_count, r.eco_count, r.mms_count, r.vms_gsm_count, r.vms_land_count)
Example response:
a) in case of success:
{
"name": "string",
"email": "string",
"username": "string",
"phone_number": "string",
"payment_type": "prepaid",
"user_type": "native",
"points": 0 // number of credits avaivable in SMSAPI service
}
b) in case of failure:
{
"message":"Authorization failed",
"error":"authorization_failed",
"developer_description":null,
"errors":null
}
-
https://api.smsapi.com/profile- for SSL connection
There is an additional function allowing you to check the current account balance. An example of using the function can be found below.
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system. |
| Response data | Description |
|---|---|
| points | Number of points available on SMSAPI platform |
| name | Company name |
| Contact email | |
| username | SMSAPI username |
| phone_number | Contact phone number |
| payment_type | Type of payment |
| user_type | Type of user on SMSAPI platform, native or subuser |
7. Callback Reports
The callback service updates you about message status (delivery reports), shortened URL clicks (cut.li) or HLR lookups via an endpoint set on an SMSAPI user’s side. You enter the URL address of the endpoint in the Customer Portal. When a new event occurs, SMSAPI generates a POST or GET request with data to the SMSAPI user’s endpoint.
Requests may be generated from following IP addresses: 206.189.63.71, 3.123.166.170, 91.185.184.29, 89.174.81.98, 91.185.187.219, 213.189.53.211
Requests to the callback address are repeated cyclically until they are received or the associated message is archived. Sending requests to the callback address may be blocked if too many errors are detected during the transmission on the client's side.
SMS callback
We offer you possibility to run any available script in the web with callback delivery reports. In order to use this option please login on our site https://api.smsapi.com and set the „Callback address DLR_SMS” in Callback URLs.
Receiving delivery report example (CALLBACK SMS DLR)
<?php
if($_GET['MsgId'] && $_GET['status'] ) {
mysqli_connect('host', 'user', 'password', 'database');
$arIds = explode(',',$_GET['MsgId']);
$arStatus = explode(',',$_GET['status']);
$arIdx = explode(',',$_GET['idx']);
if($arIds) {
foreach($arIds as $k => $v) {
mysqli_query("UPDATE sms SET sms_status = '".mysqli_real_escape_string($arStatus[$k])."',
sms_index = '".mysqli_real_escape_string($arIdx[$k])."' WHERE sms_id ='".mysqli_real_escape_string($v)."' LIMIT 1");
}
mysqli_close();
echo "OK";
}
?>
Example response:
a) Example with one value:
https://my_site.com/status_update?MsgId=613F1B14346335B944450980&donedate=1631525653&from=Test&idx=1&mcc=260&mnc=3&points=0.0&sent_at=1631525653&status=403&status_name=SENT&to=48500500500&username=smsapi.user
b) Example with five values:
https://my_site.com/status_update?MsgId=613F14C4346335AE0B1DBA31%2C613F14C4346335AE0B1DBA2E%2C613F14C4346335AE0B1DBA30%2C613F14C4346335AE0B1DBA2F%2C613F14C4346335AE0B1DBA2D&donedate=1631525676%2C1631525676%2C1631525676%2C1631525676%2C1631525676&from=Test%2CTest%2CTest%2CTest%2CTest&idx=%2C%2C%2C%2C&mcc=260%2C260%2C260%2C260%2C260&mnc=3%2C3%2C3%2C3%2C3&points=0.16%2C0.16%2C0.16%2C0.16%2C0.16&sent_at=1631525676%2C1631525676%2C1631525676%2C1631525676%2C1631525676&status=403%2C403%2C403%2C403%2C403&status_name=SENT%2CSENT%2CSENT%2CSENT%2CSENT&to=48500500500%2C48500500500%2C48500500500%2C48500500500%2C48500500500&username=smsapi.user%2Csmsapi.user%2Csmsapi.user%2Cmsmsapi.user%2Csmsapi.user
Example: http://www.my_site.com/status_update.php
System sends parameters using the GET method. Every parameter could have up to 5 values. Amount of values will be always the same for all parameters.
Parameters are described in following table:
| Parameter | Description |
|---|---|
| MsgId | Message ID. Length of this parameter in each request may vary, but it won't be more than 32 characters long. |
| status | Status code, list of codes can be find in Statuses |
| status_name | Status name, list of names can be find in Statuses |
| idx | Optional parameter send with SMS |
| sent_at | Date in UNIX timestamp of creating message |
| donedate | Date in UNIX timestamp of delivery report |
| username | Username which sent SMS |
| points | Number of used credits |
| to | Mobile phone number of the recipient |
| mcc | Mobile country code |
| mnc | Mobile network code |
All characters are case sensitive!
Bulk callback
Bulk CALLBACK script receives a request the moment sending a bulk starts. This feature is generally useful for scheduled bulks. The request contains parameters presented in the table below. In order to enable Bulk CALLBACK please enter CALLBACK script URL in Callback URLs.
Example: http://www.my_site.com/bulk_callback.php
Parameters are described in following table:
| Parameter | Description |
|---|---|
| type | Messages type SMS/MMS/VMS |
| all | Total number of messages (phone numbers) in bulk |
| points | Credits needed for the dispatch. |
| info | Defines if the bulk was sent using „Numbers from file”, „Numbers and content from file” or „Numbers from contacts database” tab |
| text | Message content. |
All characters are case sensitive!
Cut.li callback
In order to check cut.li URL visits please log in to the Customer Portal and enter in Callback URLs the address to a script to which information about URL visit should be sent.
Parameter will be sent using GET method separated by commas:
$_GET['MsgId']=09062414383994024
$_GET['operating_system']=Android
Example: http://www.my_site.com/bulk_callback.php
Parameters are described in following table:
| Parameter | Description |
|---|---|
| MsgId | Message ID. Length of this parameter in each request may vary, but it won't bemore than 32 characters long. |
| MsgIdx | Optional custom value sent with SMS (idx). |
| suffix | Suffix for shortened URL, e.g. Hq9Y (for http://idz.do/Hq9Y) |
| to | Recipient's phone number |
| click_date | Time of first link click in unixtime format |
| device | Device type |
| operating_system | Operating system |
| browser | Browser type |
| username | Username from which message was sent |
| ip | IP address from which short URL was clicked |
All characters are case sensitive!
8. Receiving messages
<?php
function messageReceive()
{
$received = $_POST;
$content = print_r($received, true);
$sms_from = $received['sms_from'];
$sms_to = $received['sms_to'];
$sms_date = $received['sms_date'];
$sms_text = $received['sms_text'];
$username = $received['username'];
$filename = "sms.log";
file_put_contents($filename, $content);
if (is_file($filename)) {
return true;
} else {
return false;
}
}
if ($_POST) {
if (messageReceive() === true) {
echo "OK";
}
}
?>
Receiving messages may be done using CALLBACK script located on client's server. Address to this script should be entered here Callback URL with Type selected as “Callback address SMS receive”. The script works as follows:
After receiving message we will send query to the script with POST table that contains following parameters:
| Parameter | Description |
|---|---|
| sms_to | Recipient's phone number |
| sms_from | Sender phone number |
| sms_text | Message content |
| sms_date | Date in timestamp taken from the message |
| username | Username of the client to which message has been assigned |
Data will be sent in UTF-8 encoding.
9. HLR Lookup
Example request:
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/hlr.do?\
number=44123123123,44234234234&\
format=json"
<?php
$params = array(
'access_token' => 'token_api_oauth', //https://ssl.smsapi.com/react/oauth/manage
'number' => '48500000000', //number to check
'format' => 'json'
);
if ($params['access_token']&&$params['number']) {
$date = '?'.http_build_query($params);
$file = fopen('https://api.smsapi.com/hlr.do'.$date,'r');
$result = fread($file,1024);
fclose($file);
echo $result;
}
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Hlr\Bag\SendHlrBag;
use Smsapi\Client\Feature\Hlr\Data\Hlr;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Hlr $hlr */
$hlr = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->hlrFeature()
->sendHlr(new SendHlrBag('48500000000'));
var_dump($hlr);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
def check_number():
r = client.hlr.check_number(number='48500000000')
print(r.status, r.number, r.id, r.price)
Example response (JSON format):
a) in case of success:
{
"status": "OK",
"number": "48100200300",
"id": "46567088",
"price": "0.0500"
}
b) in case of failure:
{
"status":"ERROR",
"number":"481002003001", // invalid phone number
"error":13 // error code
}
Example response (text):
a) in case of success:
OK:<NUMBER>:<ID>:<POINTS>;OK:<NUMBER>:<ID>:<POINTS>;...;...
OK:44123123123:80625:0.006;OK:44234234234:80627:0.006;
b) in case of failure:
ERROR:<NUMBER>:<ERR>;ERROR:<NUMBER>:<ERR>;...;...
OK:44123123123:80625:0.006;ERROR:4433412333:13;
where:
<NUMBER> Checked number
<ID> Checking unique ID
<POINTS> Number of used credits
<ERR> Error code
Example of data sent to the callback script (sent to the URL provided in a POST table):
Array
(
[0] => Array
(
[id] => 80625
[number] => 48600600600
[mcc] => 260
[mnc] => 2
[info] => T-Mobile
[status] => OK
[date] => 1302703609
[ported] => 0
[ported_from] => null
)
[1] => Array
(
[id] => 80627
[number] => 48500600700
[mcc] => 260
[mnc] => 2
[info] => ABSENT_SUBSCRIBER
[status] => FAIL
[date] => 1302703609
[ported] => 0
[ported_from] => null
)
)
HLR (Home location Register) is an extensive base including different kinds of information about every working telephone number in GSM. In order to use this option, you should send a request to following URL:
https://api.smsapi.com/hlr.do– for SSL secured connections
with proper parameters described below. There might be up to 20 numbers in one request. All information about numbers will be sent to address given on our site https://ssl.smsapi.com at „Callback address HLR” in „API Settings” → „Callback URLs”.
It is important that the address entered is a valid address to an existing, available script. After checking a number in the HLR, information about the number will be sent to the URL provided in a POST table.
HLR error code list can be checked in the Error codes tab.
The parameters are described in the table below:
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system. |
| number | Numbers to be checked in HLR. |
| idx | Optional custom value sent with SMS and sent back in CALLBACK. Parameter idx may contain up to 255 chars, allowed characters are digits 0 – 9 and letters a – z (parameter is not case sensitive). (&idx=123) |
The parameters returned to the script are described in the table below:
| Parameter | Description |
|---|---|
| id | ID returned as a response to the request |
| number | Checked number |
| mcc | Mobile country code |
| mnc | Mobile network code |
| info | Name of network or description of error |
| status | OK when number is correct, FAIL when number is wrong |
| date | UNIX timestamp when number was checked |
| ported | 0 number not ported, 1 number ported |
| ported_from | null when number is not ported or name of network from which number is ported |
| idx | Optional custom value sent with HLR request and sent back in CALLBACK (&idx=123) |
All characters are case sensitive!
The data is sent in UTF8 encoding. The list of possible errors, which may appear in infofield, with description, can be found in Error Codes.
10. Contact database
GET https://api.smsapi.com/contacts- for SSL connection
Endpoint contacts allows you to perform operations on contacts.
List contacts
GET https://api.smsapi.com/contacts
curl -X GET -H "Authorization: Bearer token_api_oauth" https://api.smsapi.com/contacts?\
birthday_date=between%281997-02-24%2C%202002-02-24%29
<?php
function getContact($token,$params)
{
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/contacts?'.$params);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$params = 'phone_number=48500500500';
// or when using operators on custom field
// $params = 'custom_field=9' -- Listing contacts where custom_field is equal to 9, 91, 99 etc.
// $params = 'custom_field=between(9,11) -- Listing contacts where custom_field is between two given values.
echo getContact($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\FindContactsBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
$findContactsBag = new FindContactsBag();
$findContactsBag->phoneNumber = 48500000000;
/** @var Contact[] $contacts */
$contacts = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->contactsFeature()
->findContacts($findContactsBag);
var_dump($contacts);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
def get_all_contacts():
l = client.contacts.list_contacts()
for c in l:
print(c.id, c.first_name, c.last_name, c.phone_number)
Example response:
a) in case of success:
{
"size":1,
"collection":[
{
"id":"5b83ba81a788494a0469490f",
"first_name":"name",
"last_name":"surname",
"birthday_date": "1998-03-09",
"phone_number":"48500000000",
"email":"bok@smsapi.com",
"gender":"male",
"city":"City",
"country":"Poland",
"source":"source",
"date_created":"2018-08-27T10:46:57+02:00",
"date_updated":"2018-08-27T10:46:57+02:00",
"groups":[
{
"id":"59a3ca1fa78849062837cd0c",
"name":"default",
"date_created":"2017-08-28T09:45:35+02:00",
"date_updated":"2017-08-28T09:45:35+02:00",
"description":"",
"created_by":"login",
"idx":null,
"contact_expire_after":null,
"contacts_count":null
}
]
}
]
}
b) in case of failure:
{
"message":"Authorization failed",
"error":"authorization_failed",
"errors":null
}
The following parameters allow you to filter the list of contacts in this function. The search is case-insensitive.
You can also filter the contacts by your own custom fields. You can define them on Custom fields.
| Parameter | Description |
|---|---|
| q | The parameter allows you to search for contacts containing the given string of characters within the basic fields in the bases of the constitutions, i.e. name, surname, telephone number, email, city. |
| offset | Specifying from which place in a row contacts will be listed. |
| limit | The limit of clients to be listed. |
| sort | The parameter specifies the field in the contact database after which the data sorting will be performed. The increasing direction is, for example, sort = last_name and the descending direction is, for example, sort = -last_name. |
| phone_number | Listing a contact with a given telephone number. |
| Listing a contact with a given email address. | |
| first_name | Listing contacts of a given name. |
| last_name | Listing contacts with the given last name. |
| group_id | Listing contacts belonging to a specific group (specify groupID). |
| gender | Listing contacts with a given gender, male or female. |
| birthday_date | Listing contacts at the given birth date. The date is given in format YYYY-MM-DD. |
You can also use the following operators for filtering. They may not work with every parameter type.
| Operator | Description |
|---|---|
| gt | Operator "greater than" listing contacts where value is greater than value given in parameter. |
| lt | Operator "less than" listing contacts where value is less than value given in parameter. |
| gte | Operator "greater or equal" listing contacts where value is greater or equal to value given in parameter. |
| lte | Operator "less or equal" listing contacts where value is less or equal to value given in parameter. |
| eq | Operator "equal" listing contacts where value is equal to value given in parameter. |
| = | Operator "like" listing contacts where value contains the value given in parameter. |
| between | Listing contacts where value is between values given in parameters. |
Create contact
POST https://api.smsapi.com/contacts
curl -X POST "https://api.smsapi.com/contacts" -H "Authorization: Bearer token_api_oauth" -d\
"phone_number=48500000000&email=bok@smsapi.com&first_name=Name&last_name=Last_name&gender=gender\
&description=description&city=city&groups=default"
<?php
function contactsCreate($params, $token)
{
static $content;
$url = 'https://api.smsapi.com/contacts';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $params);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$params = http_build_query(array(
'phone_number' => '48500000000',
'email' => 'bok@smsapi.com',
'first_name' => "Name",
'last_name' => "Last Name",
'gender' => "Gender", // male or female
'birthday_date' => "Birthday", // YYYY-MM-DD
'city' => "City",
'source' => "source"
));
echo contactsCreate($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\CreateContactBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Contact $contact */
$contact = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->contactsFeature()
->createContact(CreateContactBag::withEmail('example@example.com'));
var_dump($contact);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
def create_contact():
c = client.contacts.create_contact(
first_name='first name',
last_name='last name',
phone_number=48500000000,
email='adres email',
birthday_date='1970-01-01',
gender='{male|female|undefined}',
city='city',
description='description')
Example response:
a) in case of success:
{
"id":"5b802315a788494a04690d1d",
"first_name":"string",
"last_name":"string",
"phone_number":"48500000000",
"email":"bok@smsapi.com",
"gender":"gender",
"city":"city",
"date_created":"2018-08-24T17:24:05+02:00",
"date_updated":"2018-08-24T17:24:05+02:00",
"description":"description",
"groups":
[
{
"id":"59a3ca1fa78849062837cd0c",
"name":"default",
"date_created":"2017-08-28T09:45:35+02:00",
"date_updated":"2017-08-28T09:45:35+02:00",
"description":"",
"created_by":"username",
"idx":null,
"contact_expire_after":null,
"contacts_count":null
}
]
}
b) in case of failure:
{
"message":"Contact already exists",
"error":"contact_conflict",
"code":409,
"errors":[],
"developer_description":null
}
| Parameter | Description |
|---|---|
| token_api_oauth | Token SMSAPI. |
| phone_number | Phone number. |
| Email address. | |
| first_name | Name. |
| last_name | Last Name. |
| gender | Gender, male or female. |
| birthday_date | In format YYYY-MM-DD |
| city | City |
| description | Description |
If the request is successful:
| Response | Description |
|---|---|
| id | Contact ID |
| first_name | Name saved in the contact database. |
| last_name | Last name saved in the contact database. |
| phone_number | Phone number saved in the contact database. |
| Email address saved in the contact database. | |
| gender | Gender saved in the contact database. |
| city | City saved in the contact database. |
| date_created | The date of creating the contact in the database. |
| date_updated | Date of the last update of the contact in the database. |
| description | Description saved in the contact database. |
| groups | Groups to which contact belongs. |
If error occurred:
| Response | Description |
|---|---|
| message | Error description. |
| error | Error type. |
| errors | error table. |
Edit contact
The function allows you to edit the contact based on its ID.
PUT https://api.smsapi.com/contacts/{contactId}
curl -X PUT -H "Authorization: Bearer token_api_oauth" -d 'email=tech@smsapi.com\
&phone_number=48500000001&email=tech@smsapi.com&first_name=name&last_name=LastName&gender=Gender' https://api.smsapi.com/contacts/Contact_id
<?php
function putContact($id,$params,$token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/contacts/'.$id);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$params = (array(
'phone_number' => '48500000001',
'email' => 'tech@smsapi.com',
'first_name' => "Name",
'last_name' => "Last Name",
'gender' => "Gender", // male or female
'birthday_date' => "Birthday", // YYYY-MM-DD
'city' => "City"
));
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$id = "contact_id"; //contact ID
echo putContact($id, $params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\UpdateContactBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
$update = new UpdateContactBag('contact_id');
/** @var Contact $contact */
$contact = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->contactsFeature()
->updateContact($update->setName('Name', 'Last name'));
var_dump($contact);
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
def update_contacts():
c = client.contacts.update_contact(contact_id=1, description='new description', email='new email address')
print(c.id, c.first_name, c.last_name, c.phone_number)
Example response:
a) in case of success:
{
"id":"5b83ba81a788494a0469490f",
"first_name":"Name",
"last_name":"Last name",
"phone_number":"48500000001",
"email":"tech@smsapi.com",
"gender":"undefined",
"city":"City",
"country":"Poland",
"source":"source",
"date_created":"2018-08-27T10:46:57+02:00",
"date_updated":"2018-08-27T14:17:20+02:00",
"groups":[
{
"id":"59a3ca1fa78849062837cd0c",
"name":"default",
"date_created":"2017-08-28T09:45:35+02:00",
"date_updated":"2017-08-28T09:45:35+02:00",
"description":"",
"created_by":"username",
"idx":null,
"contact_expire_after":null,
"contacts_count":null
}
]
}
b) in case of failure:
{
"message":"Authorization failed",
"error":"authorization_failed",
"errors":null
}
| Parameter | Description |
|---|---|
| token_api_oauth | Token SMSAPI |
| id | Contact Id |
| first_name | Name |
| last_name | Last name |
| phone_number | Phone number |
| gender | Gender |
| city | City |
| date_created | Date when contact created |
| date_updated | Date last contact update |
| description | Description |
If the request is successful:
| Response | Description |
|---|---|
| id | Contact ID |
| first_name | Name saved in the contact database. |
| last_name | Last_name saved in the contact database. |
| phone_number | Phone number saved in the contact database. |
| Email address saved in the contact database. | |
| gender | Gender saved in the contact database. |
| city | City saved in the contact database. |
| date_created | The date of creating the contact in the database. |
| date_updated | Date of the last update of the contact in the database. |
| description | Description saved in the contact database. |
| groups | Groups to which contact belongs. |
If error occur:
| Response | Description |
|---|---|
| message | Error description. |
| error | Error type. |
| errors | error table. |
Assign contact to group
curl -X PUT -H "Authorization: Bearer token_api_oauth"
'https://api.smsapi.com/contacts/{contactId}/groups/{groupId}'
<?php
function putContact($contactId, $groupId, $token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/contacts/'.$contactId.'/groups/'.$groupId);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$contactId = "contact_id";
$groupId = "group_id";
echo putContact($contactId, $groupId, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Groups\Bag\AssignContactToGroupBag;
use Smsapi\Client\Feature\Contacts\Data\Contact;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Contact $contact */
$contact = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->contactsFeature()
->groupsFeature()
->assignContactToGroup(new AssignContactToGroupBag('contact_id', 'group_id'));
var_dump($contact);
Example response:
a) in case of success:
{
"size":1,
"collection":[
{
"id":"1238f47da26ee45dc41fb987",
"name":"Test group",
"date_created":"2022-04-01T12:00:00+02:00",
"date_updated":"2022-04-01T12:00:00+02:00",
"description":"",
"created_by":"smsapi_user",
"idx":"",
"contact_expire_after":null,
"contacts_count":1,
"permissions":[
{
"username":"smsapi_user",
"group_id":"1238f47da26ee45dc41fb987",
"write":true,
"read":true,
"send":true
}
]
}
]
}
b) in case of failure:
{
"message":"Authorization failed",
"error":"authorization_failed",
"errors":null
}
This function allows you to assign contact to selected group based on its ID.
PUT https://api.smsapi.com/contacts/{contactId}/groups/{groupId}
| Parameter | Description |
|---|---|
| contactId | Contact ID |
| groupId | Group ID |
To remove contact from the selected group, send a DELETE request instead of a PUT with the same parameters.
DELETE https://api.smsapi.com/contacts/{contactId}/groups/{groupId}
Delete contacts
The function allows you to delete a contact based on its ID.
DELETE https://api.smsapi.com/contacts/{contactId}
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.com/contacts/Contact_id
<?php
function deleteContact($contactID,$token)
{
$url = "https://api.smsapi.com/contacts/".$contactID;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$contactID = "Contact_id";
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo deleteContact($contactID,$token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Contacts\Bag\DeleteContactBag;
use Smsapi\Client\Curl\SmsapiHttpClient;
(new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->contactsFeature()
->deleteContact(new DeleteContactBag('000000000000000000000000'));
from smsapi.client import Client
client = Client("https://api.smsapi.com", access_token="%SMSAPI_ACCESS_TOKEN%")
def remove_contact():
client.contacts.delete_contact(contact_id=1)
11. Black List
Endpoint blacklist allows you to perform operations on blacklist.
Blacklist option allows you to add numbers to which sending SMS messages will be blocked on your account (e.g. if client from your database don't want to receive SMS from you anymore). You may also set expiration date for each record after which number will not be blocked any more.
List Blacklist
GET https://api.smsapi.com/blacklist/phone_numbers
curl -H "Authorization: Bearer token_api_oauth" -H \
"Content-Type: application/json" -X GET https://api.smsapi.com/blacklist/phone_numbers
<?php
function getBlacklist($token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/blacklist/phone_numbers');
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo getBlacklist($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Blacklist\Bag\FindBlacklistedPhoneNumbersBag;
use Smsapi\Client\Feature\Blacklist\Data\BlacklistedPhoneNumberFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->blacklistFeature()
->findBlacklistedPhoneNumbers(new FindBlacklistedPhoneNumbersBag());
var_dump($blacklist);
Example response:
a) in case of success:
[{
"id":"ID_number",
"phone_number":"48500000000",
"created_at":"2018-11-08T09:36:53+01:00",
"expire_at":"2021-03-16"
},
{
"id":"ID_number",
"phone_number":"48500000001",
"created_at":"2018-11-08T09:36:53+01:00",
"expire_at":null
}]
b) in case of failure:
{
"error": 101,
"message": "authorization_failed"
}
| Parameter | Description |
|---|---|
| token_api_oauth | SMSAPI token |
| id | Id query |
| phone_number | The number added to the blacklist |
| created_at | Date of being added to the blacklist |
| expire_at | The expiration date of the entry to the blacklist (if "null" it never expires) |
Adding number to Black list
This function allows you to add a number to your Black list.
POST https://api.smsapi.com/blacklist/phone_numbers
curl -i -H "Authorization: Bearer token_api_oauth" -H "Content-Type: application/json" -X POST -d \
'{"phone_number":"48500000000","expire_at":"2021-03-16"}' https://api.smsapi.com/blacklist/phone_numbers
<?php
function addNumbertoblacklist($params, $token)
{
static $content;
$url = 'https://api.smsapi.com/blacklist/phone_numbers';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$params = array(
'phone_number' => '48500000000',
'expire_at' => '2021-03-16',
);
echo addNumbertoblacklist($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Blacklist\Bag\CreateBlacklistedPhoneNumberBag;
use Smsapi\Client\Feature\Blacklist\Data\BlacklistedPhoneNumberFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->blacklistFeature()
->createBlacklistedPhoneNumber(new CreateBlacklistedPhoneNumberBag('48500000000'));
var_dump($blacklist);
Example response:
a) in case of success:
{
"id":"ID_number",
"phone_number":"48500000000",
"created_at":"2018-11-08T09:36:53+01:00",
"expire_at":"2021-03-16"
}
b) in case of failure:
{
"error": 101,
"message": "authorization_failed"
}
| Parameter | Description |
|---|---|
| token_api_oauth | SMSAPI token |
| id | Id query |
| phone_number | The number added to the blacklist |
| created_at | Date of being added to the blacklist |
| expire_at | The expiration date of the entry to the blacklist (if "null" it never expires) |
Delete number from Blacklist
This function allows you to remove the number from the blacklist.
DELETE https://api.smsapi.com/blacklist/phone_numbers/{entry_Id}
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.com/blacklist/phone_numbers/entry_Id
<?php
function deleteNumberfromblacklist($token,$Id)
{
$url = "https://api.smsapi.com/blacklist/phone_numbers/".$Id;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
};
$Id = '5BE3F5A53738306F740DB6DB'; //Id of the entry to be removed from the blacklist
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo deleteNumberfromblacklist($token,$Id);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Blacklist\Bag\DeleteBlacklistedPhoneNumberBag;
use Smsapi\Client\Feature\Blacklist\Data\BlacklistedPhoneNumberFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->blacklistFeature()
->deleteBlacklistedPhoneNumber(new DeleteBlacklistedPhoneNumberBag('record_id'));
Clear blacklist
This function allows you to remove all numbers from the blacklist.
DELETE https://api.smsapi.com/blacklist/phone_numbers
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.com/blacklist/phone_numbers
<?php
function deleteAllNumbersFromBlacklist($token)
{
$url = "https://api.smsapi.com/blacklist/phone_numbers";
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
};
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo deleteAllNumbersFromBlacklist($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Blacklist $blacklist */
$blacklist = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->blacklistFeature()
->deleteBlacklistedPhoneNumbers();
12. User accounts administration
User's list
This function allows you to display users.
GET https://api.smsapi.com/subusers
curl -i -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X GET https://api.smsapi.com/subusers
<?php
function getSubusers($token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/subusers');
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo getSubusers($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Data\Subuser;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subuser[] $subusers */
$subusers = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->subusersFeature()
->findSubusers();
var_dump($subusers);
Example response:
a) in case of success:
[{
"id":"5A5359173738303F2F95B7E2",
"username":"subuser1",
"active":true,
"description":null,
"points":{
"from_account":10.0,
"per_month":0.0
}
},
{
"id":"5A5359173738303F2F95B7E2",
"username":"subuser2",
"active":true,
"description":null,
"points":{
"from_account":10.0,
"per_month":0.0
}
}]
b) in case of failure:
{
"error": 123,
"message": "error message"
}
| Parameter | Description |
|---|---|
| id | userid |
| username | User name |
| active | "true" - active, "false" - inactive |
| description | Subuser description |
| from_account | Account balance |
| per_month | Monthly renewable limit |
Adding new sub-user account
This function allow you to add users.
Example request:
curl -i -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X POST -d \
'{"credentials":{"username":"User_name","password":"Smsapi_panel_password","api_password":"api_password"},\
"active":"1","description":"description","points":{"from_account":"2","per_month":"2"}}'\
https://api.smsapi.com/subusers
<?php
function subuserCreate($params, $token)
{
static $content;
$url = 'https://api.smsapi.com/subusers';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$params = array(
'credentials' => array(
'username' => 'Subuser name',
'password' => 'Smsapi_panel_password',
'api_password' => 'api_password'
),
'active' => true,
'description' => "description",
'points' => array(
'from_account' => 2,
'per_month' => 2
)
);
echo subuserCreate($params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Bag\CreateSubuserBag;
use Smsapi\Client\Feature\Subusers\Data\Subuser;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subuser $subuser */
$subuser = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->subusersFeature()
->createSubuser(new CreateSubuserBag('username', 'password'));
var_dump($subuser);
Example response:
a) in case of success:
{
"id":"ABCD1234EFGH9876ABCD1234",
"username":"subuser123",
"active":true,
"description":"new subuser for tests",
"points":
{
"from_account":2.0, //Account balance
"per_month":2.0 //Monthly renewable limit
}
}
b) in case of failure:
{
"message":"Username already exists",
"error":"invalid_domain_logic",
"errors":[
{
"error":"invalid_domain_logic",
"message":"Username already exists"
}]
}
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system. |
| username | New sub-user's name (without main user prefix) |
| password | Sub-user's password hashed with md5 |
| api_password | Sub-user's API password hashed with MD5. |
| from_account | Credit limit granted to the sub-user account |
| per_month | Month limit the amount that will be granted 1st day of every month. |
| active | Activating sub-user's account (available values: 1 – active, 0 – inactive, default value is 0). |
| description | Additional account's description |
Deleting user
This function allows you to delete the subuser with a given ID.
DELETE https://api.smsapi.com/subusers/{subuser_id}
curl -X "DELETE" -H "Authorization: Bearer token_api_oauth" \
https://api.smsapi.com/subusers/{subuser_id}
<?php
function deleteSubuser($token,$userID)
{
$url = "https://api.smsapi.com/subusers/".$userID;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$userID = "{subuser_id}";
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo deleteSubuser($token,$userID);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Bag\DeleteSubuserBag;
use Smsapi\Client\Feature\Subusers\Data\SubuserFactory;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subusers $subusers */
$subusers = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->subusersFeature()
->deleteSubuser(new DeleteSubuserBag('subuser_id'));
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system |
| subuser_id | User id (subuser) |
Editing sub-user account
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Bearer token_api_oauth" -d\
'{"credentials":{"password":"Customer_portal_password","api_password":"API_password"}, \
"active":"1","description":"Test description","points":{"from_account":"2","per_month":"2"}}'
'https://api.smsapi.com/subusers/{subuser_id}'
<?php
function putSubuser($id,$params,$token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/subusers/'.$id);
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$params = array(
'credentials' => array(
'password' => 'password to Customer Portal',
'api_password' => 'API password'
),
'active' => true,
'description' => "test description",
'points' => array(
'from_account' => 2, //Credit limit granted to the sub-user account
'per_month' => 2 //Month limit the amount that will be granted 1st day of every month
)
);
$token = "token_smsapi"; //https://ssl.smsapi.com/react/oauth/manage
$id = "subuser_id"; //subuser ID
echo putSubuser($id, $params, $token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Subusers\Bag\UpdateSubuserBag;
use Smsapi\Client\Feature\Subusers\Data\Subuser;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Subuser $subuser */
$updateSubuserBag = new UpdateSubuserBag('000000000000000000000000');
$updateSubuserBag->active = true;
$subuser = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->subusersFeature()
->updateSubuser($updateSubuserBag);
var_dump($subuser);
Example response:
a) in case of success:
{
"id":"5A8D6E6F373830607C87B277",
"username":"Subuser name",
"active":true,
"description":"Description",
"points":{
"from_account":2,
"per_month":2
}
}
b) in case of failure:
{
"error": 123,
"message": "error message"
}
User's account administration is done by sending HTTP GET or POST request to our system:
GET https://api.smsapi.com/subusersPOST https://api.smsapi.com/subusers
| Parameter | Description |
|---|---|
| subuser_id | Sub-user ID |
| token_api_oauth | OAuth token used to authenticate in our system |
| username | Sub-user's name |
| password | Password to Customer Portal |
| api_password | API password |
| from_account | Credit limit granted to the sub-user account |
| per_month | Month limit the amount that will be granted 1st day of every month |
| active | Activating sub-user's account (available values: 1 – active, 0 – inactive, default value is 0) |
| description | Additional description |
Sharing sender names
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Bearer token_api_oauth" \
-d '{"access":"selected","senders":["sender_name1","sender_name3"]}' \
'https://api.smsapi.com/subusers/{subuser_id}/shares/sendernames'
<?php
function putAccess($id,$params,$token)
{
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/subusers/'.$id.'/shares/sendernames');
curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$id = "subuser_id"; //Subuser id for whom we modify access to the sender names
$params = array(
'access' => "selected", //none | selected | all
'senders' => ["sender_name1","sender_name3"]
);
echo putAccess($id,$params,$token);
?>
Function allows to manage the shared sender names for subuser.
PUT https://api.smsapi.com/subusers/{subuser_id}/shares/sendernames
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system |
| subuser_id | User id (subuser) |
| access | Type of access to the sender names from main account ("none" / "selected" / "all") |
| senders | Table with a list of the sender names to share for the sub-account. Parameter set when parameter access = 'selected' |
13. Sender names
Add sender name
curl -X POST "https://api.smsapi.com/sms/sendernames" \
-H "Authorization: Bearer token_api_oauth" -d "sender=new_sender_name"
<?php
function add_sendername($token, $params)
{
static $content;
$url = 'https://api.smsapi.com/sms/sendernames';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $params);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
$http_status = curl_getinfo($c, CURLINFO_HTTP_CODE);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.pl/react/oauth/manage
$params = array(
'sender' => 'new_sender_name',
);
echo add_sendername($token, $params);
?>
Example response:
a) in case of success:
{
"sender":"new_seder_name",
"is_default":false,
"status":"INACTIVE",
"created_at":"2020-01-01T00:00:00+02:00"
}
HTTP201 code is also returned
b) in case of failure:
{
"message":"Sendername is not valid",
"error":"invalid_sender",
"errors":[
{
"error":"invalid_sender",
"message":"Sendername is not valid"
}]
}
The function of adding sender names requires additional activation. To activate the function, please contact the Customer Service Office.
POST https://api.smsapi.com/sms/sendernames
Adding new sender names is done by sending a request using the POST method.
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system |
| sender | The sender name to be added |
Checking sender name status
The function allows displaying the status of the sender name.
GET https://api.smsapi.com/sms/sendernames/{sender}
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms/sendernames/{sender}
<?php
function getSender($token, $sender)
{
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/sms/sendernames/'.$sender);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$sender = "sender_name";
echo getSender($token, $sender);
?>
Example response:
a) in case of success:
{
"sender":"sender_name",
"is_default":false,
"status":"ACTIVE",
"created_at":"2020-01-01T00:00:00+02:00"
}
b) in case of failure:
{
"message":"Sendername not exists",
"error":"not_found_sendername",
"errors":[
{
"error":"not_found_sendername",
"message":"Sendername not exists"
}]
}
Sender name status check is done by sending HTTP GET request to our system:
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system. |
| {sender} | Sender name that should be checked. |
Checking list of sender names
The function allows displaying the list of sender names.
GET https://api.smsapi.com/sms/sendernames
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms/sendernames"
<?php
function getSenderlist($token)
{
static $content;
$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'https://api.smsapi.com/sms/sendernames');
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo getSenderlist($token);
?>
Example response:
a) in case of success:
{
"collection":[
{
"sender":"sender_name1",
"is_default":false,
"status":"ACTIVE",
"created_at":"2018-09-23T12:00:00+02:00"
},
{
"sender":"sender_name2",
"is_default":true,
"status":"ACTIVE",
"created_at":"2019-05-19T16:00:00+02:00"
},
{
"sender":"sender_name3",
"is_default":false,
"status":"INACTIVE",
"created_at":"2020-01-01T00:30:00+02:00"
}
],
"size":3
}
b) in case of failure:
{
"message":"Authorization failed",
"error":"authorization_failed",
"developer_description":null,
"errors":null
}
Setting default sender name
The function allows setting the default sender name.
POST https://api.smsapi.com/sendernames/{sender}/commands/make_default
curl -H "Authorization: Bearer token_api_oauth" \
-X POST "https://api.smsapi.com/sms/sendernames/{sender}/commands\
/make_default"
<?php
function DefaultSendername($token,$sender)
{
static $content;
$url = 'https://api.smsapi.com/sms/sendernames/'.$sender.'commands/make_default';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
$sender = "sender_name";
echo DefaultSendername($token,$sender);
?>
Example response:
a) in case of success:
Only HTTP204 is returned
b) in case of failure:
{
"message":"Sendername not exists",
"error":"not_found_sendername",
"errors":[
{
"error":"not_found_sendername",
"message":"Sendername not exists"
}
]
}
Default sender name is the name that will be used when parameter &from= is empty or when this parameter is missing. Default sender name has to be active. For setting default sender name parameter &default=sender_name is used, where sender_name is the name that should be set as default.
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system. |
| {sender} | Sender name that should be set as default |
14. Price list
curl -X GET -H "Authorization: Bearer token_api_oauth"\
"https://api.smsapi.com/profile/prices?limit=ALL"
<?php
function getPrices($token)
{
static $content;
$url = 'https://api.smsapi.com/profile/prices?limit=ALL';
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
curl_close($c);
return $content;
}
$token = "token_api_oauth"; //https://ssl.smsapi.com/react/oauth/manage
echo getPrices($token);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Profile;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Profile $profile */
$profile = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->profileFeature()
->findProfilePrices();
var_dump($profile);
Example response:
a) in case of success:
{
"collection":[
{
"type":"sms",
"country":{
"name":"Falkland Islands",
"mcc":750
},
"network":{
"name":"sure (Batelco)",
"mnc":1
},
"changed_at":"2015-06-30",
"price":{
"amount":0.0413,
"currency":"EUR"
}
}
],
"size": 1
}
b) in case of failure:
{
"message":"Error message",
"error":"something_failed",
"developer_description":null,
"errors":null
}
Endpoint profile/prices allows downloading current prices for services on SMSAPI platform.
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token used to authenticate in our system. |
| Response data | Description |
|---|---|
| type | Service type |
| country.name | Country name |
| network.name | Network name |
| country.mcc | Mobile Country Code |
| network.mnc | Mobile Network Code |
| changed_at | Date of the last price change, expressed in UNIX timestamp |
| price.amount | Amount per unit |
| price.currency | Currency of amount |
15. SMS Authenticator
SMS Authenticator is an implementation of one factor, that can be a part Multi-factor authentication (MFA) and allows to make user/client authorization simple. It's realized in two steps. Firstly, shipment of automatic generated authorization code in SMS message. Second, verification that the code typed by the user is valid. Authorization code is valid for 180 seconds.
Messages sent via SMS Authenticator are by default FAST messages (cost 50% more than normal message). If messages are to be sent without the FAST option, the parameter fast = 0 should be added in the request.
Code sending
curl -H "Authorization: Bearer token_api_oauth" \
-H "Content-Type: application/json" -X POST -d\
'{"phone_number":"49500500500","from":"Test","content":"Your code: [%code%]","fast":"1"}'\
https://api.smsapi.com/mfa/codes
<?php
$url = 'https://api.smsapi.com/mfa/codes';
$ch = curl_init($url);
$params = array(
'phone_number' => '49500500500', //recipient phone number
'from' => 'Test', //sendername made in https://ssl.smsapi.com/sms_settings/sendernames
'content' => 'Your code: [%code%]', //content of one message with [%code%] filed (optional parameter)
'fast' => '1' //message type (default fast=1)
);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer token_api_oauth'));
$result = curl_exec($ch);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Mfa;
use Smsapi\Client\Feature\Mfa\Bag\CreateMfaBag;
use Smsapi\Client\Curl\SmsapiHttpClient;
$createMfaBag = new CreateMfaBag('49500500500');
$createMfaBag->from = 'Test';
$createMfaBag->content = 'Your code: [%code%]';
/** @var Mfa $mfa */
$mfa = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->mfaFeature()
->generateMfa($createMfaBag);
var_dump($mfa);
Example Response:
{
"id":"5ADEF4DC3738305BEED02B0C",
"code":"123456",
"phone_number":"49500500500",
"from":"Test"
}
https://api.smsapi.com/mfa/codes- for SSL secured connections
Shipment with authorization code could be made by POST request to API with recipient mobile number as a parameter.
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token generated in SMSAPI Customer Portal |
| phone_number | Mobile number of authorization SMS recipient |
| from | The sender name from which the authorization SMS will be sent. If the from parameter is missing, the message will be sent with the default sender name for the account |
| content | Personalized authorization message with the [%code%] field. If the content parameter is missing, the message will be sent with the default content |
| fast | Setting the priority of the sent message, by default fast=1 with quickest possible time of delivery, costs 50% more than normal message |
The result of a response is json with parameters:
| Parameter | Description |
|---|---|
| id | Event ID |
| code | Authorization code sent to recipient |
| phone_number | Mobile number of authorization SMS recipient |
| from | The sender name from which the authorization SMS was sent |
Checking the validity of the code
curl -H "Authorization: Bearer token_api_oauth"\
-H "Content-Type: application/json" -X POST -i -d\
'{"phone_number":"49500500500","code":"123456"}'\
https://api.smsapi.com/mfa/codes/verifications
<?php
$url = 'https://api.smsapi.com/mfa/codes/verifications';
$ch = curl_init($url);
$params = array(
'phone_number' => '49500500500', // phone number
'code' => '123456' // code to check
);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer token_api_oauth'));
$result = curl_exec($ch);
?>
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use Smsapi\Client\Feature\Mfa;
use Smsapi\Client\Feature\Mfa\Bag\VerificationMfaBag;
use Smsapi\Client\Curl\SmsapiHttpClient;
/** @var Mfa $mfa */
$mfa = (new SmsapiHttpClient())
->smsapiComService('token_api_oauth')
->mfaFeature()
->verifyMfa(new VerificationMfaBag('123456', '49500500500'));
var_dump($mfa);
Example Response:
HTTP/1.1 204
https://api.smsapi.com/mfa/codes/verifications- for SSL secured connections
Verification of authorization code could be made by POST request to API with two parameters, recipient mobile phone number, and authorization code that user typed.
| Parameter | Description |
|---|---|
| token_api_oauth | OAuth token generated in SMSAPI Customer Portal |
| code | Authorization code typed by SMS recipient |
| phone_number | Mobile number of authorization SMS recipient |
The result of a response is HTTP CODE that supported 3 events:
| Status | Description |
|---|---|
| 204 | Valid code |
| 404 | Wrong code |
| 408 | Expired code (valid for 180 seconds) |
16. Special characters
List of special chars that may be changed to normal ones using parameter &normalize:
'normalize_chars' => array(
'Š'=>'S', 'š'=>'s', 'Ś'=>'S', 'ś'=>'s', 'Đ'=>'Dj', 'đ'=>'dj', 'ź'=>'z', 'ż'=>'z','Ź'=>'Z',
'Ż'=>'Z', 'Ž'=>'Z','ž'=>'z', 'Č'=>'C', 'č'=>'c', 'Ć'=>'C', 'ć'=>'c', 'À'=>'A', 'Ą'=>'A',
'Á'=>'A', 'Â'=>'A', 'Ã'=>'A', 'Ä'=>'A', 'Å'=>'A', 'Æ'=>'A', 'Ç'=>'C', 'È'=>'E', 'É'=>'E',
'Ę'=>'E', 'ę'=>'e', 'Ê'=>'E', 'Ë'=>'E', 'Ì'=>'I', 'Í'=>'I','Î'=>'I', 'Ï'=>'I', 'Ñ'=>'N',
'Ò'=>'O', 'Ó'=>'O', 'Ô'=>'O', 'Ł'=>'L', 'ł'=>'l', 'Ń'=>'N', 'ń'=>'n', 'Õ'=>'O','Ö'=>'O',
'Ø'=>'O', 'Ù'=>'U', 'Ú'=>'U', 'Û'=>'U', 'Ü'=>'U', 'Ý'=>'Y', 'þ'=>'B', 'ß'=>'Ss','à'=>'a',
'ą'=>'a','á'=>'a', 'â'=>'a', 'ã'=>'a', 'ä'=>'a', 'å'=>'a', 'æ'=>'a', 'ç'=>'c', 'è'=>'e',
'é'=>'e', 'ê'=>'e', 'ë'=>'e','ì'=>'i', 'í'=>'i', 'î'=>'i', 'ï'=>'i', 'ð'=>'o', 'ñ'=>'n',
'ò'=>'o', 'ó'=>'o', 'ô'=>'o', 'õ'=>'o', 'ö'=>'o','ø'=>'o', 'ù'=>'u', 'ú'=>'u', 'û'=>'u',
'ý'=>'y', 'þ'=>'b', 'ÿ'=>'y', 'Ŕ'=>'R', 'ŕ'=>'r',
}
Special characters are these that don't fulfil regular expression: @£$¥èéùìòÇØøÅå_^{}\[~]|ÆæßÉ!"#¤%&'()*+,-./0- 9:;<=>?A-ZÄÖÑܧ¿a-zäöñüà"enter"
Points charges table:
Without special characters
| Characters amount | Number of parts |
|---|---|
| 160 | 1 part |
| 306 | 2 parts |
| 459 | 3 parts |
| 612 | 4 parts |
| 765 | 5 parts |
| 918 | 6 parts |
With special characters
| Characters amount | Number of parts |
|---|---|
| 70 | 1 part |
| 134 | 2 parts |
| 201 | 3 parts |
| 268 | 4 parts |
| 335 | 5 parts |
| 402 | 6 parts |
17. Delivery statuses
Status list:
| Number | Status | Description |
|---|---|---|
| 401 | NOT_FOUND | Wrong ID or report has expired |
| 402 | EXPIRED | Messages expired. |
| 403 | SENT | Message is sent without a final delivery report. |
| 404 | DELIVERED | Message is delivered to the recipient |
| 405 | UNDELIVERED | Message is undelivered (invalid number, roaming error etc) |
| 406 | FAILED | Sending message failed – please report it to us |
| 407 | REJECTED | Message is undelivered (invalid number, roaming error etc) |
| 408 | UNKNOWN | No report (the message may be either delivered or not) |
| 409 | QUEUE | Message is waiting to be sent |
| 410 | ACCEPTED | Message is delivered to the operator |
| 412 | STOP | Bulk has been stopped by the user. |
18. Error codes
Error codes list:
| ERROR | Description |
|---|---|
| 7 | Short links disabled on account |
| 8 | Error in request (Please report) |
| 11 | The message is too long or there is no message or parameter: nounicode is set and special characters (including Polish characters) are used |
| 12 | The message has more parts than defined in &max_parts parameter. |
| 13 | Lack of valid phone numbers (invalid or blacklisted numbers) |
| 14 | Wrong sender name |
| 17 | FLASH message cannot contain special characters |
| 18 | Invalid number of parameters |
| 19 | Too many messages in one request (number of messages in on request exceeded, when short link is used, limit is 100) |
| 20 | Invalid number of IDX parameters |
| 25 | Parameters &normalize and &datacoding mustn't appear in the same request. |
| 27 | Too long IDX parameter. Maximum 255 chars. |
| 28 | Invalid time_restriction parameter value. Available values are: follow, ignore or nearest_available |
| 30 | Wrong UDH parameter when &datacoding=bin |
| 40 | No group with given name in contacts database |
| 41 | Chosen group is empty |
| 50 | Messages may be scheduled up to 3 months in the future |
| 52 | Too many attempts of sending messages to one number (maximum 10 attempts within 60s) |
| 53 | Not unique idx parameter, message with the same idx has been already sent and &check_idx=1. |
| 54 | Wrong date - (only unix timestamp and ISO 8601) |
| 56 | The difference between date sent and expiration date can't be less than 1 and more than 72 hours. |
| 57 | The number is blacklisted for this user. |
| 59 | Number is added to OptOut list |
| 70 | Invalid URL in notify_url parameter. |
| 74 | Sending date doesn't match date sent restrictions set for the account. |
| 76 | Invalid characters in request parameters |
| 93 | Message parameters and group parameter cannot be used simultaneously. |
| 94 | Not allowed to send messages with link. |
| 96 | Account country volumes restrictions have been reached |
| 98 | Your account is restricted. You can send only to number used in account registration process. |
| 101 | Invalid authorization info |
| 102 | Invalid username or password |
| 103 | Insufficient credits on Your account |
| 104 | No such template |
| 105 | Wrong IP address (for IP filter turned on) |
| 106 | Invalid cut.li link |
| 110 | Action not allowed for your account |
| 112 | Sending messages to phone numbers from this country is restricted on your account |
| 200 | Unsuccessful message submission |
| 201 | System internal error (please report) |
| 202 | Too many simultaneous request, the message won't be sent |
| 203 | Too many requests. Please try again later. Refers to https://api.smsapi.pl/subusers |
| 301 | ID of messages doesn't exist |
| 400 | Invalid message ID of a status response |
| 401 | Token don't have permissions for this action |
| 409 | Value already exists |
| 997 | HTTP requests have been disabled for your account, please use secure connection (HTTPS) |
| 998 | Short url service is unavailable |
| 999 | System internal error (please report) |
| 1000 | Action available only for the main user |
| 1001 | Invalid action (expected one of following parameters: add_user, set_user, get_user, credits) |
| 1010 | Sub-user-s adding error |
| 1020 | Sub-user-s editing error |
| 1021 | No data to edit, at least one parameter has to be edited |
| 1030 | Checking user's data error |
| 1032 | Sub-user doesn't exist for this main user. This error may also occur when trying to get a subuser which does not contain main account username prefix and not using without_prefix parameter. |
| 1100 | Sub-user's data error |
| 1110 | Invalid new sub-user's name |
| 1111 | New sub-user's name is missing |
| 1112 | Too short new sub-user's name, it has to contain minimum 3 characters |
| 1113 | Too long new sub-user's name, sub-user's name with main user's prefix may contain maximum 32 characters |
| 1114 | Not allowed characters occurred in sub-user's name, following are allowed: letters [A – Z], digits [0 – 9] and following others @, -, _ and . |
| 1115 | Another user with the same name exists |
| 1120 | New sub-user's password error |
| 1121 | Password too short |
| 1122 | Password too long |
| 1123 | Password should be hashed with MD5 |
| 1130 | Credit limit error |
| 1131 | Parameter limit ought to be a number |
| 1140 | Month limit error |
| 1141 | Parameter month_limit ought to be a number |
| 1150 | Wrong senders parameter value, binary 0 and 1 values allowed |
| 1160 | Wrong phonebook parameter value, binary 0 and 1 values allowed |
| 1170 | Wrong active parameter value, binary 0 and 1 values allowed |
| 1180 | Parameter info error |
| 1183 | Parameter info is too long |
| 1190 | API password for sub-user's account error |
| 1192 | Wrong API password length (password hashed with MD5 should have 32 chars) |
| 1193 | API password should be hashed with MD5 |
| 2001 | Invalid action (parameter add, status, delete or list expected) |
| 2010 | New sender name adding error |
| 2030 | Sender name's status checking error |
| 2031 | Such sender name doesn't exist |
| 2060 | Default sender name error |
| 2061 | Sender name has to be active for setting it as default |
| 2062 | This sender name is already set as default |
| 2100 | Data error |
| 2110 | Sender name error |
| 2111 | Sender name is missing for adding new sender name action (parameter &add is empty) |
| 2112 | Invalid Sender Name's name (i.e. Name containing special chars or name too long), sender name may contain up to 11 chars, chars allowed: a-z A-Z 0-9 - . [space] |
| 2115 | Sender name already exists |
| 4000 | General contacts database error. |
| 4001 | Action not available for this account. |
| 4002 | Invalid action. |
| 4003 | Invalid parameter usage. |
| 4004 | Too large limit parameter value (i.e. for list_contacts action maximum value is 200). |
| 4100 | General groups' action error. |
| 4101 | Group not found. |
| 4110 | General group's name error. |
| 4111 | Invalid group's name. |
| 4112 | Group's name cannot not be empty. |
| 4113 | Group's name too short (min 2 chars). |
| 4114 | Group's name too long (max 32 chars). |
| 4115 | Forbidden chars appeared in group's name. |
| 4116 | Group already exists. |
| 4121 | Invalid Info field value for groups. |
| 4122 | Too long Info field value for contact (max 200 chars). |
| 4200 | General contact error. |
| 4201 | Contact not found. |
| 4210 | General phone number error. |
| 4211 | Invalid phone number. |
| 4212 | Contact has to contain a phone number. |
| 4213 | Phone number is too short. |
| 4214 | Phone number is too long. |
| 4220 | First name error. |
| 4221 | First name too short (min 2 chars). |
| 4222 | First name too long (max 100 chars). |
| 4230 | Last name error. |
| 4231 | Last name too long (min2 chars). |
| 4232 | Last name too long (max 100 chars). |
| 4240 | Contact Info field error. |
| 4241 | Too long Info field value for contact (max 200 chars). |
| 4250 | E-mail address error for this contact. |
| 4260 | Birthdate error of this contact. |
| 4270 | Group error for this contact. |
| 4271 | Group not found. |
| 4272 | Group name is necessary for group actions. |
| 4280 | Gender error. |
HLR error code list
HLR errors list
| Error | Description |
|---|---|
| UNKNOWN_SUBSCRIBER | Invalid, not active number. Error is permanent. |
| ABSENT_SUBSCRIBER | Number turned off or out of range. Number is considered to be inactive but it may change back to active once it is in range. Error is temporary. |
| TELESERVICE_NOT_PROVISIONED | The recipient has no SMS subscription. Error is permanent. |
| SYSTEM_FAILURE | Temporary network or protocol failure |
| HLR_LOCAL_CANCEL / HLR_ABORT | Temporary problem or lost reach |
| CALL_BARRED | Barring of the recipient's number. Error is permanent. |
19. 7-bit GSM alphabet
This is the 7 bit default alphabet as specified by GSM 03.38.
All chars outside this charset are considered to be special chars and cause shortening single message from 160 chars to 70 chars. Using only chars from this list won't shorten the message.
Notice that characters ^ { } [ ] \ ~ | [enter] € are counted double when sending message without special chars because of GSM specification requirements.
| Character | Character name | HEX | DEC |
|---|---|---|---|
| @ | COMMERCIAL AT | 0x00 | 0 |
| £ | POUND SIGN | 0x01 | 1 |
| $ | DOLLAR SIGN | 0x02 | 2 |
| ¥ | YEN SIGN | 0x03 | 3 |
| è | LATIN SMALL LETTER E WITH GRAVE | 0x04 | 4 |
| é | LATIN SMALL LETTER E WITH ACUTE | 0x05 | 5 |
| ù | LATIN SMALL LETTER U WITH GRAVE | 0x06 | 6 |
| ì | LATIN SMALL LETTER I WITH GRAVE | 0x07 | 7 |
| ò | LATIN SMALL LETTER O WITH GRAVE | 0x08 | 8 |
| Ç | LATIN CAPITAL LETTER C WITH CEDILLA | 0x09 | 9 |
| LINE FEED | 0x0A | 10 | |
| Ø | LATIN CAPITAL LETTER O WITH STROKE | 0x0B | 11 |
| ø | LATIN SMALL LETTER O WITH STROKE | 0x0C | 12 |
| CARRIAGE RETURN | 0x0D | 13 | |
| Å | LATIN CAPITAL LETTER A WITH RING ABOVE | 0x0E | 14 |
| å | LATIN SMALL LETTER A WITH RING ABOVE | 0x0F | 15 |
| Δ | GREEK CAPITAL LETTER DELTA | 0x10 | 16 |
| _ | LOW LINE | 0x11 | 17 |
| Φ | GREEK CAPITAL LETTER PHI | 0x12 | 18 |
| Γ | GREEK CAPITAL LETTER GAMMA | 0x13 | 19 |
| Λ | GREEK CAPITAL LETTER LAMBDA | 0x14 | 20 |
| Ω | GREEK CAPITAL LETTER OMEGA | 0x15 | 21 |
| Π | GREEK CAPITAL LETTER PI | 0x16 | 22 |
| Ψ | GREEK CAPITAL LETTER PSI | 0x17 | 23 |
| Σ | GREEK CAPITAL LETTER SIGMA | 0x18 | 24 |
| Θ | GREEK CAPITAL LETTER THETA | 0x19 | 25 |
| Ξ | GREEK CAPITAL LETTER XI | 0x1A | 26 |
| ESCAPE TO EXTENSION TABLE | 0x1B | 27 | |
| FORM FEED | 0x1B0A | 27 10 | |
| ^ | CIRCUMFLEX ACCENT | 0x1B14 | 27 20 |
| { | LEFT CURLY BRACKET | 0x1B28 | 27 40 |
| } | RIGHT CURLY BRACKET | 0x1B29 | 27 41 |
| '\' | REVERSE SOLIDUS (BACKSLASH) | 0x1B2F | 27 47 |
| [ | LEFT SQUARE BRACKET | 0x1B3C | 27 60 |
| ~ | TILDE | 0x1B3D | 27 61 |
| ] | RIGHT SQUARE BRACKET | 0x1B3E | 27 62 |
| VERTICAL BAR | 0x1B40 | 27 64 | |
| € | EURO SIGN | 0x1B65 | 27 101 |
| Æ | LATIN CAPITAL LETTER AE | 0x1C | 28 |
| æ | LATIN SMALL LETTER AE | 0x1D | 29 |
| ß | LATIN SMALL LETTER SHARP S (German) | 0x1E | 30 |
| É | LATIN CAPITAL LETTER E WITH ACUTE | 0x1F | 31 |
| SPACE | 0x20 | 32 | |
| ! | EXCLAMATION MARK | 0x21 | 33 |
| \" | QUOTATION MARK | 0x22 | 34 |
| # | NUMBER SIGN | 0x23 | 35 |
| ¤ | CURRENCY SIGN | 0x24 | 36 |
| % | PERCENT SIGN | 0x25 | 37 |
| & | AMPERSAND | 0x26 | 38 |
| ' | APOSTROPHE | 0x27 | 39 |
| ( | LEFT PARENTHESIS | 0x28 | 40 |
| ) | RIGHT PARENTHESIS | 0x29 | 41 |
| * | ASTERISK | 0x2A | 42 |
| + | PLUS SIGN | 0x2B | 43 |
| , | COMMA | 0x2C | 44 |
| - | HYPHEN-MINUS | 0x2D | 45 |
| . | FULL STOP | 0x2E | 46 |
| / | SOLIDUS (SLASH) | 0x2F | 47 |
| 0 | DIGIT ZERO | 0x30 | 48 |
| 1 | DIGIT ONE | 0x31 | 49 |
| 2 | DIGIT TWO | 0x32 | 50 |
| 3 | DIGIT THREE | 0x33 | 51 |
| 4 | DIGIT FOUR | 0x34 | 52 |
| 5 | DIGIT FIVE | 0x35 | 53 |
| 6 | DIGIT SIX | 0x36 | 54 |
| 7 | DIGIT SEVEN | 0x37 | 55 |
| 8 | DIGIT EIGHT | 0x38 | 56 |
| 9 | DIGIT NINE | 0x39 | 57 |
| : | COLON | 0x3A | 58 |
| ; | SEMICOLON | 0x3B | 59 |
| < | LESS-THAN SIGN | 0x3C | 60 |
| = | EQUALS SIGN | 0x3D | 61 |
| > | GREATER-THAN SIGN | 0x3E | 62 |
| ? | QUESTION MARK | 0x3F | 63 |
| ¡ | INVERTED EXCLAMATION MARK | 0x40 | 64 |
| A | LATIN CAPITAL LETTER A | 0x41 | 65 |
| B | LATIN CAPITAL LETTER B | 0x42 | 66 |
| C | LATIN CAPITAL LETTER C | 0x43 | 67 |
| D | LATIN CAPITAL LETTER D | 0x44 | 68 |
| E | LATIN CAPITAL LETTER E | 0x45 | 69 |
| F | LATIN CAPITAL LETTER F | 0x46 | 70 |
| G | LATIN CAPITAL LETTER G | 0x47 | 71 |
| H | LATIN CAPITAL LETTER H | 0x48 | 72 |
| I | LATIN CAPITAL LETTER I | 0x49 | 73 |
| J | LATIN CAPITAL LETTER J | 0x4A | 74 |
| K | LATIN CAPITAL LETTER K | 0x4B | 75 |
| L | LATIN CAPITAL LETTER L | 0x4C | 76 |
| M | LATIN CAPITAL LETTER M | 0x4D | 77 |
| N | LATIN CAPITAL LETTER N | 0x4E | 78 |
| O | LATIN CAPITAL LETTER O | 0x4F | 79 |
| P | LATIN CAPITAL LETTER P | 0x50 | 80 |
| Q | LATIN CAPITAL LETTER Q | 0x51 | 81 |
| R | LATIN CAPITAL LETTER R | 0x52 | 82 |
| S | LATIN CAPITAL LETTER S | 0x53 | 83 |
| T | LATIN CAPITAL LETTER T | 0x54 | 84 |
| U | LATIN CAPITAL LETTER U | 0x55 | 85 |
| V | LATIN CAPITAL LETTER V | 0x56 | 86 |
| W | LATIN CAPITAL LETTER W | 0x57 | 87 |
| X | LATIN CAPITAL LETTER X | 0x58 | 88 |
| Y | LATIN CAPITAL LETTER Y | 0x59 | 89 |
| Z | LATIN CAPITAL LETTER Z | 0x5A | 90 |
| Ä | LATIN CAPITAL LETTER A WITH DIAERESIS | 0x5B | 91 |
| Ö | LATIN CAPITAL LETTER O WITH DIAERESIS | 0x5C | 92 |
| Ñ | LATIN CAPITAL LETTER N WITH TILDE | 0x5D | 93 |
| Ü | LATIN CAPITAL LETTER U WITH DIAERESIS | 0x5E | 94 |
| § | SECTION SIGN | 0x5F | 95 |
| ¿ | INVERTED QUESTION MARK | 0x60 | 96 |
| a | LATIN SMALL LETTER A | 0x61 | 97 |
| b | LATIN SMALL LETTER B | 0x62 | 98 |
| c | LATIN SMALL LETTER C | 0x63 | 99 |
| d | LATIN SMALL LETTER D | 0x64 | 100 |
| e | LATIN SMALL LETTER E | 0x65 | 101 |
| f | LATIN SMALL LETTER F | 0x66 | 102 |
| g | LATIN SMALL LETTER G | 0x67 | 103 |
| h | LATIN SMALL LETTER H | 0x68 | 104 |
| i | LATIN SMALL LETTER I | 0x69 | 105 |
| j | LATIN SMALL LETTER J | 0x6A | 106 |
| k | LATIN SMALL LETTER K | 0x6B | 107 |
| l | LATIN SMALL LETTER L | 0x6C | 108 |
| m | LATIN SMALL LETTER M | 0x6D | 109 |
| n | LATIN SMALL LETTER N | 0x6E | 110 |
| o | LATIN SMALL LETTER O | 0x6F | 111 |
| p | LATIN SMALL LETTER P | 0x70 | 112 |
| q | LATIN SMALL LETTER Q | 0x71 | 113 |
| r | LATIN SMALL LETTER R | 0x72 | 114 |
| s | LATIN SMALL LETTER S | 0x73 | 115 |
| t | LATIN SMALL LETTER T | 0x74 | 116 |
| u | LATIN SMALL LETTER U | 0x75 | 117 |
| v | LATIN SMALL LETTER V | 0x76 | 118 |
| w | LATIN SMALL LETTER W | 0x77 | 119 |
| x | LATIN SMALL LETTER X | 0x78 | 120 |
| y | LATIN SMALL LETTER Y | 0x79 | 121 |
| z | LATIN SMALL LETTER Z | 0x7A | 122 |
| ä | LATIN SMALL LETTER A WITH DIAERESIS | 0x7B | 123 |
| ö | LATIN SMALL LETTER O WITH DIAERESIS | 0x7C | 124 |
| ñ | LATIN SMALL LETTER N WITH TILDE | 0x7D | 125 |
| ü | LATIN SMALL LETTER U WITH DIAERESIS | 0x7E | 126 |
| à | LATIN SMALL LETTER A WITH GRAVE | 0x7F | 127 |
Number of characters per message:
| Parts | Without special chars | With special chars |
|---|---|---|
| 1 part | 160 chars | 70 chars |
| 2 parts | 306 chars | 134 chars |
| 3 parts | 459 chars | 201 chars |
| 4 parts | 612 chars | 268 chars |
| 5 parts | 765 chars | 335 chars |
| 6 parts | 918 chars | 402 chars |
| 7 parts | 1071 chars | 469 chars |
| 8 parts | 1224 chars | 536 chars |
| 9 parts | 1377 chars | 603 chars |
| 10 parts | 1530 chars | 670 chars |
20. Encoding
Example:
curl -H "Authorization: Bearer token_api_oauth" \
"https://api.smsapi.com/sms.do?\
from=sender_name&\
to=44123456789&\
encoding=utf-8&\
message=message_content"
Default encoding is utf-8. However, you can set different encoding of messages by additional parameter &encoding in your HTTP request. Available encoding types are:
- iso-8859-1
- iso-8859-2
- iso-8859-3
- iso-8859-4
- iso-8859-5
- iso-8859-6
- iso-8859-7
- windows-1250
- windows-1251
- utf-8
21. Integrations
E-commerce sector is using more often potential of mobile communications, especially that it translates into both introductions of savings and support of sales. You can always browse complete list of our Integrations.
Gmail
Gmail is a free, email service provided by Google. The Gmail user interface is user-friendly with its focus on search and conversation threading of emails, grouping several messages between two or more people onto a single page. Integration with SMSAPI allows setting automatic SMS notifications about received e-mails.
Gmail configuration
Script monitors messages by their labels. To set automatic label assignment, you'll need to login to your Gmail account, then click the gear icon and go to settings.
In the settings, go to Filters and Blocked Addresses tab and choose the option to create a new filter.
In the next step, you must specify parameters that proper label will be assigned for.
Select option Apply the label, then create new or select one from the list.
Script configuration
function SMSapi() {
// Configuration
/*******************************************************/
var MAIL_LABEL = 'SMSAPI'; // label name (in Gmail) that notifications are going to be sent for
var SMSAPI_TOKEN = 'token_api_oauth';
var SMSAPI_SENDERNAME = 'Test'; // sender name made in https://ssl.smsapi.com/sms_settings/sendernames
var SMSAPI_RECIVER = 'tel_number'; // recipient phone number
var MESSAGE = 'New email from: :SENDER, topic: :TITLE'; // sms content with extra parameters :SENDER, :TITLE
/*******************************************************/
var threads = GmailApp.getUserLabelByName(MAIL_LABEL).getThreads();
for(i in threads)
UrlFetchApp.fetch('https://api.smsapi.com/sms.do?encoding=utf-8&access_token='+SMSAPI_TOKEN+'&from='+SMSAPI_SENDERNAME+'&to='+encodeURIComponent(SMSAPI_RECIVER)+"&message="+encodeURIComponent(MESSAGE.replace(':SENDER',threads[i].getMessages()[0].getFrom()).replace(':TITLE', threads[i].getMessages()[0].getSubject())));
GmailApp.getUserLabelByName(MAIL_LABEL).removeFromThreads(threads);
}
For proper script working, all variables listed below should be filled:
* MAIL_LABEL – name of monitored, previously set Gmail label
* SMSAPI_TOKEN - your token in SMSAPI service
* SMSAPI_SENDERNAME – sender name made in https://ssl.smsapi.com/sms_settings/sendernames
* SMSAPI_RECIVER – recipient phone number
* MESSAGE – message content
In order to configure SMSAPI service in Google Mail, make sure if you're logged into the proper account in Google service. Then go to https://script.google.com
Click "Start Scripting" and then "Blank Project"
To set script executing frequency, click 
icon and add new trigger
While saving, system can ask you for permission in order to get the script working.
Google Calendar
function SmsApiCalendar()
{
/* Configuration */
var SMSAPI_TOKEN = 'token_api_oauth';
var SMSAPI_RECEIVER = '48XXXXXXXXX';
var SMSAPI_SENDERNAME = 'Test'; // sender name made in https://ssl.smsapi.com/sms_settings/sendernames
var SMSAPI_URL = 'https://api.smsapi.com/sms.do?';
var HOURS = 0;
var MINUTES = 30;
var MESSAGE = 'GOOGLE Calendar: Coming events: :TITLE that begin :TIME';
/****************/
SMSAPI_URL += 'access_token='+SMSAPI_TOKEN;
SMSAPI_URL += '&from='+SMSAPI_SENDERNAME;
SMSAPI_URL += '&to='+encodeURIComponent(SMSAPI_RECEIVER);
var period = (HOURS * 3600000) + (MINUTES * 60000);
var now = new Date();
var periodFromNow = new Date(now.getTime() + period);
var calendar = CalendarApp.getDefaultCalendar(); // for default Calendar
//or
// var calendar = CalendarApp.getCalendarsByNAme('Calendar name') for specific calendar
var events = calendar.getEvents(now, periodFromNow);
for (var i in events) {
var event = events[i];
var has_smsapi_status = false;
var tag_keys = event.getAllTagKeys();
for (var k = 0; k < tag_keys.length; ++k) {
if (tag_keys[k] === 'smsapi_status') {
has_smsapi_status = true;
break;
}
}
if (has_smsapi_status) {
if (event.getTag('smsapi_status') === 'ok') {
continue;
}
}
var idx = event.getId();
var message = MESSAGE.replace(':TITLE', event.getTitle()).replace(':TIME', event.getStartTime());
var url = SMSAPI_URL+"&encoding=utf8&message="+encodeURIComponent(message)+"&check_idx=1&idx="+encodeURIComponent(idx);
UrlFetchApp.fetch(url);
event.setTag('smsapi_status', 'ok');
}
}
It's required to enter values of variables:
* 'SMSAPI_TOKEN' - your token in SMSAPI service
* 'SMSAPI_RECIVER' - mobile phone number SMS notification will be sent to
* 'SMSAPI_SENDERNAME' - free-registered SMS notification sender name
* 'HOURS' - defines in hours how long before the event SMS notification should be sent
* 'MINUTES' - defines in minutes how long before the event SMS notification should be sent
* 'MESSAGE' - content of SMS notification
* ':TITLE' - replace event name
* ':TIME' replace event date
Google Calendar is a time-management web application and mobile app created by Google. It became available on April 13, 2006. Integrating with SMSAPI allows to configuring automatic SMS notifications about upcoming events.
In order to work properly, the script should be given appropriate permissions. The script retrieves information about dates and names of the events directly from Google Calendar. Then properly prepared references to our API are performed, which results in sending SMS notification.
To configure SMSAPI service make sure that you are logged into desired Google account. After that go to address https://script.google.com/
Click "Start Scripting" and then "Blank Project"
Changing script name from 'Code.gs' to 'SmsApiCalendar.gs' is unnecessary.
To set the script to execute frequency choose 'Current project's triggers' then 'No triggers set up. Click here to add one now' and change settings on 'Minutes timer' and 'Every minute'.
Script needs some permissions in order to work properly. Script gets info about title and date of event. Then it constructs proper request to API that result in SMS notifications.
Zapier
Zapier lets you connect APP to hundreds of other web services. Automated connections called Zaps, set up in minutes with no coding, can automate your day-to-day tasks and build workflows between apps that otherwise wouldn't be possible.
Each Zap has one app as the Trigger, where your information comes from and which causes one or more Actions in other apps, where your data gets sent automatically.
Getting Started with Zapier
Sign up for a free Zapier account, from there you can jump right in. To help you hit the ground running, there are some popular pre-made Zaps.
How do I connect APP to Zapier?
Log in to your Zapier account or create a new account. Navigate to "Connected Accounts" from the top menu bar. Now click on "Connect new account" and search for "APP" Use your credentials to connect your APP account to Zapier. Once that's done you can start creating an automation! Use a pre-made Zap or create your own with the Zap Editor. Creating a Zap requires no coding knowledge and you'll be walked step-by-step through the setup. Need inspiration? See everything that's possible with SMSAPI and Zapier.
OAuth2 webflow
OAuth - an authorization method that enables the integration of external applications with SMSAPI. Before starting the integration process, please contact us at support@smsapi.com to assign client_id and client_secret.
GET https://ssl.smsapi.com/oauth/access/
Example of first request (the user is redirected to SMSAPI, where they log in and confirm the integration):
https://ssl.smsapi.com/oauth/access?client_id=123456&redirect_uri=https://www.sample.com/&scope=sms
Example response:
https://www.sample.com/?code=11112222
In the first step, the user is redirected to SMSAPI Customer Portal, where they log in and confirm the integration. After successful authorization, the user is redirected to the page specified in redirect_uri and receives the code, which is required for the second step.
Required parameters:
| Parameter | Description |
|---|---|
| client_id | Unique ID for app |
| redirect_uri | URL address to which the user will be redirected after completing the authorization |
| scope | Defined permission for resources |
| state | Optional parameter that contains your CSRF token |
Available scope parameters:
| Parameter | Description |
|---|---|
| sms | Access to SMS |
| sms_sender | Access to managing sender names |
| hlr | Access to HLR |
| contacts | Access to contacts database |
| subuser | Access to managing subusers |
| blacklist | Access to managing blacklist |
| mfa | Access to MFA |
| callback | Access to managing callbacks |
| short_url | Access to managing short links |
| profile | Access to managing user profile |
-
POST https://api.smsapi.com/oauth/token
After receiving a positive verification in the first request, send client_secret, code and parameters from step 1 using the POST method to complete the authorization process. You can use the received access_token to authorize your SMSAPI requests.
Example of second request:
curl -X POST "https://api.smsapi.com/oauth/token" -d "client_id=1112223334444\
&client_secret=111222333444&code=11112222&grant_type=authorization_code\
&redirect_uri=https://www.sample.com/"
Example response:
{
"access_token":"A1b***x2Z",
"token_type":"Bearer",
"expires":1577836800,
"expires_in":604800,
"refresh_token":"c3D*************************4eF"
}
* access_token – token that allows access to resources via API
* token_type – token type (always bearer for SMSAPI)
* expires – token expiration date in UNIX timestamp
* expires_in – time of token validity (days, hours and minutes)
* refresh_token – refresh token that allows to extend the authorization validity
Required parameters:
| Parameter | Description |
|---|---|
| client_id | Unique ID for app |
| client_secret | Private value unique for app |
| code | Authorization code given by SMSAPI after the first request |
| grant_type | Authorization type, should be set to "authorization_code" |
| redirect_uri | URL address where the response about successful authorization should be redirected |
-
POST https://api.smsapi.com/oauth/token
To maintain the connection, send a request containing the refresh_token received in the second request. For subsequent requests, replace access_token and refresh_token values with the new ones received in this request.
Example of request with refresh_token:
curl -X POST "https://api.smsapi.com/oauth/token" -d "client_id=123456\
&client_secret=111222333444&refresh_token=AaaaaBbbbbCccccDdddd\
&grant_type=refresh_token"
Example response:
{
"access_token":"BD1***p3k",
"token_type":"Bearer",
"expires":1577837800,
"expires_in":604800,
"refresh_token":"yn3*************************z54"
}
Required parameters:
| Parameter | Description |
|---|---|
| client_id | Unique ID for app |
| client_secret | Private value unique for app |
| refresh_token | Token received in the second request |
| grant_type | Authorization type, should be set to "refresh_token" |
PKCE
SMSAPI also supports authorization using PKCE (Proof Key for Code Exchange). It differs from standard OAuth authorization in that a random string code_verifier must be generated to perform it. In the first step, a converted version of this string must be provided under the name code_challenge, and in the second step the code_verifier must be sent. The client_secret parameter sent in the second step is optional.
You can create the code_challenge parameter by Base64 URL encoding the SHA256 hash of the code_verifier. You can perform Base64 URL encoding by taking a Base64-encoded string and changing '+' and '/' to '-' and '_' respectively, then trimming the trailing '='.
GET https://ssl.smsapi.com/oauth/access/
Example of first request (the user is redirected to SMSAPI, where they log in and confirm the integration):
https://ssl.smsapi.com/oauth/access?client_id=123456&redirect_uri=https://www.sample.com/&code_challenge=12345678&code_challenge_method=S256&scope=sms
Example response:
https://www.sample.com/?code=11112222
Required parameters:
| Parameter | Description |
|---|---|
| client_id | Unique ID for app |
| redirect_uri | URL address to which the user will be redirected after completing the authorization |
| code_challenge | Parameter generated as described above |
| code_challenge_method | code_challenge generation method, has to be equal to S256 |
| scope | Defined permission for resources |
| state | Optional parameter that contains your CSRF token |
-
POST https://api.smsapi.com/oauth/token
Example of second request:
curl -X POST "https://api.smsapi.com/oauth/token" -d "client_id=1112223334444\
&code_verifier=111222333444&code=11112222&grant_type=authorization_code\
&redirect_uri=https://www.sample.com/"
Example response:
{
"access_token":"A1b***x2Z",
"token_type":"Bearer",
"expires":1577836800,
"expires_in":604800,
"refresh_token":"c3D*************************4eF"
}
* access_token – token that allows access to resources via API
* token_type – token type (always bearer for SMSAPI)
* expires – token expiration date in UNIX timestamp
* expires_in – time of token validity (days, hours and minutes)
* refresh_token – refresh token that allows to extend the authorization validity
After receiving a positive verification in the first request, send the information using the POST method to complete the authorization process. You can use the received access_token to authorize your SMSAPI requests.
Required parameters:
| Parameter | Description |
|---|---|
| client_id | Unique ID for app |
| code | Authorization code given by SMSAPI after the first request |
| grant_type | Authorization type, should be set to "authorization_code" |
| redirect_uri | URL address where the response about successful authorization should be redirected |
| client_secret | Optional parameter - private value unique for app |
-
POST https://api.smsapi.com/oauth/token
To maintain the connection, send a request containing the refresh_token received in the second request. For subsequent requests, replace access_token and refresh_token values with the new ones received in this request.
Example of request with refresh_token:
curl -X POST "https://api.smsapi.com/oauth/token" -H "client_id=123456\
&refresh_token=AaaaaBbbbbCccccDdddd&grant_type=refresh_token"
Example response:
{
"access_token":"BD1***p3k",
"token_type":"Bearer",
"expires":1577837800,
"expires_in":604800,
"refresh_token":"yn3*************************z54"
}
Required parameters:
| Parameter | Description |
|---|---|
| client_id | Unique ID for app |
| refresh_token | Token received in the second request |
| grant_type | Authorization type, should be set to "refresh_token" |
Other integrations
We also have integrations with:
- Magento
- WordPress
You can check them all out at our Integrations page.