Get started easily with Beepsend API. Here is a complete list of our public end points. Feel free to give us feedback on @beepsend or on IRC #beepsend@freenode
| Item | Value |
|---|---|
| Host | api.beepsend.com |
| Port | 80 or 443 |
| Protocol | HTTP or HTTPS |
| Authentication | User Token OR Connection Token |
| Administrator Page | https://connect.beepsend.com |
Before you begin using Beepsends API you need to know the difference between a User and a Connection.
You are a user. At your disposal you have one or more connections to send SMS or do HLR lookups. Connections are in other services sometimes referred to as "Application-token".
As a user you can perform administrative tasks like transferring funds between your connections or get accumulated statistics. Using a connection you can send SMS and HLR requests.
I've just signed up. I have a username and password. What now?
Log in to the Beepsend Customer Portal and grap your API tokens used to authenticate against the API. Please note that Connection-token is limited in functionality and works best for production. The customer portal also showcases everything you can do using the RESTful API as it is 100% built using only these public API endpoints.
So do I send messages with a connection or a user?
Technically a connection is always what is used for sending a message. A connection means a price lists and you can have several connections with different quality and price. When you send a message as a user your user-account is linked to a connection.
Can I send SMS/HLR with a user API Token?
Yes, one of your connections will always be the default connection. When doing tasks that require a connection your default connection will be chosen automatically.
If you intend to use the data you receive in a web application, it's a good idea to sanitize the data before. This is to prevent XSS attacks.
If you do not wish to do sanitize the data on your own, all of our endpoints that return data have the option to sanitize it for you before sending.
In your query string, set _escape to true.
GET /2/users/me?_escape=trueExample data from the Users endpoint.
{
"id": 123,
"name": "Åke Ärlig Östen",
"email": "thejanitor@beepsend.com",
"phone": "46406007500",
"customer": "Beepsend AB",
"api_token": "abc123",
"default_connection": {
"id": 142,
"label": "<script type=\"text/javascript\">XSS här</script>",
"system_id": "beepbeep",
"type": 1
},
"user_types": [
{
"id": 1,
"name": "Technical Contact"
}
],
"max_level": 2,
"verified": {
"email": true,
"phone": false,
"terms": true
}
}
{
"id": 123,
"name": "Åke Ärlig Östen",
"email": "thejanitor@beepsend.com",
"phone": "46406007500",
"customer": "Beepsend AB",
"api_token": "abc123",
"default_connection": {
"id": 142,
"label": "<script type="text/javascript">XSS här</script>",
"system_id": "beepbeep",
"type": 1
},
"user_types": [
{
"id": 1,
"name": "Technical Contact"
}
],
"max_level": 2,
"verified": {
"email": true,
"phone": false,
"terms": true
}
}
This library is available via Composer. This is the recommended installation method.
To install with Composer, create composer.json in your project root and add the following.
{
"require": {
"beepsend/php-sdk": "dev-master"
}
}
To install, run:
php composer.phar install
Once you have installed the library, you will need to load Composer's autoloader (which registers all the required namespaces):
require_once __DIR__ . '/vendor/autoload.php';
Please note that the examples all expect you to have used the Composer method. If not you need to substitute the autoload.php with your own import in the php-code.
Use git to clone the repository:
git clone https://github.com/beepsend/beepsend-php.git
Or download the repository as a zip file.
Installation of this library is available trough Bower package manager.
bower install beepsend-javascript --save
Or you can clone it with git from our repository
git clone https://github.com/beepsend/beepsend-javascript.git
Or download the repository as a zip file.
After that you need to include the Beepsend Javascript library to your project:
<script type="text/javascript" src="src/beepsend.js"></script>
And you're ready to go!
API access is granted by the use of Tokens.
Each request must be accompanied by a Token. The Token grants you privileges to end points on Connection- or User level.
To find your API token, visit the Beepsend Customer Portal or contact your account manager.
There are two ways to authenticate yourself using the Beepsend API.
Add your API token as a parameter in the query string and append to the URL you are trying to reach.
Parameter: api_token
Example
/2/connections/me?api_token=abc123
If you prefer keeping the URL untouched, you can use an HTTP header in your request instead.
In your request, add the Authorization HTTP header with your API token as value.
Authorization: Token abc123
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me"
curl "https://api.beepsend.com/2/connections/me?api_token=abc123"
$client = new Client({API_TOKEN});
For authentication you need to provide valid API token in library constructor.
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
For authentication you need to set valid API token. In your main project .plist file you must add API token value for key "BeepSendToken".
This endpoint requres a valid User API-Token. Read more about Users and Connections.
As a user you belong to a customer. A customer is where your address, pay and pricelist information is stored.
GET /2/customer/{
"id": 1,
"phone": "46406007500",
"name": "Beepsend AB",
"address": "Gustav Adolfs Torg 12",
"city": "Malmö",
"post_box": "21139",
"country": "Sweden",
"vat": "",
"email": "beepsend@beepsend.se",
"invoice_type": "pre-pay",
"account_manager": {
"name": "Account Manager",
"email": "account.manager@beepsend.se"
},
"pricelist_type": 1,
"pricelist_delimiter": null,
"pricelist_schedule": {
"id": 1,
"name": "Immediately"
},
"pricelist_fields": [],
"trial": false
}
| Key | Type | Description |
|---|---|---|
| id | int | ID. |
| phone | string | Phone number. |
| name | string | name. |
| address | string | Street address. |
| city | string | City. |
| post_box | string | Post code. |
| country | string | Country. |
| vat | string | VAT number. |
| string | Email. | |
| invoice_type | string | pre-pay or post-pay. |
| account_manager.name | string | Name of customer account manager. |
| account_manager.email | string | Email of customer account manager. |
| pricelist_type | int | 1 for json, 2 for csv. |
| pricelist_delimiter | string \ null | Delimiter that is being used if pricelist_type is csv. If pricelist_type is json this will be null. |
| pricelist_schedule.id | int | Pricelist sendout schedule ID. |
| pricelist_schedule.name | string | Pricelist sendout schedule name. How often new pricelist updates should be mailed out. |
| pricelist_fields | array | Pricelist fields to be included. |
| trial | boolean | Indicates whether customer is in trial mode |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/customer/"
$client->customer->get();
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$customer = $client->customer->get();
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.customer().get().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.customer().get().then(
function(customer) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getCustomerDetailsOnCompletion:(void(^)(BSCustomer *customer, NSArray *errors))block;
@end
[[BSUser currentUser] getCustomerDetailsOnCompletion:^(BSCustomer *customer, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSCustomer object)
}
else {
//Handle error (array of BSError objects)
}
}];
If authenticated using a Connection token only one connect object is accessible. If authenticated using a User token there can be one or several connections accessible. Each User normally has a default connection specified unless no connection ID is specified.
To fetch a list of all available connections and their corresponding information.
GET /2/connections/For both Connection and User tokens a short-hand tag is available which serves as alias for the connection ID. The label is called "me".
Receive the connection object for given API-token.
GET /2/connections/me[
{
"id": 1,
"system_id": "beepsend",
"label": "beepsend-connection",
"api_token": "abc123",
"callbacks": {
"dlr": "http://beepsend.com/dlr",
"mo": "https://beepsend.com/mocallback",
"method": "PUT"
},
"users": [
{
"username": "beepsend-user",
"name": "Beep Beepson",
"id": 1
}
],
"wallet": {
"balance": 5028.14758,
"name": "Beepsend wallet",
"id": 1
},
"customer": "Beepsend AB",
"description": "",
"type": 1,
"whitelist": [
"127.0.0.1",
"10.11.12.13",
"172.16.0.36",
"192.168.1.170"
],
"tlv_for_mcc_mnc": 0
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique connection ID. |
| system_id | string | Login name. |
| label | string | Connection label. |
| api_token | string | API Token belonging to this connection. |
| callbacks.dlr | string | Connection DLR Callback URL. |
| callbacks.mo | string | Connection Mo Callback URL. |
| callbacks.method | string | HTTP method used for connection callbacks. |
| users | array | List of users with read-write access to this connection. |
| users.username | string | Username. |
| users.name | string | Name of user. |
| users.id | int | Unique user ID. |
| wallet.balance | float | Current credit balance in Euro (€). |
| wallet.name | string | The name of this wallet. |
| wallet.id | int | Unique wallet ID. |
| customer | string | Customer name. |
| description | string | (Optional) Description of this connection. |
| type | int | Type of connection, 1 for SMS connection or 2 for HLR connection. |
| whitelist | list | List of ip addresses that have been whitelisted to use this connection. |
| tlv_for_mcc_mnc | int | Tag-Length-Value field for returning mcc and mnc in DLR. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/"
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me"
$client->connection->get({CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
/* Get all connections */
$connections = $client->connection->all();
/* Get connection for given API-token */
$connection = $client->connection->get();
/* Get specific connection by id */
$connectionId = 1;
$connection = $client->connection->get($connectionId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.connection().all().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.connection().get({CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
/* In case that you want to get all connection connected to this account, you can use this library method. */
client.connection().all().then(
function(allConnections) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
/* This method returns collection of all connection connected to this account. */
/* Or if you want to fetch data about specific connection you can use this library method. In get method we can provide connection id or we can call it without connection id, in case that you havent provide connection id, we will return data of default connection */
/* connectionId - is id of connection that we want to get or you can pass null if you want to get default connection object */
var connection = 1;
client.connection().get(connection).then(
function(connection) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
//If you are using user API token
@interface BSUser
@property (nonatomic, strong) BSConnection *defaultConnection;
- (void)getAvailableConnectionsOnCompletion:(void(^)(NSArray *connections, NSArray *errors))block;
@end
//If you are using connection API token you can access connection directly
@interface BSConnection
+ (BSConnection *)currentConnection;
@end
Get users default connection:
BSConnection *connection = [[BSUser currentUser] defaultConnection];
Get all connections associated with account:
[[BSUser currentUser] getAvailableConnectionsOnCompletion:^(NSArray *connections, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSConnection objects)
}
else {
//Handle error (array of BSError objects)
}
}];
If using connection API token you can access only default connection
BSConnection *connection = [BSConnection currentConnection];
Any property of the connection object can be manipulated once authenticated either as that Connection using a Connection token or by authenticating using a User token with read/write access to the Connection.
By issuing a PUT request and one or many properties as key/values in payload the information is updated. A successful save is indicated by a 200 OK. The "me" alias can be used to reference the default Connection if authenticated as a User or the Connection in question if authenticated using a Connection token.
PUT /2/connections/<ID>
PUT /2/connections/me| Parameter | Type | Description |
|---|---|---|
| callbacks.dlr Optional |
string | The callback URL that will be used for your Delivery reports. |
| callbacks.mo Optional |
string | The callback URL that will be used for your Mobile Originated SMS. |
| callbacks.method Optional |
string | What HTTP method that will be used for your callbacks. GET, POST or PUT. |
| system_id Optional |
string | Your login name. Used for SMPP and HTTP v1 api. |
| label Optional |
string | Custom label to recognize your connection. |
| description Optional |
string | Connection description. |
| default_connection Optional |
bool | If authenticating with a user API Token, set to true to make specified connection your default. |
This endpoint supports partial updates. Any omitted field in a model will read in the current value.
Initialise a request with the fields you would like to update.
{
"callbacks": {
"dlr": "https://beepsend.com/securedlr"
},
"system_id": "crossover",
"label": "Pawnee-connection",
"description": "Cool. Cool, cool, cool"
}
If authenticating with a user API Token you can even set specified connection to be your default.
{
"default_connection": true
}
{
"id": 15748,
"system_id": "crossover",
"label": "Pawnee-connection",
"api_token": "abc123",
"callbacks": {
"dlr": "https://beepsend.com/securedlr",
"mo": "https://beepsend.com/mocallback",
"method": "PUT"
},
"users": [
{
"id": 1,
"name": "Beep Beepson",
"username": "beepsend-user"
}
],
"wallet": {
"id": 1,
"name": "Beepsend wallet",
"balance": 5.78838
},
"customer": "Beepsend AB",
"description": "Cool. Cool, cool, cool",
"type": 1,
"whitelist": [],
"tlv_for_mcc_mnc": 0
}
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"callbacks": {"dlr": "https://yourdomain.com/securedlr"}, "system_id": "crossover", "label": "Pawnee-connection", "description": "Cool. Cool, cool, cool"}' \
"https://api.beepsend.com/2/connections/1"
$client->connection->update({CONNECTION}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$data = array(
'callbacks' => array(
'dlr' => 'https://beepsend.com/securedlr'
),
'system_id' => 'crossover',
'label' => 'Pawnee-connection',
'description' => 'This is the main production connection'
);
$connectionId = 1;
$connections = $client->connection->update($connectionId, $data);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.connection().update({CONNECTION}, {DATA}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
//In this example we will show how you can update your default connection
var connectionId = "me";
var connectionData = {
"callbacks": {
"dlr": "https://beepsend.com/securedlr"
},
"system_id": "crossover",
"label": "Pawnee-connection",
"description": "Cool. Cool, cool, cool"
};
client.connection().update(connectionId, connectionData).then(
function(success) {
//Here you can handle success result
},
function(error) {
//Here you can handle error result
}
);
@interface BSConnection
@property (nonatomic, strong) NSString *label;
@property (nonatomic, strong) NSString *description;
@property (nonatomic, strong) NSString *systemID;
@property (nonatomic, strong) BSCallbacks *callbackURLs;
- (void)updateConnectionOnCompletion:(void(^)(NSArray *errors))block;
@end
//Connection that you want to update
BSConnection *connection = [BSConnection currentConnection];
connection.label = @"New label";
connection.description = @"New description";
connection.systemID = @"New system ID";
connection.callbackURLs.DLR = @"www.newdlrcallback.com";
connection.callbackURLs.MO = @"www.newmocallback.com";
connection.callbackURLs.method = @"POST";
[connection updateConnectionOnCompletion:^(NSArray *errors) {
if (!errors || errors.count == 0) {
//Connection successfully updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
If you think that the connection token used for authenticating with the Beepsend API has been compromised you can use this method (with a user token) to reset the connection token.
GET /2/connections/<id>/tokenreset{
"api_token": "abc123",
}
| Key | Type | Description |
|---|---|---|
| api_token | string | New API Token for this connection. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/1/tokenreset"
$client->connection->resetToken({CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$newToken = $client->connection->resetToken($connectionId);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.connection().resetToken({CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var connection = 1;
client.connection().resetToken(connection).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)resetConnectionTokenOnCompletion:(void(^)(NSArray *errors))block;
@end
[[BSConnection currentConnection] resetConnectionTokenOnCompletion:^(NSArray *errors) {
if (!errors || errors.count == 0) {
//Token successfully updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
If you wish to use our legacy HTTP API, you need to supply your connection username as well as password for each request. If you don't have your connection password, you can request a new one with this endpoint.
NOTE: A connection token and password are two separate things. A connection password is only used for HTTP API and SMPP.
GET /2/connections/<id>/passwordreset{
"password": "abc12345",
}
| Key | Type | Description |
|---|---|---|
| password | string | New 8 character password to use with HTTP API and SMPP. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/1/passwordreset"
$client->connection->resetPassword({CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$newToken = $client->connection->resetPassword($connectionId);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.connection().resetPassword({CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var connection = 1;
client.connection().resetPassword(connection).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)resetConnectionPasswordOnCompletion:(void(^)(NSString *password, NSArray *errors))block;
@end
[[BSConnection currentConnection] resetConnectionPasswordOnCompletion:^(NSString *password, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (updated password)
}
else {
//Handle error (array of BSError objects)
}];
Please contact your account manager if you wish to setup a 2-way number. Find out how to recieve a mobile orignated SMS under our callback documentation.
As a user you will have associated connections. These connections (may) have access to 2-way numbers, which can receive mobile originated messages. The 2-way numbers are registered in specific countries, which this endpoint will also list.
GET /2/numbers/
GET /2/numbers/<ID>
GET /2/numbers/?ids=<ID1,ID2>&connection=<connection ID>
GET /2/numbers/?number=<number>&connection=<connection ID>| Parameter | Type | Description |
|---|---|---|
| number Optional |
int | Registered number |
| connection_id Optional |
int | Get numbers linked to a specific connection |
| ids Optional |
string | List of ids separated by a comma (,) |
[
{
"id": 350,
"number": "1272",
"country": "Denmark",
"keywords": [
{
"connection": {
"id": 1,
"name": "your-account"
},
"keyword": null,
"price": 0
}
]
},
{
"id": 8779,
"number": "46736007500",
"country": "Sweden",
"keywords": [
{
"connection": {
"id": 1,
"name": "your-account"
},
"keyword": null,
"price": 0
}
]
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Recipient number id |
| number | int | Recipient number |
| country | string | Country name |
| keywords | array | List of keywords |
| keywords.keyword | null|string | The keyword that will be matched on for incoming MO traffic. null will match everything. |
| keywords.price | float | The cost for each incoming MO. |
| keywords.connection | int | Connection object |
| keywords.connection.id | int | ID of connection |
| keywords.connection.name | string | Name of connection |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/numbers/"
$client->contact->recipientNumbers();
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$numbers = $client->contact->recipientNumbers();
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.connection().recipientNumbers().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.connection().recipientNumbers().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getRecipientNumbersOnCompletion:(void(^)(NSArray *numbers, NSArray *errors))block;
@end
[[BSUser currentUser] getRecipientNumbersOnCompletion:^(NSArray *numbers, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSNumber objects)
}
else {
//Handle error (array of BSError objects)
}
}];
The following endpoints give access to a connections associated pricelist. If accessing using a user token, connection id which the user is accociated with is required.
The API offers the ability to see every revision made of price lists for each connection. When specifying a revision ID one can fetch the detailed price list at that point in time. If authenticated using a User token, a connection ID needs to be provided too. For simplicity the tag "me" can be used to select the default assigned connection for the User.
This end point is subject to rate limits. The API is restricted to allow five requests per five minute interval and token.
(To download price lists in the CSV-format specified on the individual connection you need to use the information here ).
Instead of fetching all revisions and then using the latest revision id to get the current price list the following can be used for both User and Connection authentications:
GET /2/connections/<ID>/pricelists/current
GET /2/connections/me/pricelists/current
GET /2/pricelists/<ID>
GET /2/pricelists/<label>{
"networks": [
{
"mccmnc": [
{
"mnc": "03",
"mcc": "648"
}
],
"comment": "",
"price": 0.006,
"country": {
"name": "Zimbabwe",
"prefix": 263,
"code": "ZW"
},
"operator": "Telecel Zimbabwe (PVT) Ltd (TELECEL)",
}
],
"id": 280290,
"timestamp": 1386085755,
"active": true,
"first_viewed": 1386228799,
"parent_revision_id": 280195
}
| Key | Type | Description |
|---|---|---|
| networks | array | An array of networks covered by this pricelist. |
| networks.mccmnc.mnc | string | MNC of the network. |
| networks.mccmnc.mcc | string | MCC of the network. |
| networks.comment | string | (Optional) Specific details about this network. |
| networks.price | float | Price of sending to this network in Euro (€). |
| networks.country.name | string | Name of the country this network resides in. |
| networks.country.prefix | int | Country calling code. |
| networks.country.code | string | Country code (ISO-3166-1). |
| networks.operator | string | Operator name. |
| id | int | Pricelist ID. |
| timestamp | int | Date of save for this pricelist. |
| active | bool | Whether this pricelist is active or not. |
| first_viewed | int, Unix time|null | First time this pricelist was accessed by customer. |
| parent_revision_id | int | Parent revision ID |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/1/pricelists/current"
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me/pricelists/current"
$client->pricelist->get({CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$pricelist = $client->pricelist->get($connectionId);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.pricelist().get({CONNECTION_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var connectionId = "me";
client.pricelist().get(connectionId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)getCurrentPricelistOnCompletion:(void(^)(BSPricelist *pricelist, NSArray *errors))block;
@end
[[BSConnection currentConnection] getCurrentPricelistOnCompletion:^(BSPricelist *pricelist, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSPricelist object)
}
else {
//Handle error (array of BSError objects)
}
}];
Receive the 200 latest price lists revisions* for a specific connection related to the authenticated user. A connection ID or alias tag "me" must be provided as reference.
GET /2/connections/<ID>/pricelists/
GET /2/connections/me/pricelists/[{
"networks_count": 980,
"id": 280290,
"timestamp": 1386085000,
"active": true,
"first_viewed": 1386228799
}]
| Key | Type | Description |
|---|---|---|
| networks_count | int | Number of networks covered by this pricelist. |
| id | int | Pricelist revision ID. |
| timestamp | int | Date of save for this pricelist. |
| active | bool | Whether this pricelist is active or not. |
| first_viewed | int, Unix time | First time this pricelist was accessed by customer. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/12/pricelists/"
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me/pricelists/"
$client->pricelist->revisions({CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$revisions = $client->pricelist->revisions();
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.pricelist().getRevisions({CONNECTION_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var connectionId = "me";
client.pricelist().getRevisions(connectionId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
You can also omit connection id and then the "me" alias is used to reference the default connection
@interface
- (void)getPricelistsOnCompletion:(void(^)(NSArray *pricelists, NSArray *errors))block;
@end
[[BSConnection currentConnection] getPricelistsOnCompletion:^(NSArray *pricelists, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSPricelist objects)
}
else {
//Handle error (array of BSError objects)
}
}];
Receive pricelist for a specific connection as a csv file. A connection ID or alias tag "me" must be provided as reference.
GET /2/pricelists/<ID>.csv
GET /2/pricelists/<label>.csv| Parameter | Type | Description |
|---|---|---|
| id Required |
int | Id of the connection which price list to received. |
| label Required |
string | Label of the connection. |
| delimiter Optional |
string | What delimiter to use for the csv output. (Default: , <comma>) |
| fields Optional |
string | Comma separated list of fields to use in the output (will be ordered in the same way as the input). Available fields: mcc, mnc, mccmnc, country, operator, price. Default: mcc, mnc, country, operator, price. |
Example
GET /2/pricelists/1.csv?delimiter=;&fields=mcc,mnc,operator,pricemcc;mnc;operator;price
240;;Default;0.08
240;01;"TeliaSonera Mobile Networks AB Sweden (TeliaSonera Mobile Networks)";0.068
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/pricelists/1234.csv"
$client->pricelist->download({CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$connectionId = 1;
$client = new Client('abc123');
$pricelist = $client->pricelist->download($connectionId);
You can also omit connection id and then the "me" alias is used to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.pricelist().download({CONNECTION_ID}, {DELIMITER}, {FIELDS});
var connectionId = 1;
client.pricelist().download(connectionId);
@interface BSConnection
- (void)getPricelistsAsCsvOnCompletion:(void(^)(NSString *pricelist, NSArray *errors))block;
@end
[[BSConnection currentConnection] getPricelistsAsCsvOnCompletion:^(NSString *pricelist, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (NSString containing data from csv file)
}
else {
//Handle error (array of BSError objects)
}
}];
Beepsend can give you price changes. To get it you have to find pricelist revisions that you want to compare.
Compare pricelist revisions from given connection and return their diff.
GET /2/pricelists/<ID>/<rev1>..<rev2>/diff
GET /2/pricelists/<label>/<rev1>..<rev2>/diff| Parameter | Type | Description |
|---|---|---|
| id Required |
int | Id of the connection which pricelist are compared. |
| label Required |
string | Label of the connection. |
| rev1 Required |
int | Id of first pricelist to compare |
| rev2 Required |
int | Id of second pricelist to compare |
Example
GET /2/pricelists/1/4321..4371/diff[
{
"country": {
"name": "Zimbabwe",
"prefix": 263,
"code": "ZW"
},
"operator": "Telecel Zimbabwe (PVT) Ltd (TELECEL)",
"mccmnc": [
{
"mnc": "03",
"mcc": "648"
}
],
"comment": "",
"price": 0.006,
"old_price":0.022,
"diff":"price"
}
]
| Key | Type | Description |
|---|---|---|
| country.name | string | Name of the country this network resides in. |
| country.prefix | int | Country calling code. |
| country.code | string | Country code (ISO-3166-1). |
| operator | string | Operator name. |
| mccmnc | array | An array of mcc mnc that belong to this operator |
| mccmnc.mnc | string | MNC of the network. |
| mccmnc.mcc | string | MCC of the network. |
| comment | string | Specific details about this network. |
| price | float | Price of sending to this network in Euro (�). Price belong to pricelist given as rev2 |
| old_price | float | Old price of sending to this network in Euro (�). Price belong to pricelist given as rev1 |
| diff | string | Type of differece between revisions, possible values price, new or removed |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/pricelists/1/4321..4371/diff"
$client->pricelist->diff({REV_1}, {REV_2}, {CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$diff = $client->pricelist->diff(4321, 4371, 1);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.pricelist().diff({CONNECTION_ID}, {REV1}, {REV2}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var connectionId = 1;
var rev1 = 1234;
var rev2 = 2134;
client.pricelist().diff(connectionId, rev1, rev2).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)getPricelistsDiffForPricelist:(BSPricelist *)pl1 andPricelist:(BSPricelist *)pl2 onCompletion:(void(^)(BSNetwork *pricelistDiff, NSArray *errors))block;
@end
BSPricelist *pl1 = firstPricelistToCompare;
BSPricelist *pl2 = secondPricelistToCompare;
[[BSConnection currentConnection] getPricelistsDiffForPricelist:pl1 andPricelist:pl2 onCompletion:^(BSNetwork *pricelistDiff, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSNetwork object)
}
else {
//Handle error (array of BSError objects)
}
}];
Compare pricelist revisions from given connection and return their diff as csv file.
GET /2/pricelists/<ID>/<rev1>..<rev2>/diff.csv
GET /2/pricelists/<label>/<rev1>..<rev2>/diff.csv| Parameter | Type | Description |
|---|---|---|
| id Required |
int | Id of the connection which pricelist are compared. |
| label Required |
string | Label of the connection. |
| rev1 Required |
int | Id of first pricelist to compare |
| rev2 Required |
int | Id of second pricelist to compare |
| delimiter Optional |
string | What delimiter to use for the csv output. (Default: , <comma>) |
| fields Optional |
string | Comma separated list of fields to use in the output (will be ordered in the same way as the input). Available fields: mcc, mnc, mccmnc, country, operator, old_price, price, price_diff, diff, comment. Default: mcc, mnc, mccmnc, country, operator,o ld_price, price, price_diff, diff, comment |
Example
GET /2/pricelists/1/4321..4371/diff.csv?delimiter=;&fields=mcc,mnc,operator,price,price_diff,diffmcc;mnc;operator;price;price_diff;diff
240;;Default;0.08;0.011;price
240;01;"TeliaSonera Mobile Networks AB Sweden (TeliaSonera Mobile Networks)";;0;removed
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/pricelists/1/4321..4371/diff.csv"
$client->pricelist->downloadDiff({REV_1}, {REV_2}, {CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$diff = $client->pricelist->downloadDiff(4321, 4371, 1);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.pricelist().diffDownload({CONNECTION_ID}, {REV1}, {REV2}, {DELIMITER}, {FIELDS});
var connectionId = 1;
var rev1 = 1234;
var rev2 = 2134;
client.pricelist().diffDownload(connectionId, rev1, rev2);
@interface BSConnection
- (void)getPricelistsDiffAsCsvForPricelist:(BSPricelist *)pl1 andPricelist:(BSPricelist *)pl2 onCompletion:(void(^)(NSString *pricelist, NSArray *errors))block;
@end
BSPricelist *pl1 = firstPricelistToCompare;
BSPricelist *pl2 = secondPricelistToCompare;
[[BSConnection currentConnection] getPricelistsDiffAsCsvForPricelist:pl1 andPricelist:pl2 onCompletion:^(NSString *pricelist, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (NSString containing data from csv file)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Get details regarding your user.
GET /2/users/me{
"id": 4,
"name": "Beep",
"email": "beep@beepsend.com",
"trial": false,
"disabled": false,
"phone": [
{
"number": "46736007518",
"verified": true,
"primary_number": true
}
],
"customer": [
{
"id": 1,
"name": "Beepsend AB",
"disabled": false,
"trial": false
}
],
"api_token": "abc123",
"default_connection": {
"id": 27,
"label": "The Beep Connection",
"system_id": "beep-connect",
"type": 1
},
"user_types": [
{
"id": 1,
"name": "Technical Contact"
}
],
"max_level": 2,
"verified": {
"email": true,
"terms": true
}
}
| Key | Type | Description |
|---|---|---|
| id | int | Unique user ID. |
| name | string | Name to recognise your User by. |
| string | User email. | |
| trial | bool | Indicates whether user is in trial mode |
| disabled | bool | Indicates whether user is disabled |
| phones | array | Array of user phone numbers. |
| phone.number | string | Phone number |
| phone.verified | bool | Indicates if the phone is verified. |
| phone.primary_number | bool | Indicates if the phone is user's primary number. |
| customer.id | int | Unique customer ID. |
| customer.name | string | Name of customer the user is associated with. |
| customer.disabled | bool | Indicates if customer and all users are disabled. |
| customer.trial | bool | Indicates if customers all users are in trial mode. |
| api_token | string | API Token belonging to this User. |
| default_connection | array | Object with information regarding the default connection for this user. |
| default_connection.id | int | Unique connection ID. |
| default_connection.label | string | Name of connection. |
| default_connection.system_id | string | Connection login name. Used for API v.1 as well as SMPP. |
| user_types | array | List of types that applies to this user. |
| user_types.id | int | Type ID. |
| user_types.name | string | Type name to describe its function |
| max_level | int | Simple permission model. Allows access to all version 2 endpoints. |
| verified.email | bool | If the users email address is verified or not. |
| verified.terms | bool | True if the user has agreed to the terms & conditions. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/me"
$client->user->get();
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->get();
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().get().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.user().get().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
+ (BSUser *)currentUser;
@end
//It is necessary to call this method at application start so there would be enough time for user to initialize
//Because it is singleton it will be initialized only first time
BSUser *user = [BSUser currentUser];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Update properties for your user.
PUT /2/users/me| Parameter | Type | Description |
|---|---|---|
| name Optional |
string | Name to recognise your user by. |
| phones Optional |
array | Update users phones, update must contain primary number. Expects object in array containing number. Note that this will not be immediately changed. An SMS will be sent out to your new number asking you to verify the change. Until verified your current number will be used. The verification SMS will be valid for 24 hours. |
| default_connection Optional |
array | Object with default connection. |
| default_connection.id Optional |
int | Connection ID that should be the default for this user. |
| user_types Optional |
array | List of objects with user types that applies for this user. |
| user_types.id Optional |
int | User type ID. |
| verified.terms Optional |
bool | True if you accept the terms & conditions. |
This endpoint supports partial updates. Any omitted field in a model will read in the current value.
| ID | Type |
|---|---|
| 1 | Technical Contact |
| 2 | Account Contact |
| 3 | Support Contact |
| 4 | Pricelist Contact |
| 5 | Finance Contact. |
Initialise a request with the fields you would like to update.
{
"name": "My user",
"default_connection": {
"id": 27
},
"user_types": [
{
"id": 1
},
{
"id": 5
}
],
"verified": {
"terms": true
}
}
A user object.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"name": "Christian Nilsson", "default_connection": {"id": 27}, "user_types": [{"id": 1}, {"id": 5}], "verified": {"terms": true}' \
"https://api.beepsend.com/2/users/me"
$client->user->update({OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$data = array(
'name' => 'My user',
'default_connection' => array(
'id' => 27
),
'user_types' => array(
array('id' => 1),
array('id' => 5)
),
'verified' => array(
'terms' => true
)
);
$user = $client->user->update($data);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().update({OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var options = {
"name": "My user",
"default_connection": {
"id": 27
},
"user_types": [
{
"id": 1
},
{
"id": 5
}
],
"verified": {
"terms": true
}
};
client.user().update(options).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
@property (nonatomic, strong) NSString *name;
@property (nonatomic, strong) NSString *phone;
@property (nonatomic, strong) BSConnection *defaultConnection;
@property (nonatomic, strong) NSArray *userTypes;
@property (nonatomic, strong, readonly) BSVerified *verified;
- (void)updateUserOnCompletion:(void(^)(NSArray *errors))block;
@end
[BSUser currentUser].name = @"New name";
[BSUser currentUser].phone = @"012345678911";
[BSUser currentUser].defaultConnection = newConnection;
[BSUser currentUser].userTypes = @[userType1, userType2];
[BSUser currentUser].verified.termsVerified = @YES
[[BSUser currentUser] updateUserOnCompletion:^(NSArray *errors) {
if (!errors || errors.count == 0) {
//User updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Update email for your user.
PUT /2/users/me/email| Parameter | Type | Description |
|---|---|---|
| email Required |
string | The email address you would like to change to. |
| password Required |
string | Your current password. This is needed for extra security. |
{
"email": "newemail@beepsend.se",
"password": "supersecret"
}
204 no content header.
After having changed user email, an email will be sent out to the new email address. In this email is a verification link that must be visited within 24 hours for the email change to go through. Until then, the old email is used.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"email": "newemail@beepsend.se", "password": "supersecret"}' \
"https://api.beepsend.com/2/users/me/email"
$client->user->updateEmail({EMAIL}, {CURRENT_PASSWORD});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->updateEmail('newemail@beepsend.se', 'supersecret');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().updateEmail({EMAIL}, {PASSWORD}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var newEmail = "newemail@beepsend.se";
var password = "yourpassword";
client.user().updateEmail(newEmail, password).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
@property (nonatomic, strong) NSString *email;
- (void)updateUserEmailWithPassword:(NSString *)password onCompletion:(void(^)(NSArray *errors))block;
@end
[BSUser currentUser].email = @"newemail@mail.com";
[[BSUser currentUser] updateUserEmailWithPassword:@"password" onCompletion:^(NSArray *errors) {
if (!errors || errors.count == 0) {
//Email updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Update user password.
PUT /2/users/me/password| Parameter | Type | Description |
|---|---|---|
| password Required |
string | Your current password. This is needed for extra security. |
| new_password Required |
string | The new password to be set for your user. |
{
"password": "supersecret",
"new_password": "donotlookplease"
}
204 no content header.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"password": "supersecret", "new_password": "donotlookplease"}' \
"https://api.beepsend.com/2/users/me/password"
$client->user->updatePassword({NEW_PASSWORD}, {OLD_PASSWORD});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->updatePassword('donotlookplease', 'supersecret');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().updatePassword({OLD_PASSWORD}, {NEW_PASSWORD}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var oldPassword = "oldPassword";
var newPassword = "newPassword";
client.user().updatePassword(oldPassword, newPassword).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)changePassword:(NSString *)currentPassword withNewPassword:(NSString *)newPassword onCompletion:(void(^)(NSArray *errors))block;
@end
[[BSUser currentUser] changePassword:@"currentPassword" withNewPassword:@"newPassword" onCompletion:^(NSArray *errors) {
if (!errors || errors.count == 0) {
//Password changed
}
else {
//Handle error (array of BSError objects)
}
}];
If you have forgotten or in other ways lost control over your password, you can issue a reset. When doing so, Beepsend will send an email with a link to where you can get your new password.
GET /2/users/passwordreset?email=myemail@beepsend.com| Parameter | Type | Description |
|---|---|---|
| string | Your login email. |
204 no content header.
In the reset email sent out by Beepsend you will find a link to restore your password. At the end of that link is a hash that can be used to set a new password.
PUT /2/users/password/<hash>| Parameter | Type | Description |
|---|---|---|
| password | string | Your new password |
{
"password": "mynewpassword"
}
A user object. See Users.
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/passwordreset?email=myemail@beepsend.com"
/* Set new password with given hash */
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"password": "mynewpassword"}' \
"https://api.beepsend.com/2/users/password/<hash>"
$client->user->resetUserPassword({EMAIL});
$client->user->setNewPassword({HASH}, {EMAIL});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$client->user->resetUserPassword('myemail@beepsend.com');
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->setNewPassword('<hash in email>', 'mynewpassword');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().resetUserPassword({EMAIL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.user().setNewPassword({HASH}, {EMAIL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var email = "myemail@beepsend.com";
client.user().resetUserPassword(email).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
/* After receiving reset password email you need to call next endpoint and provide hash, that you received in password reset email, and new password as well */
var hash = "b123ais123";
var newPassword = "yournewpassword";
client.user().setNewPassword(hash, newPassword).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)resetUserPasswordOnCompletion:(void(^)(BOOL success, NSArray *errors))block;
@end
[[BSUser currentUser] resetUserPasswordOnCompletion:^(BOOL success, NSArray *errors) {
if (!errors || errors.count == 0) {
//Password successfully reseted
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
If you think that the user token used for authenticating with the Beepsend API has been compromised you can use this method (with your current user token and password) to reset the user token.
GET /2/users/me/tokenreset
GET /2/users/<id>/tokenreset| Parameter | Type | Description |
|---|---|---|
| password | string | Your current password. Needed to not allow unauthorized people to reset the token. |
{
"api_token": "abc123",
}
| Key | Type | Description |
|---|---|---|
| api_token | string | New API Token for this connection. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/<id>/tokenreset"
$client->user->resetUserToken({PASSWORD});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$token = $client->user->resetUserToken('mysecretpassword');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().resetUserToken({PASSWORD}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var password = "yourpassword";
client.user().resetUserToken(password).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)resetUserTokenWithPassword:(NSString *)password onCompletion:(void(^)(NSArray *errors))block;
@end
[[BSUser currentUser] resetUserTokenWithPassword:@"password" onCompletion:^(NSArray *errors) {
if (!errors || errors.count == 0) {
//Token reseted
}
else {
//Handle error (array of BSError objects)
}
}];
Each sent message require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.
A message can carry 160 characters if in the Latin alphabet and 70 if content is Unicode. The Beepsend Gateway will automatically split up the message if the content exceeds the maximum character limit based on the content encoding. When sending UTF-8 encoding the Beepsend Gateway will try and convert to GSM7 if possible to avoid splitting at 70 characters.
The endpoint for sending messages is:
POST /2/send/Specify which connection to use for sending this message. This can be useful if you are authenticating with a User token and do not want to send with your default connection.
POST /2/send/<connection id>
POST /2/send/<connection label>| Parameter | Type | Description |
|---|---|---|
| to Required |
string | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. |
| body Required |
string | Message body. |
| from Required |
string | Sender id. Check below for a list of allowed formats. |
| encoding Optional |
string | UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE. |
| message_type Optional |
string | flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters. |
| validity_period Optional |
int, Unix time | How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite. |
| receive_dlr Optional |
int | Specify whether delivery reports should be sent to your DLR Callback URL.0: Disable, 1: Always, 2: Only on failure. Default is 1. |
| auto_gsm7_conversion Optional |
true | false | Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true. |
{
"to": "46736007518",
"body": "Hello World! 你好世界!",
"from": "Beepsend",
"encoding": "UTF-8",
"receive_dlr": 0
}
[
{
"id": [
"01108500014328897161775546736007518"
],
"from": "Beepsend",
"to": "46736007518"
}
]
| Key | Type | Description |
|---|---|---|
| id | array | null | Unique Beepsend generated ID. If the SMS got rejected, null. |
| to | string | Input destination for this particular SMS. |
| from | string | Input source. |
The following formats are allowed for from.
Alphanumeric signs with upper och lower case characters (a-z, A-Z, 0-9). The maximum allowed characters are 11. We crop the from address at 11 characters.
MSISDN numbers, international format. Minimum 9 chars, max 17 chars.
Short numbers / codes, national format. Maximum length 7 chars.
Local restrictions apply. Check with your account manager for the destinations you aim to send to for details.
Long SMS are messages with more than 160 (70 if unicode encoding) characters. Beepsend will automatically split up your long messages before sending so you don't have to worry about it. Unless you're sending binary SMS.
Since long SMS are really just two or more messages with a special identifier that connects them, you will receive a response with separate IDs for each message you are sending. When sending with our a sendouts endpoint you will get a sendout id which you then need to do a lookup with the provided id to get all the MSISDNs.
Billing is done based on how many parts the message in total requires.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"to": "46736007518", "body": "Hello World! 你好世界!", "from": "Beepsend", "encoding": "UTF-8", "receive_dlr": 0}' \
"https://api.beepsend.com/2/send/"
$client->message->send({TO}, {FROM}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$options = array(
'receive_dlr' => false
);
$message = $client->message->send(
'46736007502',
'Beepsend',
'Hello World! 你好世界!',
$connectionId,
'UTF-8',
$options
);
You can also set null for connection id and then the "me" alias is used to reference the default connection
POST /2/send/
POST /2/send/<connection id>
POST /2/send/<connection label>If your system rather sends the messages using binary content we offer a service for this. The combined length of a binary message and UDH can not be longer than 140 bytes (280 hex characters), if you want to send concatenated messages you have to do this by sending a sequence of messages with the appropriate UDH.
To send a binary SMS. You need to have message_type set to binary. When sending binary SMS the following options become available.
| Parameter | Type | Description |
|---|---|---|
| udh Optional |
string | User Data Header. Can be used to send Concatenated or Wap Push messages. |
| dcs Optional |
int | Data coding settings. For binary messages this is set to 4 (8-bit binary) by default. Should be 0 for gsm7 encoded messages and 8 for UCS-2 encoded messages. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"to": "46736007518", "message": "48656c6c6f20576f726c6421", "from": "Beepsend", "encoding": "UTF-8", "message_type": "binary"}' \
"https://api.beepsend.com/2/send/"
If something terrible were to happen. We'll send back a neat array of error codes and descriptions.
{
"to": [
"12345"
],
"from": "x"
}
[
{
"errors": [
{
"code": 1030,
"description": ""from" can not be shorter than 2 characters"
},
{
"code": 1026,
"description": ""message" is required and can not be null"
}
]
}
]
The API can be utilized to get details of any message sent through Beepsend no matter if you submitted it via SMPP or HTTP.
Get details regarding one message.
GET /2/send/<sms id>{
"id": "12345",
"body": "Hello World!",
"hex_body": "48656c6c6f20576f726c6421",
"connection": {
"id": 7,
"label": "superman-connection"
},
"to": {
"address": "46406007500",
"ton": 1,
"npi": 1
},
"from": {
"address": "Beepsend",
"ton": 1,
"npi": 1
},
"validity_period": "131102072704000-",
"data_coding": 3,
"timestamps": {
"sms": {
"in": 1383225355,
"delivered": 1383225359
},
"dlr_out": 1383225359
},
"dlr": {
"status": "DELIVRD",
"error": 0
},
"price": 0.068,
"mccmnc": {
"mcc": "240",
"mnc": "01"
}
}
| Key | Type | Description |
|---|---|---|
| id | string | Unique Beepsend generated ID. |
| body | string | The message body of sent SMS. |
| hex_body | string | Hex encoded string containing the raw body of sent SMS (or sms part if it's multipart message). |
| connection | array | Connection details. |
| connection.id | int | The id of the connection that was used to send the SMS. |
| connection.label | string | The name of the connection that was used to send the SMS. |
| to.address | string | Destination address. |
| to.ton | int | Type of number. |
| to.npi | int | Number Plan Index. |
| from.address | string | Source address. |
| from.ton | int | Type of number. |
| from.npi | int | Number Plan Index. |
| validity_period | string | Until what date and time the message is considered valid for routing. Formatted like YYMMDDhhmmsstnnp according to the SMPP standard. |
| data_coding | int | Data coding settings. 0 for Gsm7 encoded messages. 8 for UCS-2 encoded messages and 4 for binary messages. Can be set manually if sending Binary SMS. |
| timestamps.sms.in | int | When the message reached Beepsend in Unix time. |
| timestamps.sms.delivered | int | null | When the message was delivered to handset. In Unix time. null if not yet delivered. |
| timestamps.dlr_out | int | null | When the Delivery Report left our system to reach your DLR Callback URL. null if message has not been delivered yet. |
| dlr.status | string | null | One of the following: DELIVRD, EXPIRED, REJECTD, UNKNOWN, UNDELIV, FAILED. Or null if message has not yet been delivered. |
| dlr.error | int | null | Specific return codes regarding message delivey. 0 if OK. Beepsend Return Codes. null if message has not been delivered yet. |
| price | float | Message price. |
| mccmnc.mcc | string | Destination mcc. |
| mccmnc.mnc | string | Destination mnc. |
In case of a multipart SMS. body will be concatenated to contain all the parts.
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/sms/12345"
$client->message->lookup({SMS_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$smsId = 12345;
$message = $client->message->lookup($smsId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().lookup({MESSAGE_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var messageId = 12345;
client.messages().lookup(messageId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)getDetailsForSMS:(BSMessage *)message onCompletion:(void(^)(BSLookup *lookup, NSArray *errors))block;
@end
BSMessage *message = messageThatWasSent;
[[BSConnection currentConnection] getDetailsForSMS:message onCompletion:^(BSLookup *lookup, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSLookup object)
}
else {
//Handle error (array of BSError objects)
}
}];
Our Sendout endpoint is for doing some additional nifty things with your message. You can send to multiple adresses, send to a group and set a send time for your message. You can also delete,update and add recipients to a message before it has been sent, granted you set a send time.
The endpoint for sending multiple messages is:
POST /2/sendouts/Specify which connection to use for sending this message. This can be useful if you are authenticating with a User token and do not want to send with your default connection.
POST /2/sendouts/<connection id>| Parameter | Type | Description |
|---|---|---|
| sms.to Required * |
array (string) | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values. Note Multiple destinations count as multiple messages and will be charged as such. |
| sms.groups Required * |
array (int) | The id of contants group that have to exist in our system. Supports multiple values. |
| sms.body Required |
string | Message body. |
| sms.from Required |
string | Sender id. Check below for a list of allowed formats. |
| label Optional | string | The name of your sendout of messages. |
| send_time Optional | int, Unix time | Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future. |
| receive_dlr Optional | int | Specify whether delivery reports should be sent to your DLR Callback URL.0: Disable, 1: Always, 2: Only on failure. Default is 1. |
| sms.encoding Optional | string | UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE. |
| sms.message_type Optional | string | flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters. |
| sms.validity_period Optional | int, Unix time | How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite. |
| sms.auto_gsm7_conversion Optional | true | false | Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true. |
The following formats are allowed for from.
Alphanumeric signs with small characters or capitals (a-z, A-Z, 0-9). The maximum allowed characters are 11. We crop the from address at 11 characters.
MSISDN numbers, international format. Minimum 9 chars, max 17 chars.
Short numbers / codes, national format. Maximum length 7 chars.
Local restrictions apply. Check with your account manager for the destinations you aim to send to for details.
Long SMS are messages with more than 160 (70 if unicode encoding) characters. Beepsend will automatically split up your long messages before sending so you don't have to worry about it. Unless you're sending binary SMS.
Since long SMS are really just two or more messages with a special identifier that connects them, you will receive a response with separate IDs for each message you are sending. When sending with our a sendouts endpoint you will get a sendout id which you then need to do a lookup with the provided id to get all the MSISDNs.
Billing is done based on how many parts the message in total requires.
{
"label": "Lottery winner",
"send_time": 1433116800,
"sms": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
],
"body": "You won!",
"from": "Beepsend",
"encoding": "UTF-8"
}
}
[
{
"id": 24151,
"label": "Lottery winner",
"connection_id": 17755,
"send_time": 1433116800,
"sms": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
],
"from": "Beepsend",
"message": "You won!"
}
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique sendout id. |
| label | string | Name of the Sendout. |
| conneciton_id | int | Connection id |
| send_time | int, Unix timestamp | Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days). |
| sms | object | Sms object with the data about your message, groups, to, from and any optional setting. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"label": "Lottery winner", "send_time": 1433116800, "sms": { "groups": [1,2],"to": ["123456","1234567"], "body": "You won!", "from": "Beepsend", "encoding": "UTF-8"}}' \
"https://api.beepsend.com/2/sendouts/"
$client->message->sendouts({GROUPS}, {TO}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$options = array(
'receive_dlr' => false
);
$message = $client->message->sendouts(
[1,2], /* Id of groups that we want to send sms too */
["123456","1234567"], /* List of numbers that we want to send sms too*/
'Beepsend',
'You won!',
$connectionId,
'UTF-8',
$options
);
You can also set null for connection id and then the "me" alias is used to reference the default connection
Send messages to groups or numbers.
POST /2/sendouts/Use specific connections to send messages
POST /2/sendouts/<connection id>You can send single SMS or sendout SMS but instead using 1 or more to addresses you can import contacts and send to full contacts group
To send message to contacts groups just add to standard sms parameter groups, parameter to is optional
| Parameter | Type | Description |
|---|---|---|
| groups Required |
array (string) | The id of contants group that have to exist in our system. Supports multiple values in an array. |
| to Optional |
array (string) | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array. |
{
"label": "Lottery winner",
"send_time": 1433116800,
"sms": {
"groups": [
1,
2
],
"body": "You won!",
"from": "Beepsend",
"encoding": "UTF-8"
}
}
[
{
"id": 24154,
"label": "Lottery winner",
"connection_id": 17755,
"send_time": 1433116800,
"sms": {
"groups": [
1,
2
],
"to": null,
"from": "Beepsend",
"message": "You won!"
}
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique sendout id. |
| label | string | Name of the Sendout. |
| conneciton_id | int | Connection id |
| send_time | int, Unix timestamp | Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days). |
| sms | object | Sms object with the data about your message, groups, to, from and any optional setting. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"label": "Lottery winner", "send_time": 1433116800, "sms": { "groups": [1,2], "body": "You won!", "from": "Beepsend", "encoding": "UTF-8"}}' \
"https://api.beepsend.com/2/sendouts/"
$client->message->sendouts({GROUPS}, {TO}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$options = array(
'receive_dlr' => false
);
$message = $client->message->sendouts(
[1,2], /* Id of groups that we want to send sms too */
[""], /* Empty list of phone numbers*/
'Beepsend',
'You won!',
$connectionId,
'UTF-8',
$options
);
You can also set null for connection id and then the "me" alias is used to reference the default connection
You can:
PUT /2/sendouts/<sendout id>| Parameter | Type | Description |
|---|---|---|
| id Required |
int | Unique sendout id for the sendout you wish to update or alter. |
| sms.to Required * |
array (string) | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values. Note Multiple destinations count as multiple messages and will be charged as such. |
| sms.groups Required * |
array (int) | The id of group that have to exist in our system. Supports multiple values. |
| sms.body Required |
string | Message body. |
| sms.from Required |
string | Sender id. Check below for a list of allowed formats. |
| label Optional | string | The name of your sendout of messages. |
| send_time Optional | int, Unix time | Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future. |
| receive_dlr Optional | int | Specify whether delivery reports should be sent to your DLR Callback URL.0: Disable, 1: Always, 2: Only on failure. Default is 1. |
| sms.encoding Optional | string | UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE. |
| sms.message_type Optional | string | flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters. |
| sms.validity_period Optional | int, Unix time | How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite. |
| sms.auto_gsm7_conversion Optional | true | false | Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true. |
{
"label": "Lottery winner",
"send_time": 1433116800,
"sms": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
],
"body": "You won!",
"from": "Beepsend"
}
}
[
{
"id": 24151,
"label": "Lottery winner",
"connection_id": 17755,
"send_time": 1433116800,
"sms": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
],
"from": "Beepsend",
"message": "You won!"
}
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique sendout id. |
| label | string | Name of the Sendout. |
| connection_id | int | Connection id |
| send_time | int, Unix timestamp | Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days). |
| sms | object | Sms object with the data about your message, groups, to, from and any optional setting. |
Note: Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days).
| Error Codes | Description |
|---|---|
| 1 | This Sendout has already been delivered or is in the process of being delivered. |
| 2 | Id does not exist. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"label": "Lottery winner", "send_time": 1433116800, "sms": { "groups": [14589,14581], "body": "You won!", "from": "Beepsend", "encoding": "UTF-8"}}' \
"https://api.beepsend.com/2/sendouts/<sendout id>"
The endpoint for deleting a Sendout messages is:
DELETE /2/Sendouts/<id>Please note: You can only delete a Sendout if you have specified a send time and if that send time is in the future.
{
"response": {
"code": 0,
"description": "Sendout deleted"
}
}
| Status Code | Description |
|---|---|
| 0 | Sendout deleted. |
| 1 | This Sendout has already been processed or are being processed. |
| 2 | Id does not exist. |
curl -H "Authorization: Token abc123" \
-X DELETE "https://api.beepsend.com/2/sendouts/<id>"
Get details of your created sendouts
GET /2/sendouts/GET /2/sendouts/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What offset in result set to fetch data from. |
[
{
"id": 24160,
"connection_id": "17755",
"label": "Lottery winner",
"date_created": 1432890161,
"send_time": 1433116800,
"processed": 51512,
"status": 2,
"sms": {
"groups": [
1,
2
],
"to": null,
"from": "Beepsend",
"message": "You won!",
"receive_dlr": 1,
"encoding": "utf-8",
"message_type": null,
"validity_period": "",
"auto_gsm7_conversion": true,
"sendout": {
"label": "Lottery winner",
"id": "24160"
}
}
},
{
"id": 24155,
"connection_id": "17755",
"label": "Lottery Loser",
"date_created": 1432889596,
"send_time": 1433116800,
"processed": 2,
"status": 2,
"sms": {
"groups": null,
"to": [
"46123456789",
"46987654321"
],
"from": "Beepsend",
"message": "You lost!",
"receive_dlr": 1,
"encoding": "utf-8",
"message_type": null,
"validity_period": "",
"auto_gsm7_conversion": true,
"sendout": {
"label": "Lottery Loser",
"id": "24155"
}
}
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique sendout id. |
| label | string | Name of the Sendout. |
| date_created | int, Unix time | Creation time of the Sendout. |
| last_used | int, Unix time | Last time the batch was used to send a message. |
| processed | int | Number of processed messages. |
| status | int | 0 for pending, 1 for in progress and 2 for sent. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/sendouts/?<parameter>=<value>"
This call will give a paginated overview of messages in a sendout, complete with sent and received message body, recipient number and contact details, if recipient number exists in user contacts. The mobile terminated messages are matched with their mobile originated counterpart
GET /2/sendouts/<ID>/messages/| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What offset in result set to fetch data from. Default is 0. |
[
{
"mt_sms_id": "889000680270500421",
"mt_body": "What is your name?",
"mt_timestamp": 1418030569,
"mo_sms_id": "889000680270500422",
"mo_body": "Sir Lancelot",
"mo_timestamp": 1418030569,
"dlr_stat": "DELIVRD",
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
},
{
"mt_sms_id": "889000680141388005",
"mt_body": "What is your quest?",
"mt_timestamp": 1418030569,
"mo_sms_id": "889000680141388006",
"mo_body": "To seek the holy grail",
"mo_timestamp": 1418030569,
"dlr_stat": "DELIVRD",
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
},
{
"mt_sms_id": "889000680141388005",
"mt_body": "What is your favorite color?",
"mt_timestamp": 1418030569,
"mo_sms_id": "889000680141388006",
"mo_body": "BLUE!",
"mo_timestamp": 1418030569,
"dlr_stat": "DELIVRD",
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
}
]
| Key | Type | Description |
|---|---|---|
| mt_sms_id | string | Unique Beepsend generated ID. |
| mt_body | string | UTF-8 encoded message body of the mobile terminated message. |
| mt_timestamp | int|null | Unix time of when the message was sent. |
| mo_sms_id | string | Unique Beepsend generated ID. |
| mo_body | string | UTF-8 encoded message body of the mobile originated message. |
| mo_timestamp | int|null | Unix time of when a reply was received. |
| dlr_stat | string | Response status. |
| to | object | |
| to.number | string | Recipient number |
| to.contact | object | |
| to.contact.firstname | string | Firstname of contact. |
| to.contact.lastname | string | Lastname of contact. |
This call will give all messages in a sendout formatted as CSV.
GET /2/sendouts/<ID>/messages.csv| Parameter | Type | Description |
|---|---|---|
| delimiter Optional |
string | What delimiter to use for the csv output. (Default: , <comma>) |
Fields in the CSV file are
| Field | Description |
|---|---|
| number | Recipient's number. |
| firstname | Firstname of the contact (might be empty). |
| lastname | Lastname of the contact (might be empty). |
| sent_sms_id | Outgoing SMS ID. |
| sent_body | Text sent to the recipient. |
| sent_sms_timestamp | ISO-8601 formatted time when the message was sent. |
| delivery_status | Status of the outgoing message. |
| incoming_sms_id | Incoming SMS ID. |
| incoming_message | Text received from the recipient. |
| incoming_sms_timestamp | ISO-8601 formatted time when the message was received. |
If you have an HLR connection set up with Beepsend this can be used to make HLR queries. You still need to identify which connection to use as HLR connection for submissions, either by setting the Connection ID or by using the "me" alias if your HLR connection is the default connection for the User token.
You can choose to do a simple, immediate HLR lookup via GET. This is only valid for one number at a time.
For bulk submissions you need to POST a request. The results will be returned to your callback URL.
GET /2/hlr/<msisdn>?connection=<connection id>| Parameter | Type | Description |
|---|---|---|
| msisdn Required |
string | Mobile number |
| connection Optional |
int | Specify your preferred connection to use for this operation. |
{
"id": "08087780013866630151559112345",
"timestamps": {
"hlr": {
"in": 1383225355,
"delivered": 1383225359
},
"dlr_out": 1383225359
},
"dlr": {
"status": "DELIVRD",
"error": 0
},
"mccmnc": {
"mcc": "402",
"mnc": "02"
},
"to": {
"address": "46736007600",
"ton": 1,
"npi": 1
},
"imsi": "423900000000000000000",
"ported": true,
"roaming": {
"is_roaming": true,
"mcc": "240",
"mnc": "01"
},
"prefix": {
"mcc": "402",
"mnc": "02"
}
}
| Key | Type | Description |
|---|---|---|
| id | string | The id of the transaction. |
| timestamps.hlr.in | int | When the HLR reached Beepsend. |
| timestamps.hlr.delivered | int | When HLR response reached Beepsend. |
| timestamps.dlr_out | int | When callback was sent. |
| dlr.status | string | Response status. |
| dlr.error | int | Response code. |
| mccmnc.mcc | string | Mobile Country Code for the handset. |
| mccmnc.mnc | string | Mobile Network Code for the handset. |
| to.address | string | The number you did the HLR on. |
| to.ton | int | The numbers Type of Number. |
| to.npi | int | The numbers Numbering Plan Identifier. |
| imsi | int | The IMSI of the handset if available. First five characters and then zeroes. |
| ported | bool | True if the number seems to be ported, false if not. |
| roaming | object | Return roaming information |
| roaming.is_roaming | bool | True if the number is roaming, false if not. |
| roaming.mcc | string | Mobile Country Code of current phone location |
| roaming.mnc | string | Mobile Network Code of current phone location |
| prefix | object | Return Mcc Mnc assigned to msisdn prefix. |
| prefix.mcc | string | Mobile Country Code assigned to msisdn prefix. |
| prefix.mnc | string | Mobile Network Code assigned to msisdn prefix. |
The following fields can be included by request.
| Key | Type | Description |
|---|---|---|
| price | float | HLR price. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlr/46736007518"
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlr/46736007518?connection=<connection id>"
$client->hlr->intermediate({MSISDN}, {CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$response = $client->hlr->intermediate(123456, $connectionId);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.hlr().intermediate({MSISDN}, {CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
/* You can provide specific connection for intermediate hlr request or you can use default (me) connection */
var connection = "me";
var msisdn = "46406007500";
client.hlr().intermediate(msisdn, connection).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface
- (void)immediateHLRForNumber:(NSString *)phoneNumber onCompletion:(void(^)(BSHLR *hlr, NSArray *errors))block;
@end
[[BSConnection currentConnection] immediateHLRForNumber:@"012345678900" onCompletion:^(BSHLR *hlr, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSHLR object)
}
else {
//Handle error (array of BSError objects)
}
}];
Sometimes you might want to do an HLR lookup on more than one number at a time. For this case we have created an HLR Batch endpoint. You can do lookups on multiple addresses, on an pre-defined group or a mix of them both. You can also look at the reports afterwards, either as JSON objects or as a CSV file.
You need to specify which HLR connection to use for doing lookups.
POST /2/hlrbatch/<connection id>| Parameter | Type | Description |
|---|---|---|
| hlr.to Required * |
array (string) | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values. Note: Multiple numbers counts as multiple lookups and will be charged as such. |
| hlr.groups Required * |
array (int) | The id of contacts group that have to exist in our system. Supports multiple values. |
| label Optional | string | The name of your hlr batch. |
{
"label": "Winter customer sendout HLR",
"hlr": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
]
}
}
{
"id": 24151,
"label": "Winter customer sendout HLR",
"date_created": 1453485600,
"connection_id": 17755,
"hlr": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
]
},
"processed": 0,
"status": 0
}
| Key | Type | Description |
|---|---|---|
| id | int | Unique batch id. |
| label | string | Name of the Batch lookup. |
| date_created | int, Unix time | Creation time of the HLR batch. |
| conneciton_id | int | Connection id. |
| hlr | object | HLR object with the data about the lookup (to and groups). |
| processed | int | Number of processed numbers. |
| status | int | 0 for pending, 1 for in progress and 2 for done. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"label": "Winter customer sendout HLR", "hlr": {"groups": [1,2],"to": ["123456","1234567"]}}' \
"https://api.beepsend.com/2/hlrbatch/"
You need a valid User API-Token to use the "groups" field in the batch request since they are connected to a User and not connections. Read more about Users and Connections. You can still use a Connection token, but you will be limited to using only the "to" field.
Do a HLR lookup on groups or numbers.
You can use HLR Batch Lookup to do lookups on your imported contact groups instead of using 1 or more to MSISDN addresses.
To do a batch lookup on contact groups, just add the hlr parameter groups with the desired group ids.
{
"label": "Winter customer sendout HLR",
"hlr": {
"groups": [
1,
2
]
}
}
{
"id": 24151,
"label": "Winter customer sendout HLR",
"date_created": 1453485600,
"connection_id": 17755,
"hlr": {
"groups": [
1,
2
],
"to": null
},
"processed": 0,
"status": 0
}
| Key | Type | Description |
|---|---|---|
| id | int | Unique sendout id. |
| label | string | Name of the Sendout. |
| date_created | int, Unix time | Creation time of the HLR batch. |
| conneciton_id | int | Connection id. |
| hlr | object | HLR object with the data about your groups and to. |
| processed | int | Number of processed numbers. |
| status | int | 0 for pending, 1 for in progress and 2 for done. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"label": "Winter customer sendout HLR", "hlr": {"groups": [1,2]}}' \
"https://api.beepsend.com/2/hlrbatch/123"
This call will give a paginated overview of the previously created HLR batches.
GET /2/hlrbatch/GET /2/hlrbatch/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What offset in result set to fetch data from. Default is 0. |
[
{
"id": 24151,
"label": "Winter customer sendout HLR",
"date_created": 1453485600,
"connection_id": 17755,
"hlr": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
]
},
"processed": 42,
"status": 2
},
{
"id": 24150,
"label": "Summer customer sendout HLR",
"date_created": 1467413400,
"connection_id": 17755,
"hlr": {
"groups": [
1
],
"to": [
"123456",
"1234567"
]
},
"processed": 12,
"status": 2
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique batch id. |
| label | string | Name of the Batch lookup. |
| date_created | int, Unix time | Creation time of the HLR batch. |
| conneciton_id | int | Connection id. |
| hlr | object | |
| hlr.to | array (string) | MSISDNs to be HLRed. |
| hlr.groups | array (int) | Contact group ids. |
| processed | int | Number of processed numbers. |
| status | int | 0 for pending, 1 for in progress and 2 for done. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/?<parameter>=<value>"
To fetch a specific batch you only need to supply the unique batch ID to the URL.
This endpoint requires a valid User API-Token. Read more about Users and Connections.
GET /2/hlrbatch/<ID>| Parameter | Type | Description |
|---|---|---|
| ID Required |
int | The unique batch id. |
{
"id": 24151,
"label": "Winter customer sendout HLR",
"date_created": 1453485600,
"connection_id": 17755,
"hlr": {
"groups": [
1,
2
],
"to": [
"123456",
"1234567"
]
},
"processed": 42,
"status": 2
}
| Key | Type | Description |
|---|---|---|
| id | int | Unique batch id. |
| label | string | Name of the Batch lookup. |
| date_created | int, Unix time | Creation time of the HLR batch. |
| conneciton_id | int | Connection id. |
| hlr | object | |
| hlr.to | array (string) | MSISDNs to be HLRed. |
| hlr.groups | array (int) | Contact group ids. |
| processed | int | Number of processed numbers. |
| status | int | 0 for pending, 1 for in progress and 2 for done. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/123"
This endpoint requres a valid User API-Token. Read more about Users and Connections.
This call will give a paginated overview of the results in an HLR batch, complete with status, errorcode, mcc, mnc, number and contact details (if the number exists in user contacts).
GET /2/hlrbatch/<ID>/results/GET /2/hlrbatch/<ID>/results/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What offset in result set to fetch data from. Default is 0. |
[
{
"dlr": {
"status": "DELIVRD",
"error": 0
},
"mccmnc": {
"mcc": "240",
"mnc": "07"
},
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
},
{
"dlr": {
"status": "DELIVRD",
"error": 0
},
"mccmnc": {
"mcc": "240",
"mnc": "07"
},
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
},
{
"dlr": {
"status": "DELIVRD",
"error": 0
},
"mccmnc": {
"mcc": "240",
"mnc": "07"
},
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
}
]
| Key | Type | Description |
|---|---|---|
| dlr | object | |
| dlr.status | string | Response status. |
| dlr.error | int | Response code |
| mccmnc | object | |
| mccmnc.mcc | string | Mobile Country Code |
| mccmnc.mnc | string | Mobile Network Code |
| to | object | |
| to.number | string | Recipient number |
| to.contact | object | |
| to.contact.firstname | string | First name of contact. |
| to.contact.lastname | string | Last name of contact. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/123/results/"
This endpoint requires a valid User API-Token. Read more about Users and Connections.
This call will give all results in an hlr batch formatted as CSV.
GET /2/hlrbatch/<ID>/results.csv| Parameter | Type | Description |
|---|---|---|
| delimiter Optional |
string | What delimiter to use for the csv output. (Default: , <comma>) |
Fields in the CSV file are
| Field | Description |
|---|---|
| number | Recipient's number. |
| firstname | First name of the contact (might be empty). |
| lastname | Last name of the contact (might be empty). |
| delivery_status | Status of the HLR result. |
| delivery_error | Response code of the HLR result. |
| mcc | Mobile Country Code. |
| mnc | Mobile Network Code. |
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/123/results.csv"
Perform a dry run of SMS sending or HLR lookups.
POST /2/sms/validateSee Send SMS for request instructions.
If validation is successful, the response will be sent like below. Since the SMS was never sent id will always be null.
{
"id": null,
"to": "502040",
"from": "Sir Lancelot",
"errors": null
}
If validation is unsuccessful, errors would be an array instead of null.
If any messages fail to validate, this endpoint will return the status code 403.
{
"id": null,
"to": "5020assd40",
"from": "Beepsend",
"errors": [
{
"code": 1031,
"description": "\"to\" must be a numeric value"
}
]
}
If you want to validate multiple messages you need to use our batch endpoint
POST /2/batch/validateIf validation is successful, the response will be sent like below. Since the SMS was never sent id will always be null.
{
"id": null,
"batch_label": "My custom name for my batch",
"to": "502040",
"from": "lolboll",
"errors": null
}
If validation is unsuccessful, errors would be an array instead of null.
If any messages fail to validate, this endpoint will return the status code 403.
{
"id": null,
"batch_label": "My custom name for my batch",
"to": "5020assd40",
"from": "Beepsend",
"errors": [
{
"code": 1031,
"description": "\"to\" must be a numeric value"
}
]
}
POST /2/hlr/validateSee instructions for HLR.
If validation is successful, the response will be sent like below. Since the HLR lookup was never sent id will always be null.
{
"id": null,
"msisdn": "46736007518",
"errors": null
}
If validation is unsuccesful, errors would be an array instead of null.
If any lookups fail to validate, this endpoint will return the status code 403.
{
"id": null,
"msisdn": "5020assd40",
"errors": [
{
"code": 1031,
"description": "\"msisdn\" must be a numeric value"
}
]
}
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"batch_label": "My custom name for batch", "to": "46736007518", "message": "Hello World! 你好世界", "from": "Beepsend", "send_time": 1383225355, "encoding": "UTF-8", "receive_dlr": false}' \
"https://api.beepsend.com/2/sms/validate"
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"msisdn": "46736007518"}' \
"https://api.beepsend.com/2/hlr/validate/"
$client->message->validate(
{TO},
{FROM},
{MESSAGE},
{CONNECTION},
{ENCODING},
{OPTIONS}
);
$client->hlr->validate({MSISDN});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$options = array(
'batch_label' => 'My custom name for my batch',
);
$connectionId = 1;
$message = $client->message->validate(
46736007518,
'TonyMontana',
'Hello World! 你好世界!',
'UTF-8',
$options
);
You can also set null for connection id and the "me" alias will be used to reference your default SMS connection
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$response = $client->hlr->validate(46736007518);
You can also set null for connection id and the "me" alias will be used to reference your default HLR connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().validate({FROM}, {TO}, {MESSAGE}, {ENCODING}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.hlr().validate({MSISDN}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
/* SMS validation example */
var from = "Beepsend";
var to = "46736007518";
var message = "Hello World!";
var encoding = "UTF-8";
/* Aditional options */
var options = {
"batch_label": "My custom name for my batch",
"receive_dlr": false
};
client.messages().validate(from, to, message, encoding, options).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
/* HLR validation example */
var msisdn = "46406007500";
client.hlr().validate(msisdn).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSMessage
- (void)validateMessageOnCompletion:(void(^)(BSMessage *message, NSArray *errors))block;
@end
@interface BSHLR
- (void)validateHLRForNumberOnCompletion:(void(^)(BSHLR *hlr, NSArray *errors))block;
@end
SMS validation
BSMessage *sms = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
[sms validateMessageOnCompletion:^(BSMessage *message, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSMessage object)
}
else {
//Handle error (array of BSError objects)
}
}];
HLR validation
BSHLR *hlr = [[BSHLR alloc] initHLRWithNumber:@"01234567890"];
[hlr validateHLRForNumberOnCompletion:^(BSHLR *hlr, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSHLR object)
}
else {
//Handle error (array of BSError objects)
}
}];
Callbacks is our way of giving you back results for operations that typically are asynchronous or take a longer time. One common use-case for callbacks is to get delivery receipts of SMS. The Callback is a webpage located on a public URL which will listen for incoming requests with a JSON payload. Without a proper callback handling you will not be able to get delivery confirmations. This chapter describes in more detail how to configure your callback for delivery receipts, incoming SMS (MO) and HLR results.
Setup callback url for delivery reports.
When a text message is received by the Beepsend SMS Gateway, you will receive a delivery report (also called DR, DN or DLR) once we have attempted delivery. The DR is sent to your specified callback URL by HTTP PUT, POST or GET. This message passing procedure is called callback and gives you statistics for if and when a message was delivered. If you don't want delivery notifications you should leave the callback URL-field empty. The first thing to do is specifying the callback URL for your connection on the admin page.
POST http://youraddress.com/
PUT http://youraddress.com/<sms id>
GET http://youraddress.com/?id=<sms id> {...}Please visit the Beepsend Customer Portal to set up your callback URL and method.
The delivery-notification you will receive after each sent message contains five parameters:
| Key | Type | Description |
|---|---|---|
| id | string | Message Id. |
| batch | array | null | Object with id and label or null. |
| timestamps.sms.in | int | When the SMS reached Beepsend. |
| timestamps.sms.delivered | int | When DLR reached Beepsend. |
| timestamps.dlr_out | int | When DLR callback was sent. |
| dlr.status | string | Response status. |
| dlr.error | int | Response code. |
| to.address | string | Destination address |
| to.ton | int | Destination Type of Number. |
| to.npi | int | Destination Numbering Plan Identifier. |
Via GET these parameters will be appended to the URL in a querystring. If using POST or PUT they will be sent as a JSON request shown below.
{
"id": "128452",
"batch": null,
"timestamps": {
"sms": {
"in": 1383225355,
"delivered": 1383225359
},
"dlr_out": 1383225359
},
"dlr": {
"status": "DELIVRD",
"error": 0
},
"to": {
"address": "46736007600",
"ton": 1,
"npi": 1
}
}
Delivery notification can also contain optional information per customer request:
| Key | Type | Description |
|---|---|---|
| mccmnc.mcc | string | MCC, Destination country code. |
| mccmnc.mnc | string | MNC, Destination operator code. |
| imsi | int | The IMSI of the handset if available. First five characters and then zeroes. |
| price | float | Message price. |
After you have received the DLR, your webserver should send http response 200 OK
This tells us that you have received the DLR and we can flag the transaction complete.
Mobile Originated SMS is sent by end user phone to registered shortcode or longcode.
You need to have a 2-way Number to be able to recieve a mobile originated SMS.
The mobile operator will forward the message to the Beepsend SMS platform. Beepsend's SMS gateway will then send it to your specified callback URL by HTTP POST, PUT or GET.
POST http://youraddress.com/
PUT http://youraddress.com/
GET http://youraddress.com/?from=<Sender MSISDN> {...}Please visit the Beepsend Customer Portal to set up your callback URL and method.
The Beepsend SMS Gateway will initialise an HTTP request to your URL with the following parameters.
| Key | Type | Description |
|---|---|---|
| id | string | Message Id. |
| timestamps.sms.in | int | When MO sms reached Beepsend. |
| from | string | Sender MSISDN. |
| to | string | Destination short or longcode. |
| message | string | MO SMS body. Plain text URL encoded. |
| hex_body | string | Hex encoded string containing the raw body of MO sms (or MO sms part if it's multipart message). |
| encoding | string | Message encoding. ‘Windows-1252’ if possible. If message contain non latin characters then ‘Unicode’ (UTF-16 BE). |
Via GET these parameters will be appended to the URL in a querystring. If using POST or PUT they will be sent as a JSON request shown below.
{
"id":"07595980013893439611559146736007518",
"timestamps": {
"sms": {
"in": 1383225355
}
},
"from": "46406007500",
"to": "461111111",
"message": "Hello World!",
"hex_body": "48656c6c6f20576f726c6421",
"encoding": "Windows-1252"
}
MO sms can also contain optional information per customer request:
| Key | Type | Description |
|---|---|---|
| mccmnc.mcc | string | MCC, Destination country code. |
| mccmnc.mnc | string | MNC, Destination operator code. |
| imsi | int | The IMSI of the handset if available. First five characters and then zeroes. |
| price | float | Message price. |
After you have received the MO SMS, your webserver should send http response 200 OK
This tells us that you have received the MO SMS and we can flag the transaction complete.
Once all the HLR requests has been made our system will send the results to the DLR URL defined as callback
for the specified HLR connection. Callbacks are made for each submitted number and returned as they are
completed. The result payload is:
{
"id": "08087780013866630151559112345",
"timestamps": {
"hlr": {
"in": 1383225355,
"delivered": 1383225359
},
"dlr_out": 1383225359
},
"dlr": {
"status": "DELIVRD",
"error": 0
},
"mccmnc": {
"mcc": "402",
"mnc": "02"
},
"to": {
"address": "46736007500",
"ton": 1,
"npi": 1
},
"imsi": "423900000000000000000",
"ported": true,
"roaming": {
"is_roaming": true,
"mcc": "240",
"mnc": "01"
},
"prefix": {
"mcc": "402",
"mnc": "02"
}
}
| Key | Type | Description |
|---|---|---|
| id | string | The id of the transaction. |
| timestamps.hlr.in | int | When the HLR reached Beepsend. |
| timestamps.hlr.delivered | int | When HLR response reached Beepsend. |
| timestamps.dlr_out | int | When callback was sent. |
| dlr.status | string | Response status. |
| dlr.error | int | Response code. |
| mccmnc.mcc | string | Mobile Country Code for the handset. |
| mccmnc.mnc | string | Mobile Network Code for the handset. |
| to.address | string | The number you did the HLR on. |
| to.ton | int | The numbers Type of Number. |
| to.npi | int | The numbers Numbering Plan Identifier. |
| imsi | int | The IMSI of the handset if available. First five characters and then zeroes. |
| ported | bool | True if the number seems to be ported, false if not. |
| roaming | object | Return roaming information |
| roaming.is_roaming | bool | True if the number is roaming, false if not. |
| roaming.mcc | string | Mobile Country Code of current phone location |
| roaming.mnc | string | Mobile Network Code of current phone location |
| prefix | object | Return Mcc Mnc assigned to msisdn prefix. |
| prefix.mcc | string | Mobile Country Code assigned to msisdn prefix. |
| prefix.mnc | string | Mobile Network Code assigned to msisdn prefix. |
The following fields can be included by request.
| Key | Type | Description |
|---|---|---|
| price | float | HLR price. |
After you have received the DLR, your webserver should send http response 200 OK
This tells us that you have received the DLR and we can flag the transaction complete.
This call will give you accumulated statistics for all messages sent between two specified dates and the accumulated cost for these in Euro (€). The call counts all messages submitted via SMPP and HTTP alike.
The call supports a summary for available connections based on a User Token, a specific connection or using the short hand alias "me" for the authenticated connection, will return you statistics for user default connection.
This call does not consider delivery statistics and should merely be used for aggregated views on traffic. If no ID is provided the return data set is a list of connections.
GET /2/analytics/summary/<ID>
GET /2/analytics/summary/me
GET /2/analytics/summary/| Parameter | Type | Description |
|---|---|---|
| from_date Optional |
int | Begin Date in Unix time. |
| to_date Optional |
int | End dates in Unix time. |
{
"connection": "customer-1",
"count": 100,
"price": 4.38
}
| Key | Type | Description |
|---|---|---|
| connection | string | The connection label |
| count | int | Number of messages during the time interval. |
| price | float | Total cost for traffic between given interval in Euro (€). |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/analytics/summary/"
$client->analytic->summary({CONNECTION}, {FROM_DATE}, {TO_DATE});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$fromDate = 1388534400;
$toDate = 1619984000;
$summary = $client->analytic->summary($connectionId, $fromDate, $toDate);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.analytic().summary({CONNECTION}, {FROM_DATE}, {TO_DATE}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.analytic().summary().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getNetworkDetailsFromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
mccmnc:(BSMCCMNC *)mccmnc
withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
@end
@interface BSConnection
- (void)getNetworkDetailsFromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
mccmnc:(BSMCCMNC *)mccmnc
withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
@end
//Use current user to check analytics summary
[[BSUser currentUser] getAnalyticsSummaryFromDate:[NSDate date] toDate:[NSDate date] withCompletionBlock:^(NSArray *statistics, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSAccumulatedStatistics objects)
}
else {
//Handle error (array of BSError objects)
}
}];
//You can use default connection or any other connection for analytics summary
[[BSConnection currentConnection] getAnalyticsSummaryFromDate:[NSDate date] toDate:[NSDate date] withCompletionBlock:^(NSArray *statistics, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSAccumulatedStatistics objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This call will give you granular delivery statistics for all messages sorted by each recipient network between two specified dates. The call counts all messages submitted via SMPP and HTTP alike.
The call supports parameter to specify a list of MCC and/or MNC. If these parameters are omitted all MCC and MNC that has traffic will be returned.
The call supports a summary for available connections on used token. Either a specific Connection ID or using the short hand alias "me" for the authenticated connection if Connection token was used when authenticating or the default connection if User token was used instead. If no ID is provided all connections available is returned as list.
GET /2/analytics/network/<ID>
GET /2/analytics/network/me
GET /2/analytics/network/| Parameter | Type | Description |
|---|---|---|
| from_date Optional |
int | Begin Date in Unix time. |
| to_date Optional |
int | End dates in Unix time. |
| MCC Optional |
string | Mobile Country Code |
| MNC Optional |
string | Mobile Network Code |
[
{
"mccmnc": {
"mcc": "648",
"mnc": "03"
},
"statistics": {
"delivered": 100,
"mo": 0,
"expired": 12,
"unknown": 20,
"rejected": 0,
"undelivered": 10,
"no_dlr": 0
},
"total": 142
}
]
| Key | Type | Description |
|---|---|---|
| mccmnc.mnc | string | Mobile Country Code |
| mccmnc.mcc | string | Mobile Network Code |
| statistics.delivered | int | Amount of messages with status delivered to handset |
| statistics.mo | int | Incoming messages from Operator |
| statistics.expired | int | Amount of messages that suffered time out |
| statistics.unknown | int | Failed messages without a clear error |
| statistics.rejected | int | Messages not accepted by Operator |
| statistics.undelivered | int | Failed messages. Unlike unknown, an error code was returned |
| statistics.no_dlr | int | Messages still in the process of sending |
| total | int | Total amount of messages for the MCC MNC |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/analytics/network/"
$client->analytic->network({CONNECTION}, {FROM_DATE}, {TO_DATE}, {MCC}, {MNC});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$fromDate = 1388534400;
$toDate = 1619984000;
$summary = $client->analytic->network($connectionId, $fromDate, $toDate);
You can also omit connection id and then we will use the "me" alias to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.analytic().network({CONNECTION}, {FROM_DATE}, {TO_DATE}, {MCC}, {MNC}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.analytic().network().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getNetworkDetailsFromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
mccmnc:(BSMCCMNC *)mccmnc
withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
@end
@interface BSConnection
- (void)getNetworkDetailsFromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
mccmnc:(BSMCCMNC *)mccmnc
withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
@end
//Use current user to check network analytics
[[BSUser currentUser] getNetworkDetailsFromDate:[NSDate date] toDate:[NSDate date] mccmnc:nil withCompletionBlock:^(NSArray *networkDetails, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSNetworkDetails objects)
}
else {
//Handle error (array of BSError objects)
}
}];
//You can use default connection or any other connection for network analytics
[[BSConnection currentConnection] getNetworkDetailsFromDate:[NSDate date] toDate:[NSDate date] mccmnc:nil withCompletionBlock:^(NSArray *networkDetails, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSNetworkDetails objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This call will give you delivery statistics for a whole sendout.
GET /2/analytics/sendouts/
GET /2/analytics/sendouts/<ID>GET /2/analytics/sendouts/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from. |
[
{
"id": 23,
"name": "My sendout",
"total": 142,
"statistics": {
"delivered": 100,
"expired": 12,
"unknown": 20,
"rejected": 0,
"undelivered": 10,
"no_dlr": 0
},
"total_responses": 10,
"responses": [
{
"text": "yes",
"count": 7
},
{
"text": "no",
"count": 3
}
]
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique sendout id |
| name | string | sendout name |
| total | int | Total amount of messages in the sendout |
| statistics.delivered | int | Amount of messages with status delivered to handset |
| statistics.expired | int | Amount of messages that suffered time out |
| statistics.unknown | int | Failed messages without a clear error |
| statistics.rejected | int | Messages not accepted by Operator |
| statistics.undelivered | int | Failed messages. Unlike unknown, an error code was returned |
| statistics.no_dlr | int | Messages still in the process of sending |
| responses_total | int | Number of responses. |
| responses | array | |
| responses.text | string | The content of the response. |
| responses.count | int | The amount of responses with this text. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/analytics/sendouts/"
$client->analytic->batch({BATCH_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$fromDate = 1388534400;
$toDate = 1619984000;
$analytics = $client->analytic->batch();
/* For getting analytics for specific batch set batch id */
$batchId = 23;
$analytics = $client->analytic->batch($batchId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.analytic().batch({BATCH_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var batchId = 23;
client.analytic().batch(batchId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSBatch
- (void)getDeliveryStatisticsWithCompletionBlock:(void(^)(NSArray *statistics, NSArray *errors))block;
@end
BSBatch *batch = [[BSBatch alloc] initWithID:@"1234" andLabel:@"batch"];
[batch getDeliveryStatisticsWithCompletionBlock:^(NSArray *statistics, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSStatistics objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This call will give you delivery statistics for a HLR batch.
GET /2/analytics/hlrbatch/
GET /2/analytics/hlrbatch/<ID>GET /2/analytics/hlrbatch/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from. |
[
{
"id": 23,
"name": "My hlr batch",
"total": 142,
"statistics": {
"delivered": 100,
"expired": 12,
"unknown": 20,
"rejected": 0,
"undelivered": 10,
"no_dlr": 0
}
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique batch id |
| name | string | HLR batch name |
| total | int | Total amount of HLRs in the sendout |
| statistics | object | |
| statistics.delivered | int | Amount of HLRs with status delivered to handset |
| statistics.expired | int | Amount of HLRs that suffered time out |
| statistics.unknown | int | Failed HLRs without a clear error |
| statistics.rejected | int | HLRs not accepted by Operator |
| statistics.undelivered | int | Failed HLRs. Unlike unknown, an error code was returned |
| statistics.no_dlr | int | HLRs still in the process of sending |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/analytics/hlrbatch/"
This endpoint requres a valid User API-Token. Read more about Users and Connections.
List your user conversations.
GET /2/conversations/GET /2/conversations/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from. |
[
{
"id": "46736007500-46736000005",
"to": "46736007500",
"from": {
"number": "46736000005",
"contact": {
"id": 10,
"firstname": "Foo",
"lastname": "Bar"
}
},
"body": "Hi. This is a test message.",
"timestamp": 1383225355
}
]
| Key | Type | Description |
|---|---|---|
| id | string | Unique ID for this conversation. Based on to and from values. |
| to | string | Your system phone number. |
| from | object | |
| from.number | string | The receiving number. |
| from.contact | object | |
| from.contact.id | int | null | Id of the matching contact, if any. |
| from.contact.firstname | string | null | Firstname of contact. |
| from.contact.lastname | string | null | Lastname of contact. |
| body | string | Last received body from the |
| timestamp | int | Unixtime of the last received message. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X GET "https://api.beepsend.com/2/conversations/"
$client->message->conversations();
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$conversations = $client->message->conversations();
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().conversations().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.messages().conversations().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getConversationsOnCompletion:(void(^)(NSArray *conversations, NSArray *errors))block;
@end
[[BSUser currentUser] getConversationsOnCompletion:^(NSArray *conversations, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSConversation objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
List all messages sent back and forth in to a single contact/number.
GET /2/conversations/<id>The items list is paginated and this endpoint accepts the same parameters as
sms lookup.
{
"id": "46736007500-46736000005",
"to": "46736007500",
"from": {
"number": "46736000005",
"contact": {
"id": 10,
"firstname": "Foo",
"lastname": "Bar"
}
},
"body": "Hi. This is a test message.",
"timestamp": 1383225355,
"items": [
{
"id": "12345",
"batch": null,
"body": "Hello World!",
"connection": {
"id": 7,
"label": "superman-connection"
},
"to": {
"address": "46406007500",
"ton": 1,
"npi": 1
},
"from": {
"address": "Beepsend",
"ton": 1,
"npi": 1
},
"validity_period": "131102072704000-",
"data_coding": 3,
"timestamps": {
"sms": {
"in": 1383225355,
"delivered": null
},
"dlr_out": null
},
"dlr": {
"status": null,
"error": null
},
"price": 0.068,
"mccmnc": {
"mcc": "240",
"mnc": "01"
}
}
]
}
| Key | Type | Description |
|---|---|---|
| id | string | Unique ID for this conversation. Based on to and from values. |
| to | string | Your system phone number. |
| from | object | |
| from.number | string | The receiving number. |
| from.contact | object | |
| from.contact.id | int | null | Id of the matching contact, if any. |
| from.contact.firstname | string | null | Firstname of contact. |
| from.contact.lastname | string | null | Lastname of contact. |
| body | string | Last received body from the |
| items | array | A list of sms objects |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X GET "https://api.beepsend.com/2/conversations/1"
$client->message->fullConversation({CONVERSATION_ID}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$conversationId = 123;
$conversations = $client->message->conversations($conversationId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().conversation({CONVERSATION_ID}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var conversationId = 1;
client.messages().conversation(conversationId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)getDetailsForConversation:(BSConversation *)conversation onCompletion:(void(^)(BSConversation *fullConversation, NSArray *errors))block;
@end
[[BSUser currentUser] getDetailsForConversation:conversation onCompletion:^(BSConversation *fullConversation, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSConversation object that contains array of BSSMSLookup objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Get all contacts belonging to your user. Specify a group id or name to filter your results. To get a specific contact by number, use /msisdn/. When fetching all contacts the endpoint is paginated, add parameters to the query string to browse contacts.
GET /2/contacts/<id>
GET /2/contacts/?<parameter>=<value>
GET /2/contacts/msisdn/<msisdn>| Parameter | Type | Description |
|---|---|---|
| group Optional |
int | string | Group id or name. |
| since_id Optional |
int | Returns results more recent than the specified id. |
| max_id Optional |
int | Returns results with an id older than or equal to the specified id. |
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from (as an alternative to max_id). |
| sort Optional |
string | Sorting of the dataset. Available keys: name, id. Can be prepended with + or - to change the sorting direction (+ ASC, - DESC). |
| include_global Optional |
boolean | Include contacts that belong to global groups. Global groups are shared between users under the same customer. false by default. |
[
{
"id": 22594418,
"msisdn": "46736007518",
"name": "Phone",
"groups": []
},
{
"id": 22594420,
"msisdn": "46406007500",
"name": "Beepsend",
"groups": [
{
"id": 213,
"name": "Beepnumbers"
}
]
}
]
| Key | Type | Description |
|---|---|---|
| id | id | The id of the group. |
| msisdn | string | Mobile number. |
| name | string | Contact name. |
| groups | array | List of linked groups. |
| groups.x.id | int | id of a group this contact is linked to. |
| groups.x.name | string | Name of a group this contact is linked to. |
Get all contacts
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X GET "https://api.beepsend.com/2/contacts/"
Get contacts from a certain group
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X GET "https://api.beepsend.com/2/contacts/?group=2"
$client->contact->all({GROUP_ID}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$contacts = $client->contact->all();
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().all({GROUP_ID}, {SORT}, {SINCE_ID}, {MAX_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.contacts().all().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getAllContactsfromGroup:(BSGroup *)group sorted:(NSString *)sort forNextPage:(BOOL)nextPage onCompletion:(void(^)(NSArray *contacts, NSArray *errors))block;
@end
[[BSUser currentUser] getAllContactsfromGroup:nil sorted:@"+" forNextPage:NO onCompletion:^(NSArray *contacts, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSContact objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
POST /2/contacts/| Parameter | Type | Description |
|---|---|---|
| msisdn Required |
string | Mobile number. |
| firstname Optional |
string | Contacts first name. |
| lastname Optional |
string | Contacts last name. |
| groups Optional |
array | List of group objects. |
| groups.x.id Optional |
int | Group id this contact should be linked to. |
{
"msisdn": "1234567",
"firstname": "Example contact"
}
{
"id": 22594443,
"msisdn": "1234567",
"firstname": "Example contact",
"lastname": "",
"groups": [],
"errors": null
}
Status code: 201 created.
Multiple contacts can be added at once.
[
{
"msisdn": "12345",
"firstname": "Multi-example"
},
{
"msisdn": "34525",
"groups": [
{
"id": 1
},
{
"id": 14
}
]
}
]
[
{
"id": 22594444,
"msisdn": "12345",
"firstname": "Multi-example",
"lastname": "",
"groups": [],
"errors": null
},
{
"id": null,
"msisdn": "34525",
"firstname": "",
"lastname": "",
"groups": [
{
"id": 1,
"name": "Customers"
}
{
"id": 14,
"name": "The lorem ipsum group"
}
],
"errors": null
}
]
| Status code | Case |
|---|---|
| 201 | All contacts created successfully. |
| 200 | Some contacts created, check errors. |
| 403 | All contacts failed to be added. |
curl -H "Authorization: Token abc123" -H "Content-Type: application/json" \
-X POST -d '{"msisdn" : "46736007518", "firstname" : "Christian", "lastname" : "Nilsson"}' \
"https://api.beepsend.com/2/contacts/"
$client->contact->add({MSISDN}, {FIRST_NAME}, {LAST_NAME}, {GROUP_IDS});
Note: Groups are optional and always an array of ids when used.
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$contact = $client->contact->add('46736007502', 'Jane', 'Doe', array(137, 235));
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().add({MSISDN}, {FIRSTNAME}, {LASTNAME}, {GROUPS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var msisdn = 1234567;
var firstName = "Example"; //Or you can pass null to method
var lastName = "Contact"; //Or you can pass null to method
var groups = ["1", "2"];
client.contacts().add(msisdn, firstName, lastName, groups).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSContact
@property (nonatomic, strong) NSString *firstName;
@property (nonatomic, strong) NSString *lastName;
@property (nonatomic, strong) NSString *phoneNumber;
- (void)saveContactOnCompletion:(void(^)(BSContact *contact, NSArray *errors))block;
@end
@interface BSUser
- (void)addMultipleContacts:(NSArray *)contacts onCompletion:(void(^)(NSArray *response, NSArray *errors))block;
@end
//create single contact and save it
BSContact *contact = [[BSContact alloc] initContactWithPhoneNumber:@"123456789000" firstName:@"First" lastName:@"Last" group:nil];
[contact saveContactOnCompletion:^(BSContact *contact, NSArray *errors) {
if (!errors || errors.count == 0) {
if (contact.errors && contact.errors.count > 0) {
//Handle errors (array of BSError objects)
}
else {
//Contact successfully added
}
}
else {
//Handle error (array of BSError objects)
}
}];
//For adding multiple contacts create contacts and use user method for adding multiple contacts
BSContact *c1 = [[BSContact alloc] initContactWithPhoneNumber:@"123456789001" firstName:@"First1" lastName:@"Last1" group:nil];
BSContact *c2 = [[BSContact alloc] initContactWithPhoneNumber:@"123456789002" firstName:@"First2" lastName:@"Last2" group:nil];
BSContact *c3 = [[BSContact alloc] initContactWithPhoneNumber:@"123456789003" firstName:@"First3" lastName:@"Last3" group:nil];
[[BSUser currentUser] addMultipleContacts:@[c1, c2, c3] onCompletion:^(NSArray *response, NSArray *errors) {
if (!errors || errors.count == 0) {
for (BSContact *contact in response) {
if (contact.errors && contact.errors.count > 0) {
//Handle errors (array of BSError objects)
}
else {
//Contact successfully added
}
}
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
PUT /2/contacts/<id>| Parameter | Type | Description |
|---|---|---|
| msisdn Optional |
string | Mobile number. |
| firstname Optional |
string | Contacts first name. |
| lastname Optional |
string | Contacts last name. |
| groups Optional |
array | A list of objects containing group ids that should be linked to contact. Can be used to move a contact between groups. NOTE If empty or not specified all contact links will be cleared. |
| groups.x.id Optional |
int | Group id this contact should be linked against. |
This endpoint supports partial updates. Any omitted field in a model will read in the current value.
{
"msisdn": "3456789",
"firstname": "Still an example"
}
{
"id": 22594443,
"msisdn": "3456789",
"firstname": "Still an example",
"lastname": "",
"groups": [],
"errors": null
}
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X PUT \
-d '{"msisdn" : "46736007518", "firstname" : "Christian", "lastname" : "Nilsson"}' \
"https://api.beepsend.com/2/contacts/1"
$client->contact->update({CONTACT_ID}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$contactId = 123;
$options = array(
'msisdn' => 46736007518,
'firstname' => 'Mary'
);
$contact = $client->contact->update($contactId, $options);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().update({CONTACT_ID}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var contactId = 22594443;
var options = {
"msisdn": "3456789",
"firstname": "Still an example"
};
client.contacts().update(contactId, options).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSContact
- (void)updateContactOnCompletion:(void(^)(BSContact *contact, NSArray *errors))block;
@end
BSContact *contact = existingContactToEdit;
contact.firstName = @"NewFirstName";
contact.lastName = @"NewLastName";
contact.phoneNumber = @"012345678900";
[contact updateContactOnCompletion:^(BSContact *contact, NSArray *errors) {
if (!errors || errors.count == 0) {
//Contact successfully updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
DELETE /2/contacts/<id>
This will remove the contact and its link from every group it belonged to. To unlink a contact from a specific group, use Update with only the groups you want or an empty list to remove all links.
204 no content header.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X DELETE "https://api.beepsend.com/2/contacts/1"
$client->contact->delete({CONTACT_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$contactId = 123;
$contact = $client->contact->delete($contactId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().delete({CONTACT_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var contactId = 22594443;
client.contacts().delete(contactId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSContact
- (void)removeContactOnCompletion:(void(^)(BOOL success, NSArray *errors))block;
@end
BSContact *contact = existingContactToDelete;
[contact removeContactOnCompletion:^(BOOL success, NSArray *errors) {
if (!errors || errors.count == 0) {
//Contact successfully deleted
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Get all contact groups belonging to your user. Specify a group id to filter your results. When fetching all groups the endpoint is paginated, add parameters to the query string to browse groups.
GET /2/contacts/groups/<id>
GET /2/contacts/groups/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| since_id Optional |
int | Returns results more recent than the specified id. |
| max_id Optional |
int | Returns results with an id older than or equal to the specified id. |
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| include_global Optional |
boolean | Include global groups that are shared between users under the same customer. false by default. |
[
{
"id": 1,
"name": "Customers",
"contacts_count": 27,
"processing": 1,
"owner": {
"id": 15000,
"name": "Beepsend-user"
},
"global": 0
},
{
"id": 2,
"name": "Others",
"contacts_count": 2,
"processing": 0,
"owner": {
"id": 15000,
"name": "Beepsend-user"
},
"global": 1
}
]
| Key | Type | Description |
|---|---|---|
| id | id | The id of the group. |
| name | string | Contact group name. |
| contacts_count | int | Number of contacts in the group. |
| processing | int | null | This flag is 1 if contacts are being imported, otherwise 0. |
| owner | string | User that owns the group. |
| global | int, 0/1 |
1 means that the group is shared between all users under the same customer. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X GET "https://api.beepsend.com/2/contacts/groups/"
$client->contact->groups({SINCE_ID}, {MAX_ID}, {COUNT});
$client->contact->group({GROUP_ID}, {GROUP_NAME});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$groups = $client->contact->groups();
/* Get single group */
$groupId = 123;
$group = $client->contact->group($groupId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().groups().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.contacts().group({GROUP_ID}, {SINCE_ID}, {MAX_ID}, {COUNT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
/* Get all contact groups belonging to your user */
client.contacts().groups().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
/* Get content of specific group */
var groupId = 1;
client.contacts().group(groupId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getAllGroupsForNextPage:(BOOL)nextPage onCompletion:(void(^)(NSArray *groups, NSArray *errors))block;
- (void)getGroupDetails:(NSString *)groupID onCompletion:(void(^)(BSGroup *group, NSArray *errors))block;
@end
// Get all groups
[[BSUser currentUser] getAllGroupsForNextPage:NO onCompletion:^(NSArray *groups, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSGroup objects)
}
else {
//Handle error (array of BSError objects)
}
}];
// Get details for specific group
[[BSUser currentUser] getGroupDetails:@"1234" onCompletion:^(BSGroup *group, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSGroup object)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
POST /2/contacts/groups/| Parameter | Type | Description |
|---|---|---|
| name Required |
string | Group name. |
| global Optional |
int | 1 makes this group shared between users under the same customer. This can only be changed later by the group owner. |
{
"name": "Important people"
}
{
"id": 2,
"name": "Important people",
"contacts_count": 0,
"processing": 0,
"owner": {
"id": 15000,
"name": "Beepsend-user"
},
"global": 0
}
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"name" : "Important people"}' \
"https://api.beepsend.com/2/contacts/groups/"
$client->contact->addGroup({GROUP_NAME});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$group = $client->contact->addGroup('Important people');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().addGroup({NAME}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var groupName = "Important people";
client.contacts().addGroup(groupName).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSGroup
- (void)saveGroupOnCompletion:(void(^)(BSGroup *group, NSArray *errors))block;
@end
BSGroup *group = [[BSGroup alloc] initGroupWithName:@"Group name"];
[group saveGroupOnCompletion:^(BSGroup *group, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSGroup object)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
PUT /2/contacts/groups/<id>| Parameter | Type | Description |
|---|---|---|
| name Required |
string | Group name. |
| global Optional |
int | 1 makes this group shared between users under the same customer. This can only be changed by the group owner. |
This endpoint supports partial updates. Any omitted field in a model will read in the current value.
{
"name": "Still very important people",
"global": 1
}
{
"id": 2,
"name": "Still very important people",
"contacts_count": 0,
"processing": 0,
"owner": {
"id": 15000,
"name": "Beepsend-user"
},
"global": 1
}
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"name" : "New name of group"}' \
"https://api.beepsend.com/2/contacts/groups/1"
$client->contact->updateGroup({GROUP_ID}, {GROUP_NAME});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$groupId = 123;
$group = $client->contact->updateGroup($groupId, 'Still very important people');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().updateGroup({GROUP_ID}, {NAME}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var groupId = 1;
var groupName = "Important people";
client.contacts().updateGroup(groupId, groupName).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSGroup
- (void)updateGroupOnCompletion:(void(^)(BSGroup *group, NSArray *errors))block;
@end
BSGroup *group = existingGroupToEdit;
[group updateGroupOnCompletion:^(BSGroup *group, NSArray *errors) {
if (!errors || errors.count == 0) {
//Group successfully updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
DELETE /2/contacts/groups/<id>
Note: This will delete the group and all members of it. Make sure to update with a new group_id to move them.
204 no content header.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X DELETE \
"https://api.beepsend.com/2/contacts/groups/1"
$client->contact->deleteGroup({GROUP_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$groupId = 123;
$group = $client->contact->deleteGroup($groupId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.contacts().deleteGroup({GROUP_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var groupId = 1;
client.contacts().deleteGroup(groupId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSGroup
- (void)removeGroupOnCompletion:(void(^)(BOOL success, NSArray *errors))block;
@end
BSGroup *group = existingGroupToDelete;
[group removeGroupOnCompletion:^(BOOL success, NSArray *errors) {
if (!errors || errors.count == 0) {
//Group successfully deleted
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
DELETE /2/contacts/groups/members/<id>
Note: This will delete the members inside the affected group and not the group itself.
204 no content header.
This endpoint requres a valid User API-Token. Read more about Users and Connections.
If the uploaded file contains a header we'll try and parse the names and use that order. If there is no header the ordering below is used as default.
| Number | First name | Last name |
|---|---|---|
| 46760005630 | Malcolm | Reynolds |
If we can't guess the column order or if there are less than 3 columns we'll fall back to use the first column as phone number.
Post /2/contacts/upload/| Parameter | Type | Description |
|---|---|---|
| group_id | int | group id |
| data | string | file with contacts |
curl -v \
-H "Authorization: Token ApiToken123" \
-H "Content-Type: multipart/form-data" \
-F "group_id=<id>" \
-F "data=@path/to/file/christmasCampaign2017.csv" \
https://api.beepsend.com/2/contacts/uploads/
GET /2/contacts/upload/[
{
"id": 4142,
"group": {
"id": 16412,
"name": "easter"
},
"filename": "easter_sendout.csv",
"upload_date": 1469172663,
"report_available": true,
"total": 40001,
"successful": 40001,
"failed": 0,
"skipped": 0,
"status": 2,
"error": null
},
{
"id": 3244,
"group": {
"id": 16003,
"name": "christmas"
},
"filename": "christmas_sendout.csv",
"upload_date": 1469172641,
"report_available": true,
"total": 25000,
"successful": 25000,
"failed": 0,
"skipped": 0,
"status": 2,
"error": null
},
{
"id": 3243,
"group": {
"id": 16003,
"name": "christmas"
},
"filename": "christmas_sendout.gif",
"upload_date": 1469172631,
"report_available": false,
"total": 25000,
"successful": 25000,
"failed": 0,
"skipped": 0,
"status": 3,
"error": "Could not parse uploaded file."
}
]
| Key | Type | Description |
|---|---|---|
| id | id | The id of the upload. |
| group.id | id | The id of the group. |
| group.name | string | Group name. |
| groups | array | List of linked groups. |
| filename | string | Name of the uploaded file. |
| upload_date | int, Unix time | Time of the upload. |
| report_available | boolean | If a upload report is ready. |
| total | int | Number of contacts found. |
| successful | int | Number of successful imports. |
| failed | int | Number of failed imports. |
| skipped | int | Number of skipped contacts due to duplicate entries in the group. |
| status | int | 0=uploaded, 1=uplode job started, 2= finished, 3=failed to import contacts. |
| errors | string / null | error description. |
curl \
-H "Authorization: Token ApiToken123" \
https://api.beepsend.com/2/contacts/uploads/
GET /2/contacts/upload/ {
"id": 4142,
"group": {
"id": 16412,
"name": "easter"
},
"filename": "easter_sendout.csv",
"upload_date": 1469172663,
"report_available": true,
"total": 40001,
"successful": 40001,
"failed": 0,
"skipped": 0,
"status": 2,
"error": null
}
| Key | Type | Description |
|---|---|---|
| id | id | Upload id. |
| group.id | id | Group id. |
| group.name | string | Group name. |
| filename | string | Name of the uploaded file. |
| upload_date | int, Unix time | Time of the upload. |
| report_available | boolean | If a upload report is ready. |
| total | int | Number of contacts found. |
| successful | int | Number of successful imports. |
| failed | int | Number of failed imports. |
| skipped | int | Number of skipped contacts due to duplicate entries in the group. |
| status | int | 0=uploaded, 1=uplode job started, 2= finished, 3=failed to import contacts. |
| errors | string / null | error description. |
curl \
-H "Authorization: Token ApiToken123" \
https://api.beepsend.com/2/contacts/uploads/<id>
GET /2/contacts/upload/<id>/reportGet a detailed report on contacts or rows in your file that we did no upload.
| Line number | Phone number | First name | Last name | comment |
|---|---|---|---|---|
| 2 | 46702137998 | 46702137998 | 46702137998 | Duplicate: Contact already exist in this group. |
| 39 | 1976 | Ryan | Reynolds | Failed: Invalid phone number. |
| 74 | 1944 | Gary | Busey | Failed: Invalid phone number. |
curl \
-H "Authorization: Token ApiToken123" \
https://api.beepsend.com/2/contacts/uploads/<id>/report
This endpoint requres a valid User API-Token. Read more about Users and Connections.
GET /2/search/contacts/?query=search_text| Parameter | Type | Description |
|---|---|---|
| query Required |
string | Will search entries matching on id, msisdn, firstname and lastname. |
| group_id Optional |
int | Specify which group to search in. |
| include_global Optional |
boolean | Include contacts that belong to global groups. Global groups are shared between users under the same customer. false by default. |
| limit Optional |
int | Limit the amount of search results. |
[
{
"id": 22594418,
"msisdn": "46736007518",
"name": "Phone",
"groups": []
},
{
"id": 22594420,
"msisdn": "46406007500",
"name": "Beepsend",
"groups": [
{
"id": 213,
"name": "Beepnumbers"
}
]
}
]
| Key | Type | Description |
|---|---|---|
| id | id | The id of the group. |
| msisdn | string | Mobile number. |
| name | string | Contact name. |
| groups | array | List of linked groups. |
| groups.x.id | int | id of a group this contact is linked to. |
| groups.x.name | string | Name of a group this contact is linked to. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/search/contacts/?query=Beepsend"
$client->search->contacts({QUERY}, {GROUP_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$contacts = $client->search->contacts(46736007518);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.search().contacts({QUERY}, {GROUP_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var query = "Test contact";
client.search().contacts(query).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)searchContactsWithQuery:(NSString *)query inGroup:(BSGroup *)group limit:(NSNumber *)limit onCompletion:(void(^)(NSArray *results, NSArray *errors))block;
@end
[[BSUser currentUser] searchContactsWithQuery:@"con" inGroup:nil limit:@100 onCompletion:^(NSArray *results, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSContact objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
GET /2/search/contact_groups/?query=search_text| Parameter | Type | Description |
|---|---|---|
| query Required |
string | Will search entries with matching name. |
| include_global Optional |
boolean | Include global groups that are shared between users under the same customer. false by default. |
| limit Optional |
int | Limit the amount of search results. |
[
{
"id": 1,
"name": "Customers",
"contacts_count": 27,
"processing": 1,
"owner": {
"id": 15000,
"name": "Beepsend-user"
},
"global": 0
},
{
"id": 2,
"name": "Others",
"contacts_count": 2,
"processing": 0,
"owner": {
"id": 15000,
"name": "Beepsend-user"
},
"global": 1
}
]
| Key | Type | Description |
|---|---|---|
| id | id | The id of the group. |
| name | string | Contact group name. |
| contacts_count | int | Number of contacts in the group. |
| processing | int | null | This flag is 1 if contacts are being imported, otherwise 0. |
| owner | string | User that owns the group. |
| global | int, 0/1 |
1 means that the group is shared between all users under the same customer. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/search/contact_groups/?query=Test"
$client->search->groups({QUERY});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$contacts = $client->search->groups('Test');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.search().groups({QUERY}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var query = "Test";
client.search().groups(query).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)searchGroupsWithQuery:(NSString *)query limit:(NSNumber *)limit onCompletion:(void(^)(NSArray *results, NSArray *errors))block;
@end
[[BSUser currentUser] searchGroupsWithQuery:@"group" limit:@100 onCompletion:^(NSArray *results, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSGroup objects)
}
else {
//Handle error (array of BSError objects)
}
}];
External recipient Emails for pricelist notifications
This endpoint requres a valid User API-Token. Read more about Users and Connections.
By default, all pricelist and wallet notifications will be sent to the email registered to your user. If you wish to have updates sent to more emails you can add external recipients.
Get a list of your external emails.
GET /2/wallets/<wallet id>/emails/[
{
"id": 1,
"email": "support@beepsend.com"
},
{
"id": 2,
"email": "example@beepsend.com"
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Email id. |
| string | Email address. |
Get details for a specific wallet
GET /2/wallets/<wallet id>/emails/<email id>| Parameter | Type | Description |
|---|---|---|
| id | int | Id of the requested email |
| string | Id of the requested email |
{
"id": 1,
"email": "support@beepsend.com"
}
| Key | Type | Description |
|---|---|---|
| id | int | Email id. |
| string | Email address. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/wallets/1/emails/"
$client->wallet->notifications({WALLET_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$walletId = 123;
$emails = $client->wallet->notifications($walletId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().notifications({WALLET_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var walletId = 1;
client.wallet().notifications(walletId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSWallet
- (void)getEmailsOnCompletion:(void(^)(NSArray *emails, NSArray *errors))block;
- (void)getEmailWithID:(NSString *)emailID onCompletion:(void(^)(BSEmail *email, NSArray *errors))block;
@end
//List all emails associated with wallet
BSWallet *wallet = walletToListEmails;
[wallet getEmailsOnCompletion:^(NSArray *emails, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSEmail objects)
}
else {
//Handle error (array of BSError objects)
}
}];
//Check for email with given ID
[wallet getEmailWithID:@"1234" onCompletion:^(BSEmail *email, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSEmail object)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
POST /2/wallets/<wallet id>/emails/| Parameter | Type | Description |
|---|---|---|
| email Required |
string | Email address you want to add as a recipient |
{
"email": "mailman@beepsend.com"
}
{
"id": 3,
"email": "mailman@beepsend.com"
}
| Key | Type | Description |
|---|---|---|
| id | int | Email id. |
| string | Email address. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X POST \
-d '{"email": "mailman@beepsend.com"}' \
"https://api.beepsend.com/2/wallets/1/emails/"
$client->wallet->addNotificationEmail({WALLET_ID}, {EMAIL});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$walletId = 123;
$email = $client->wallet->addNotificationEmail($walletId, 'mailman@beepsend.com');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().addNotificationEmail({WALLET_ID}, {EMAIL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var walletId = 1;
var email = "mailman@beepsend.com";
client.wallet().addNotificationEmail(walletId, email).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSWallet
- (void)addEmail:(NSString *)email onCompletion:(void(^)(BSEmail *email, NSArray *errors))block
@end
BSWallet *wallet = walletToAddNewEmail;
[wallet addEmail:@"email@mail.com" onCompletion:^(BSEmail *email, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSHLR object)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
DELETE /2/wallets/<wallet id>/emails/<email id>
204 no content header.
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X DELETE \
"https://api.beepsend.com/2/wallets/1/emails/2"
$client->wallet->deleteNotificationEmail({WALLET_ID}, {EMAIL});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$walletId = 123;
$emailId = 12;
$email = $client->wallet->deleteNotificationEmail($walletId, $emailId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().deleteNotificationEmail({WALLET_ID}, {EMAIL_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var walletId = 1;
var emailId = 2;
client.wallet().deleteNotificationEmail(walletId, emailId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSWallet
- (void)removeEmail:(BSEmail *)email onCompletion:(void(^)(BOOL success, NSArray *errors))block;
@end
BSWallet wallet = walletToRemoveEmail;
BSEmail *email = emailToDelete;
[wallet removeEmail:email onCompletion:^(BOOL success, NSArray *errors) {
if (!errors || errors.count == 0) {
//Email successfully deleted
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Get the info for your wallet.
GET /2/wallets/
GET /2/wallets/<wallet id>{
"id": 1,
"name": "Beepsend new wallet",
"balance": 47.60858,
"notify_limit": 10,
"max_negative_balance": 0,
"topup_limit": {
"limit": 20,
"interval": {
"amount": 0,
"seconds": 86400
}
},
"users": [
{
"id": 1,
"name": "Beep Beepson",
"email": "user@beepsend.se"
}
],
"connections": [
{
"system_id": "beepsend",
"name": "beepsend-connection",
"id": 1
}
]
}
| Key | Type | Description |
|---|---|---|
| id | int | Wallet id. |
| name | string | Name of the wallet. |
| balance | float | Current balance. In Euro (€). |
| notify_limit | float | When balance is equal to or below this value notification mails is sent to all users of type Financial Contact. |
| max_negative_balance | float | The allowed negative balance for your wallet. |
| topup_limit.limit | int | The maximum allowed amount to top up within a 24 hour period. |
| topup_limit.interval.amount | float | Amount topped up so far within the last 24h period (period started topup.interval.seconds seconds ago) |
| topup_limit.interval.seconds | int | Number of seconds from now that is used to summarize the amount topped up so far (defaults to 86400s = 24h). |
| users | array | Users which will receive warning notification when low balance. |
| users.email | string | Email address that will receive notification emails. |
| users.name | string | User name |
| users.id | int | User ID. |
| connections | array | Linked connections. |
| connections.system_id | string | Connection login name. Used for SMPP and HTTP v1 api. |
| connections.name | string | Connection name. |
| connection.id | int | Connection ID. |
Get all wallets connected to account
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/wallets/"
Get specific wallet
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/wallets/1"
$client->wallet->all();
$client->wallet->get({WALLET_ID});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
/* Get all wallets */
$wallets = $client->wallet->all();
/* Get single wallet */
$walletId = 123;
$wallet = $client->wallet->get($walletId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().all().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.wallet().get({WALLET_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
/* Get all wallets connected to account */
client.wallet().all().then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
/* Get specific wallet by provided id */
var walletId = 1;
client.wallet().get(walletId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSUser
- (void)getAvailableWalletsOnCompletion:(void(^)(NSArray *wallets, NSArray *errors))block;
- (void)getWalletDetailsForID:(NSString *)walletID onCompletion:(void(^)(BSWallet *wallet, NSArray *errors))block;
@end
Get list of wallets
[[BSUser currentUser] getAvailableWalletsOnCompletion:^(NSArray *wallets, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSWallet objects)
}
else {
//Handle error (array of BSError objects)
}
}];
Get wallet details
[[BSUser currentUser] getWalletDetailsForID:@"1234" onCompletion:^(BSWallet *wallet, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSWallet object)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Update wallet settings.
PUT /2/wallets/<wallet id>| Parameter | Type | Description |
|---|---|---|
| name Optional |
string | Wallet name. |
| notify_limit Optional |
int | At what balance level Beepsend should send a notification email about low balance. Email will be sent to your Financial Contact user as well as your external subscribers. |
If you'd like to update your balance, see Wallet Topup
This endpoint supports partial updates. Any omitted field in a model will read in the current value.
{
"name": "Beepsend new wallet",
"notify_limit": 10
}
{
"id": 1,
"name": "Beepsend new wallet",
"balance": 47.60858,
"notify_limit": 10,
"max_negative_balance": 0,
"topup_limit": {
"limit": 20,
"interval": {
"amount": 0,
"seconds": 86400
}
},
"users": [
{
"id": 1,
"name": "Beep Beepson",
"email": "user@beepsend.se"
}
],
"connections": [
{
"system_id": "beepsend",
"name": "beepsend-connection",
"id": 1
}
]
}
| Key | Type | Description |
|---|---|---|
| id | int | Wallet id. |
| name | string | Name of the wallet. |
| balance | float | Current balance. In Euro (€). |
| notify_limit | float | When balance is equal or below this value a notification email will be sent to all listed users. |
| max_negative_balance | float | The allowed negative balance for your wallet. |
| topup_limit.limit | int | The maximum allowed amount to top up within a 24 hour period. |
| topup_limit.interval.amount | float | Amount topped up so far within the last 24h period (period started topup.interval.seconds seconds ago) |
| topup_limit.interval.seconds | int | Number of seconds from now that is used to summarize the amount topped up so far (defaults to 86400s = 24h). |
| users | array | Users which will receive warning notification when low balance. |
| users.email | string | Email address that will receive notification emails. |
| users.name | string | User name |
| users.id | int | User ID. |
| connections | array | Linked connections. |
| connections.system_id | string | Connection login name. Used for SMPP and HTTP v1 api. |
| connections.name | string | Connection name. |
| connection.id | int | Connection ID. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X PUT \
-d '{"name": "Beepsend new wallet", "notify_limit": 10}' \
"https://api.beepsend.com/2/wallets/1"
$client->wallet->update({WALLET_ID}, {NAME}, {NOTIFY_LIMIT});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$walletId = 123;
$wallet = $client->wallet->update($walletId, 'Beepsend new wallet', 10);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().update({WALLET_ID}, {NAME}, {NOTIFY_LIMIT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var walletId = 1;
var name = "new wallet name";
var notifyLimit = 10;
client.wallet().update(walletId, name, notifyLimit).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSWallet
@property (nonatomic, strong) NSString *name;
@property (nonatomic, strong) NSNumber *minimumBalanceForNotification;
- (void)updateWalletOnCompletion:(void(^)(BSWallet *wallet, NSArray *errors))block;
@end
BSWallet *wallet = walletToUpdate;
wallet.name = @"wallet new name";
wallet.minimumBalanceForNotification = @0.5;
[wallet updateWalletOnCompletion:^(BSWallet *wallet, NSArray *errors) {
if (!errors || errors.count == 0) {
//Wallet successfully updated
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
View transactions for given wallet.
GET /2/wallets/<wallet id>/transactions/| Parameter | Type | Description |
|---|---|---|
| since_id Optional |
string | Return more recent transactions than given ID. |
| max_id Optional |
string | Return transactions with an ID older than or equal to given ID. |
| count Optional |
int | How many transactions to fetch. Maximum 200, default 50. |
[
{
"id": 20,
"timestamp": 1388669449,
"new_balance": 8085.56838,
"change": 200,
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Transaction id. |
| timestamp | int | Unix time when the transaction took place. |
| new_balance | float | Balance after the transaction. |
| change | float | Amount that was added/deducted from the wallet. |
| comment | string | Comment attached to transaction. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/wallets/1/transactions/"
$client->wallet->transactions({WALLET_ID}, {SINCE_ID}, {MAX_ID}, {COUNT});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$walletId = 123;
$transactions = $client->wallet->transactions($walletId);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().transactions({WALLET_ID}, {SINCE_ID}, {MAX_ID}, {COUNT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var walletId = 1;
client.wallet().transactions(walletId).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSWallet
- (void)getTransactionLogForNextPage:(BOOL)nextPage onCompletion:(void(^)(NSArray *log, NSArray *errors))block;
@end
BSWallet *wallet = walletForGettingTransactionLog;
[wallet getTransactionLogForNextPage:NO onCompletion:^(NSArray *log, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSLog objects)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Transfer credits between your connection wallets.
POST /2/wallets/<source id>/transfer/<target id>/{
"amount": 123.45
}
{
"source_wallet": {
"id": 1,
"name": "wallet-1",
"balance": 273.45
},
"target_wallet": {
"id": 2,
"name": "wallet-2",
"balance": 125
},
"amount": 123.45
}
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X POST \
-d '{"amount": 123.45}' \
"https://api.beepsend.com/2/wallets/1/transfer/3/"
$client->wallet->transfer({SOURCE_ID}, {TARGET_ID}, {AMOUNT});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$sourceId = 123;
$targetId = 321;
$response = $client->wallet->transfer($sourceId, $targetId, 123.45);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().transfer({SOURCE_ID}, {TARGET_ID}, {AMOUNT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var sourceId = 1;
var targetId = 2;
var amount = 10;
client.wallet().transfer(sourceId, targetId, amount).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSWallet
- (void)transferFunds:(NSNumber *)funds toWallet:(BSWallet *)wallet onCompletion:(void(^)(BSTransfer *transfer, NSArray *errors))block;
- (void)transferFunds:(NSNumber *)funds fromWallet:(BSWallet *)wallet onCompletion:(void(^)(BSTransfer *transfer, NSArray *errors))block;
@end
BSWallet *wallet1 = walletToTransferFundsFrom;
BSWallet *wallet2 = walletToTransferFundsTo;
[wallet1 transferFunds:@1.0 toWallet:wallet2 onCompletion:^(BSTransfer *transfer, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSTransfer object)
}
else {
//Handle error (array of BSError objects)
}
}];
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Calculate the amount after VAT has been applied.
GET /2/wallets/<wallet id>/topup/vat-check/<amount>{
"topup_amount": 100,
"vat_amount": 125,
"vat_percentage": 25
}
| Key | Type | Description |
|---|---|---|
| topup_amount | float | Amount added to your wallet. |
| vat_amount | float | VAT that will be added to your topup_amount when paying. |
| vat_percentage | float | VAT percentage applied. |
This endpoint requres a valid User API-Token. Read more about Users and Connections.
Add credit to wallet.
POST /2/wallets/<wallet id>/topup/paypal/| Parameter | Type | Description |
|---|---|---|
| amount Required |
float | The amount in euro to add to the wallet. |
| url.return Optional |
string | The URL to redirect a user when a payment is complete and successful. Default: https://beepsend.com/success.html |
| url.cancel Optional |
string | The URL to redirect a user when a payment is aborted. Default: https://beepsend.com/cancel.html |
{
"amount": 123.45,
"url": {
"return": "https://beepsend.com/success.html",
"cancel": "https://beepsend.com/cancel.html"
}
}
{
"url": "https:\/\/www.sandbox.paypal.com\/cgi-bin\/webscr?cmd=_ap-payment&paykey=foo"
}
| Key | Type | Description |
|---|---|---|
| url | string | URL to redirect the user to, to complete the transaction. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X POST \
-d '{"amount": 123.45, "url": {"return": "https://yourdomain.com/success.html", "cancel": "https://yourdomain.com/cancel.html"}}' \
"https://api.beepsend.com/2/wallets/1/topup/paypal/"
$client->wallet->topup({WALLET_ID}, {AMOUNT});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$walletId = 123;
$response = $client->wallet->topup($walletId, 123.45);
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.wallet().topup({WALLET_ID}, {AMOUNT}, {RETURN_URL}, {CANCEL_URL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var walletId = 1;
var amount = 10;
var returnUrl = "https://beepsend.com/success.html";
var cancelUrl = "https://beepsend.com/cancel.html";
client.wallet().topup(walletId, amount, returnUrl, cancelUrl).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
Each estimation require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.
The endpoints for estimating messages cost are:
Get details for a default connection
POST /2/sms/costestimate/Get details for a specific connection
POST /2/sms/costestimate/<connection id>
POST /2/sms/costestimate/<connection label>If you want to check costs for specified mobile numbers send same object as for single send:
| Parameter | Type | Description |
|---|---|---|
| to Required |
string | array | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array. |
| message Optional |
string | Message body. If using international characters, You will need to URL encode the message. Note Multiple destinations count as multiple messages and will be charged as such. |
| encoding Optional |
string | UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE. |
You can also check cost for groups, just replace parameter to by groups
| Parameter | Type | Description |
|---|---|---|
| groups Required |
string | array | The id of contacts group that have to exist in our system. Supports multiple values in an array. |
{
"to": "46736007518",
"message": "Hello World! 你好世界!"
}
For groups
{
"groups": [
"11",
"34"
],
"message": "Hello World! 你好世界!"
}
You can also send batch. Just put your SMS objects into an array.
[
{
"to": "46736007518",
"message": "Hello World! 你好世界!",
},
{
"groups": [
"11",
"34"
],
"message": "Hello World! 你好世界!",
}
]
[
{
"total_cost": 0.0032,
"to": [
"46736007518": 0.0032
]
},
{
"total_cost": 358.57,
"groups": [
"11": 13.45,
"34": 345.12
]
}
]
| Key | Type | Description |
|---|---|---|
| total_cost | float | Total estimated cost for all messages |
| to | array(string:float) | Array containing number and it's cost |
or
| Key | Type | Description |
|---|---|---|
| total_cost | float | Total estimated cost for all messages |
| groups | array(string:float) | Array containing group id and it's cost |
Estimate SMS cost
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X POST \
-d '{"to": "46736007518", "message": "Hello World! 你好世界!"}' \
"https://api.beepsend.com/2/sms/costestimate/"
Estimate group SMS cost
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X POST \
-d '{"groups":["11","34"],"message": "Hello World! 你好世界!"}' \
"https://api.beepsend.com/2/sms/costestimate/"
Estimate batch SMS cost
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X POST \
-d '[{"to": ["46736007518","35736007505"],"message": "Hello Mr. Nilsson!"},{"groups": ["11","34"],"message": "Hello World! 你好世界!"}]' \
"https://api.beepsend.com/2/sms/costestimate/"
$client->message->estimateCost({TO}, {MESSAGE}, {CONNECTION}, {ENCODING});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
/* Get estimate cost for sms */
$sms = $client->message->estimateCost(46736007518, 'Hello World! 你好世界!');
/* Get estimate cost for sendin sms to groups */
$sms = $client->message->estimateCostGroup(array(11, 34), 'Hello World! 你好世界!');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().estimateCost({TO}, {MESSAGE}, {CONNECTION}, {ENCODING}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
client.messages().estimateCostGroup({GROUPS}, {MESSAGE}, {CONNECTION}, {ENCODING}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
/* Estimate cost for single message */
var to = 46736007518;
var message = "Hello World!";
var connection = "";
var encoding = "UTF-8";
client.messages().estimateCost(to, message, connection, encoding).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
/* Estimate cost for group message */
var groups = ["11", "34"];
var message = "Hello World!";
var connection = "";
var encoding = "UTF-8";
client.messages().estimateCostGroup(groups, message, connection, encoding).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (void)estimateSMSCostForMessages:(NSArray *)messages onCompletion:(void(^)(NSArray *cost, NSArray *errors))block;
@end
BSMessage *sms1 = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
[sms1 addGroupsRecipients:@[group1, group2]];
BSMessage *sms2 = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" toMultiple:@[@"012345678900", @"012345678901"]];
[sms2 addGroupsRecipients:@[group1]];
BSMessage *sms3 = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" toGroups:@[group1, group2]];
[[BSConnection currentConnection] estimateSMSCostForMessages:@[sms1, sms2, sms3] onCompletion:^(NSArray *cost, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSEstimateCost objects)
}
else {
//Handle error (array of BSError objects)
}
}];
Get list of all message status errors with response codes.
GET /2/errors/[
{
"id": 0,
"description": "No error."
},
{
"id": 1,
"description": "Absent subscriber. The HLR responded to the SRI for SM request with an error indicating the subscriber is absent."
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Error id |
| description | string | Error description |
Get details for specific message status error code.
GET /2/errors/<error id>{
"id": 4,
"description": "Equipment not equipped with short-message capability."
}
| Key | Type | Description |
|---|---|---|
| id | int | Error id |
| description | string | Error description |
Codes that represent message status.
| Id | Description |
|---|---|
| 0 | No error. |
| 1 | Absent subscriber. The HLR responded to the SRI for SM request with an error indicating the subscriber is absent. |
| 2 | Handset memory capacity exceeded. Handset has run out of free memory to store new message. |
| 3 | Equipment protocol error. |
| 4 | Equipment not equipped with short-message capability. |
| 5 | Unknown subscriber. The IMSI is unknown in the HLR. The HLR responded to the SRI for SM request with an error indicating the subscriber is unknown. |
| 6 | Illegal subscriber. The mobile station failed authentication. |
| 7 | Teleservice not provisioned. Mobile subscription identified by the MSISDN number does include the short message service. |
| 8 | Illegal equipment. IMEI check failed, i.e. The IMEI is either blacklisted or not whitelisted. |
| 9 | Call barred. Operator barred the MSISDN number. |
| 10 | Facility not supported. VLR in the PLMN does not support MT short message service. |
| 11 | Subscriber busy for MT short message. |
| 12 | System failure. Task cannot be completed because of a problem in another entity. |
| 13 | Data missing. Necessary parameter is not present in the primitive. |
| 14 | Unexpected data value. Necessary data is badly formatted in the primitive. |
| 15 | Unidentified subscriber. Subscriber is not contained in the database and it has not or cannot be established whether or not a subscription exists. |
| 16 | Absent subscriber. No paging response via MSC. |
| 17 | Absent subscriber. IMSI detached. |
| 18 | Absent subscriber. Roaming restriction. |
| 20 | Mobile subscriber not reachable |
| 21 | Local cancel - No response for the SRI for SM request was received. |
| 47 | TCAP error. |
| 49 | SMS discarded. This error is specific to IP-based protocols like SMPP. |
| 50 | SMS window exceeded. |
| 51 | SMS malformed. SMS is not formed correctly. This error is specific to IP-based protocols like SMPP. |
| 52 | SMS expired. |
| 53 | Insufficient credit. The user has insufficient credit/not allowed to send to that destination. |
| 54 | Invalid destination. Receiver is not a valid number. |
| 55 | Unable to find outbound route for this SMS. |
| 56 | SMS buffered. |
| 57 | Timeout waiting for response from peer. |
| 58 | Throttling Error. The user has exceeded allowed message limit. |
| 59 | Absent Subscriber: The message is undeliverable because the subscriber is temporarily absent, e.g. their phone is switch off, they cannot belocated on the network. |
| 60 | Portability error: The message was failed due to the ported combinations being unreachable. |
| 61 | Invalid PDU Format |
| 62 | ESME Client Error |
| 63 | Local ACL Deny |
| 64 | Invalid Payload Length |
| 65 | Remote Logic Error |
| 66 | Remote Logic Deny |
| 67 | DCS inconsistency |
| 68 | Route error, please contact Beepsend support |
| 69 | Rejected - SMSC rejected the SRI for SM request. |
| 70 | PSA Connection failed |
| 162 | Abort - The HLR (or some other entity in the network) aborted the SRI for SM re- quest. |
| 205 | Illegal subscriber |
| 206 | Illegal equipment |
| 218 | Screening error, Terminating IMSI blocked |
| 255 | Unknown error |
| 711 | Destination network or country is blocked. Contact with your AM to unblock this network/country |
| 712 | Insufficient credits to send message |
| 713 | SMS sent, no delivery report received. |
| 714 | Route loop detected |
| 716 | Flood protection – Multiple identical messages to Recipient detected |
| 717 | Invalid srcAddr |
| 718 | Invalid msisdn/destAddr |
| 800 | The end user does not exist |
| 801 | The end user is blocked |
| 802 | The end user belongs to a network operator that does not allow charge |
| 803 | The end user is not allowed to purchase premium services. |
| 804 | The end user has insufficient funds |
| 805 | Unknown operator |
| 810 | Subscription failed |
| 811 | SMS submit from SMSGW to SMSC failure |
| 812 | No MT connection found for short number |
| 813 | The recipient has no credit |
| 814 | Charged failed |
| 815 | Invalid service id from the request. |
| 816 | The subscription period to the associated service is already expired. |
| 817 | Invalid input format. Mandatory parameter MSISDN not found in request. |
| 826 | Message body error |
| 827 | No route found |
| 828 | Message too long |
| 829 | Internal server error |
| 830 | Invalid source address |
| 831 | Invalid destination address |
| 832 | Login incorrect |
| 833 | Missing params |
| 834 | Invalid params |
| 835 | Data not found |
| 907 | Credit related message may be being retried |
| 920 | Permanent operator error |
| 921 | Credit related: message has been retried by operator |
| 925 | Operator network failure |
| 926 | Phone related error |
| 927 | Permanent phone related error |
| 928 | Blocked due to spam |
| 929 | Content related error |
| 930 | Subscriber spend limit exceeded |
| 931 | Subscriber unable to be billed |
| 933 | Age verification failure parental lock |
| 935 | Age verification failure no previous AV |
| 936 | Age verification failure temporary AV error |
| 937 | National blacklist |
Error codes for api responses.
Note: These codes won't come up in the /2/errors/ endpoint or be searchable trough /2/errors/<error id> since we throw them before accepting the SMS traffic. The /2/errors/ endpoint is for codes regarding already accepted traffic.
| Id | Description |
|---|---|
| 1024 | Out of credits |
| 1025 | Illegal characters in message body |
| 1026 | Message body error |
| 1027 | No Valid Route found |
| 1028 | Message too long |
| 1029 | Internal server error |
| 1030 | Invalid source address |
| 1031 | Invalid destination address |
| 1032 | Invalid account or password |
| 1033 | Invalid send time |
| 1034 | Login incorrect |
| 1035 | Flood detected |
| 1036 | Invalid parameter |
| 1037 | Invalid receive dlr value |
| 1038 | Access error |
| 1039 | Requested object does not exist |
| 1040 | Requested object not modifiable |
| 1041 | Invalid validity period |
Get all error codes and the descriptions
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/errors/"
Get an error code and the description
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" -X GET \
"https://api.beepsend.com/2/errors/1"
$client->error->all();
$client->error->get({id});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
/* Get all error codes and the descriptions */
$client->error->all()
/* Get an error code and the description */
$client->error->get(1)
An email will be sent out after changing your email address asking you to verify that you have indeed changed it. Use the unique hash in the verification link to perform the verification.
GET /2/users/email/<hash>204 no content header.
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/email/<hash>"
$client->user->verifyEmail({HASH});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->verifyEmail('<hash>');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().verifyEmail({HASH}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var hash = "1231as141";
client.user().verifyEmail(hash).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
After changing your phone number. An SMS will be sent out asking you to verify the change. Use the unique hash to verify.
GET /2/users/phone/<hash>204 no content header.
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/phone/<hash>"
$client->user->verifyPhone({HASH});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->verifyPhone('<hash>');
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.user().verifyPhone({HASH}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var hash = "1231as141";
client.user().verifyPhone(hash).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
When doing pagination with the Beepsend API you use the parameters since_id and max_id.
It is a great way to efficiently filter the data you want, but we understand that they can be confusing to understand at first,
We would like to refer to the following text by Twitter to get a deeper understanding of how it works.
Each sent message require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.
A message can carry 160 characters if in the Latin alphabet and 70 if content is Unicode. The Beepsend Gateway will automatically split up the message if the content exceeds the maximum character limit based on the content encoding. When sending UTF-8 encoding the Beepsend Gateway will try and convert to GSM7 if possible to avoid splitting at 70 characters.
The endpoint for sending messages is:
POST /2/sms/Specify which connection to use for sending this message. This can be useful if you are authenticating with a User token and do not want to send with your default connection.
POST /2/sms/<connection id>
POST /2/sms/<connection label>| Parameter | Type | Description |
|---|---|---|
| to Required |
string | array | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array. Note Multiple destinations count as multiple messages and will be charged as such. |
| message Required |
string | Message body. |
| from Required |
string | Sender id. Check below for a list of allowed formats. |
| batch_id Optional |
int | The id of an existing batch of messages. This can later be used to look up details regarding your messages. |
| batch_label Optional |
string | The name of your batch of messages. Can be used to create a new batch or reuse an older batch with the same name. If batch_id is also specified, batch_label will be ignored. |
| send_time Optional |
int, Unix time | Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future. |
| encoding Optional |
string | UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE. |
| message_type Optional |
string | flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters. |
| validity_period Optional |
int, Unix time | How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite. |
| receive_dlr Optional |
int | Specify whether delivery reports should be sent to your DLR Callback URL.0: Disable, 1: Always, 2: Only on failure. Default is 1. |
| auto_gsm7_conversion Optional |
true | false | Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true. |
{
"batch_label": "My custom name for my batch",
"to": "46736007518",
"message": "Hello World! 你好世界!",
"from": "Beepsend",
"send_time": 1383225355,
"encoding": "UTF-8",
"receive_dlr": false
}
[
{
"id": "07595980013893439611559146736007518",
"batch": {
"id": 3,
"label": "My custom name for my batch"
},
"to": "46736007518",
"from": "Beepsend",
"errors": null
}
]
| Key | Type | Description |
|---|---|---|
| id | string | null | Unique Beepsend generated ID. If the SMS got rejected, null. |
| batch | array | null | Object with id and label. null if neither batch_label nor batch_id was supplied or the SMS got rejected. |
| batch.id | int | Unique batch id. |
| batch.label | string | Name of batch. |
| to | string | Input destination for this particular SMS. |
| from | string | Input source. |
| errors | null | array | Null if everything went ok. Else an array of errors. See Errors. |
The following formats are allowed for from.
Alphanumeric signs with upper or lower case characters (a-z, A-Z, 0-9). The maximum allowed characters are 11. We crop the from address at 11 characters.
MSISDN numbers, international format. Minimum 9 chars, max 17 chars.
Short numbers / codes, national format. Maximum length 7 chars.
Local restrictions apply. Check with your account manager for the destinations you aim to send to for details.
Long SMS are messages with more than 160 (70 if unicode encoding) characters.
Beepsend will automatically split up your long messages before sending so you don't have to worry about it.
Unless you're sending binary SMS.
Since long SMS are really just two or more messages with a special identifier that connects them, you will receive a response with separate IDs for each message you are sending. Similar to the response of multi address sending or batch sendouts.
Billing is done based on how many parts the message in total requires.
Send multiple messages to one or more receivers.
POST /2/sms/
POST /2/sms/<connection id>
POST /2/sms/<connection label>Messages are sent either as single objects, or multiple objects inside an array. So it's easy to send different messages at the same time.
It's like sending a single SMS. Just put your SMS objects into an array.
[
{
"batch_label": "Lottery winner",
"to": "12345",
"message": "You won!",
"from": "Beepsend",
"send_time": 1383225355,
"encoding": "UTF-8",
"message_type": "flash"
},
{
"batch_label": "Lottery contestants",
"to": [
"123456",
"1234567"
],
"message": "Better luck next time!",
"from": "Beepboop",
"send_time": 1383225385,
"encoding": "UTF-8"
}
]
You receive individual response objects for each SMS.
[
{
"id": "03003620013893441731559112345",
"batch": {
"id": 10,
"label": "Lottery winner"
},
"to": "12345",
"from": "Beepsend",
"errors": null
},
{
"id": "030889300138934417315591123456",
"batch": {
"id": 11,
"label": "Lottery contestants"
},
"to": "123456",
"from": "Beepboop",
"errors": null
},
{
"id": "0310373001389344173155911234567",
"batch": {
"id": 11,
"label": "Lottery contestants"
},
"to": "1234567",
"from": "Beepboop",
"errors": null
}
]
| Status code | Case |
|---|---|
| 201 | All messages sent successfully. |
| 200 | Some messages sent, check errors. |
| 403 | All messages failed. |
POST /2/sms/
POST /2/sms/<connection id>
POST /2/sms/<connection label>If your system rather sends the messages using binary content we offer a service for this. The combined length of a binary message and UDH can not be longer than 140 bytes (280 hex characters), if you want to send concatenated messages you have to do this by sending a sequence of messages with the appropriate UDH.
To send a binary SMS. You need to have message_type set to binary. When sending binary SMS the following options become available.
| Parameter | Type | Description |
|---|---|---|
| udh Optional |
string | User Data Header. Can be used to send Concatenated or Wap Push messages. |
| dcs Optional |
int | Data coding settings. For binary messages this is set to 4 (8-bit binary) by default. Should be 0 for gsm7 encoded messages and 8 for UCS-2 encoded messages. |
Send one message to multiple receivers.
POST /2/sms/
POST /2/sms/<connection id>
POST /2/sms/<connection label>To send to multiple destinations, just make to an array of addresses instead of a string.
{
"batch_id": 7,
"to": [
"12345",
"123456",
"1234567"
],
"message": "Hello World!",
"from": "Beepsend",
"send_time": 1383225355,
"encoding": "UTF-8",
"message_type": "flash"
}
You will receive individual objects in response.
[
{
"id": "07177940013893440591559112345",
"batch": {
"id": 7,
"label": "My multi destination batch"
},
"to": "12345",
"from": "Beepsend",
"errors": null
},
{
"id": "072644000138934405915591123456",
"batch": {
"id": 7,
"label": "My multi destination batch"
},
"to": "123456",
"from": "Beepsend",
"errors": null
},
{
"id": "0727961001389344059155911234567",
"batch": {
"id": 7,
"label": "My multi destination batch"
},
"to": "1234567",
"from": "Beepsend",
"errors": null
}
]
| Status code | Case |
|---|---|
| 201 | All messages sent successfully. |
| 200 | Some messages sent, check errors. |
| 403 | All messages failed. |
The API can be utilized to get details of any message sent through Beepsend no matter if you submitted it via SMPP or HTTP.
Get details regarding one message. This end point is subject to rate limits. The API is restricted to allow 90 requests in a 15 minute interval for a specific sms id and token.
GET /2/sms/<sms id>{
"id": "12345",
"batch": {
"id": 52,
"label": "Super batch!"
},
"body": "Hello World!",
"hex_body": "48656c6c6f20576f726c6421",
"connection": {
"id": 7,
"label": "superman-connection"
},
"to": {
"address": "46406007500",
"ton": 1,
"npi": 1
},
"from": {
"address": "Beepsend",
"ton": 1,
"npi": 1
},
"validity_period": "131102072704000-",
"data_coding": 3,
"timestamps": {
"sms": {
"in": 1383225355,
"delivered": 1383225359
},
"dlr_out": 1383225359
},
"dlr": {
"status": "DELIVRD",
"error": 0
},
"price": 0.068,
"mccmnc": {
"mcc": "240",
"mnc": "01"
}
}
| Key | Type | Description |
|---|---|---|
| id | string | Unique Beepsend generated ID. |
| batch | array | null | Array with id and label or null if message was sent with no batch specified. |
| body | string | The message body of sent SMS. |
| hex_body | string | Hex encoded string containing the raw body of sent SMS (or sms part if it's multipart message). |
| connection | array | Connection details. |
| connection.id | int | The id of the connection that was used to send the SMS. |
| connection.label | string | The name of the connection that was used to send the SMS. |
| to.address | string | Destination address. |
| to.ton | int | Type of number. |
| to.npi | int | Number Plan Index. |
| from.address | string | Source address. |
| from.ton | int | Type of number. |
| from.npi | int | Number Plan Index. |
| validity_period | string | Until what date and time the message is considered valid for routing. Formatted like YYMMDDhhmmsstnnp according to the SMPP standard. |
| data_coding | int | Data coding settings. 0 for Gsm7 encoded messages. 8 for UCS-2 encoded messages and 4 for binary messages. Can be set manually if sending Binary SMS. |
| timestamps.sms.in | int | When the message reached Beepsend in Unix time. |
| timestamps.sms.delivered | int | null | When the message was delivered to handset. In Unix time. null if not yet delivered. |
| timestamps.dlr_out | int | null | When the Delivery Report left our system to reach your DLR Callback URL. null if message has not been delivered yet. |
| dlr.status | string | null | One of the following: DELIVRD, EXPIRED, REJECTD, UNKNOWN, UNDELIV, FAILED. Or null if message has not yet been delivered. |
| dlr.error | int | null | Specific return codes regarding message delivey. 0 if OK. Beepsend Return Codes. null if message has not been delivered yet. |
| price | float | Message price. |
| mccmnc.mcc | string | Destination mcc. |
| mccmnc.mnc | string | Destination mnc. |
In case of a multipart SMS. body will be concatenated to contain all the parts.
Get details regarding multiple sent messages with filters. Result is sorted by date in descending order.
GET /2/sms/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| to Optional |
string | MSISDN, the to address. |
| from Optional |
string | Sender id. The from address. |
| connection_id Optional |
int | ID of the connection used to send the message. |
| batch_id Optional |
string | The id of your batch of messages. Will return every message sent with the same batch id or batch label. |
| status Optional |
string | Comma separated list of statuses to search for. Available: delivrd, undeliv, expired, rejectd, unknown, failed, mosms, deleted. |
| from_date Optional |
int, Unix time | Filter messages sent from this date (inclusive interval). |
| to_date Optional |
int, Unix time | Filter messages sent till this date (inclusive interval). |
| count Optional |
int | How many SMS objects to fetch. Maximum 200, default 100. |
you will receive multiple SMS objects in an array as a response.
[
{
"id": "12345",
"batch": null,
"body": "Hello World!",
"hex_body": "48656c6c6f20576f726c6421",
"connection": {
"id": 7,
"label": "superman-connection"
},
"to": {
"address": "46406007500",
"ton": 1,
"npi": 1
},
"from": {
"address": "Beepsend",
"ton": 1,
"npi": 1
},
"validity_period": "131102072704000-",
"data_coding": 3,
"timestamps": {
"sms": {
"in": 1383225355,
"delivered": null
},
"dlr_out": null
},
"dlr": {
"status": null,
"error": null
},
"price": 0.068,
"mccmnc": {
"mcc": "240",
"mnc": "01"
}
}
]
| Key | Type | Description |
|---|---|---|
| id | string | Unique Beepsend generated ID. |
| batch | array | null | Array with id and label or null if message was sent with no batch specified. |
| body | string | The message body of sent SMS. |
| hex_body | string | Hex encoded string containing the raw body of sent SMS (or sms part if it's multipart message). |
| connection | array | Connection details. |
| connection.id | int | The id of the connection that was used to send the SMS. |
| connection.label | string | The name of the connection that was used to send the SMS. |
| to.address | string | Destination address. |
| to.ton | int | Type of number. |
| to.npi | int | Number Plan Index. |
| from.address | string | Source address. |
| from.ton | int | Type of number. |
| from.npi | int | Number Plan Index. |
| validity_period | string | Until what date and time the message is considered valid for routing. Formatted like YYMMDDhhmmsstnnp according to the SMPP standard. |
| data_coding | int | Data coding settings. 0 for Gsm7 encoded messages. 8 for UCS-2 encoded messages and 4 for binary messages. Can be set manually if sending Binary SMS. |
| timestamps.sms.in | int | When the message reached Beepsend in Unix time. |
| timestamps.sms.delivered | int | null | When the message was delivered to handset. In Unix time. null if not yet delivered. |
| timestamps.dlr_out | int | null | When the Delivery Report left our system to reach your DLR Callback URL. null if message has not been delivered yet. |
| dlr.status | string | null | One of the following: DELIVRD, EXPIRED, REJECTD, UNKNOWN, UNDELIV, FAILED. Or null if message has not yet been delivered. |
| dlr.error | int | null | Specific return codes regarding message delivey. 0 if OK. Beepsend Return Codes. null if message has not been delivered yet. |
| price | float | Message price. |
| mccmnc.mcc | string | Destination mcc. |
| mccmnc.mnc | string | Destination mnc. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"to": "46736007518", "message": "Hello World! 你好世界!", "from": "Beepsend", "encoding": "UTF-8", "receive_dlr": false}' \
"https://api.beepsend.com/2/sms/"
$client->message->send({TO}, {FROM}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$options = array(
'batch_label' => 'My custom name for my batch',
'receive_dlr' => false
);
$message = $client->message->send(
46736007518,
'Beepsend',
'Hello World! 你好世界!',
$connectionId,
'UTF-8',
$options
);
You can also set null for connection id and the "me" alias is used to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().send({FROM}, {TO}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var from = "Beepsend";
var to = "46736007518";
var message = "Hello World!";
/* You can provide specific connection if you want to send from another connection account */
var connection = "";
var encoding = "UTF-8";
/* Aditional options */
var options = {
"batch_label": "My custom name for my batch",
"send_time": 1383225355,
"receive_dlr": false
};
client.messages().send(from, to, message, connection, encoding, options).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (NSInteger)sendSMS:(BSMessage *)message withCompletionBlock:(void(^)(BSMessage *message, NSArray *errors))block;
@end
BSMessage *sms = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
[[BSConnection currentConnection] sendSMS:sms withCompletionBlock:^(BSMessage *message, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (BSMessage object)
}
else {
//Handle error (array of BSError objects)
}
}];
Each sent message require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.
Get your previous batches with messages.
GET /2/batches/GET /2/batches/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from. |
[
{
"id": 3,
"label": "My custom name for my batch",
"date_created": 1386777418,
"last_used": 1387442294
},
{
"id": 4,
"label": "batch testing",
"date_created": 1387457467,
"last_used": 1387457467
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Batch id. |
| label | string | Batch name. |
| date_created | int, Unix time | Creation time of batch. |
| last_used | int, Unix time | Last time the batch was used to send a message. |
Get details for a specific batch.
GET /2/batches/<batch id>{
"id": 2,
"label": "batch testing",
"date_created": 1387457467,
"last_used": 1387457467
}
| Key | Type | Description |
|---|---|---|
| label | string | Batch name. |
| date_created | int, Unix time | Creation time of batch. |
| last_used | int, Unix time | Last time the batch was used to send a message |
This call will give a paginated overview of messages in a batch, complete with sent and received message body, recipient number and contact details, if recipient number exists in user contacts. The mobile terminated messages are matched with their mobile originated counterpart
GET /2/batches/<ID>/messages/| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from. Default is 0. |
[
{
"mt_sms_id": "889000680270500421",
"mt_body": "What is your name?",
"mt_timestamp": 1418030569,
"mo_sms_id": "889000680270500422",
"mo_body": "Sir Lancelot",
"mo_timestamp": 1418030569,
"dlr_stat": "DELIVRD",
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
},
{
"mt_sms_id": "889000680141388005",
"mt_body": "What is your quest?",
"mt_timestamp": 1418030569,
"mo_sms_id": "889000680141388006",
"mo_body": "To seek the holy grail",
"mo_timestamp": 1418030569,
"dlr_stat": "DELIVRD",
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
},
{
"mt_sms_id": "889000680141388005",
"mt_body": "What is your favorite color?",
"mt_timestamp": 1418030569,
"mo_sms_id": "889000680141388006",
"mo_body": "BLUE!",
"mo_timestamp": 1418030569,
"dlr_stat": "DELIVRD",
"to" : {
"number": "46736007500",
"contact" : {
"firstname": "Foo",
"lastname": "Bar"
}
}
}
]
| Key | Type | Description |
|---|---|---|
| mt_sms_id | string | Unique Beepsend generated ID. |
| mt_body | string | UTF-8 encoded message body of the mobile terminated message. |
| mt_timestamp | int|null | Unix time of when the message was sent. |
| mo_sms_id | string | Unique Beepsend generated ID. |
| mo_body | string | UTF-8 encoded message body of the mobile originated message. |
| mo_timestamp | int|null | Unix time of when a reply was received. |
| dlr_stat | string | Response status. |
| to | object | |
| to.number | string | Recipient number |
| to.contact | object | |
| to.contact.firstname | string | Firstname of contact. |
| to.contact.lastname | string | Lastname of contact. |
This call will give all messages in a batch formatted as CSV.
GET /2/batches/<ID>/messages.csv| Parameter | Type | Description |
|---|---|---|
| delimiter Optional |
string | What delimiter to use for the csv output. (Default: , <comma>) |
Fields in the CSV file are
| Field | Description |
|---|---|
| number | Recipient's number. |
| firstname | Firstname of the contact (might be empty). |
| lastname | Lastname of the contact (might be empty). |
| sent_sms_id | Outgoing SMS ID. |
| sent_body | Text sent to the recipient. |
| sent_sms_timestamp | ISO-8601 formatted time when the message was sent. |
| delivery_status | Status of the outgoing message. |
| incoming_sms_id | Incoming SMS ID. |
| incoming_message | Text received from the recipient. |
| incoming_sms_timestamp | ISO-8601 formatted time when the message was received. |
This call will give you delivery statistics for a whole batch.
GET /2/analytics/batches/
GET /2/analytics/batches/<ID>GET /2/analytics/batches/?<parameter>=<value>| Parameter | Type | Description |
|---|---|---|
| count Optional |
int | How many objects to fetch. Maximum 200, default 200. |
| offset Optional |
int | What row offset in result set to fetch data from. |
[
{
"id": 23,
"label": "My batch",
"total": 142,
"statistics": {
"delivered": 100,
"expired": 12,
"unknown": 20,
"rejected": 0,
"undelivered": 10,
"no_dlr": 0
},
"total_responses": 10,
"responses": [
{
"text": "yes",
"count": 7
},
{
"text": "no",
"count": 3
}
]
}
]
| Key | Type | Description |
|---|---|---|
| id | int | Unique batch id |
| label | string | Batch name |
| total | int | Total amount of messages in the batch |
| statistics.delivered | int | Amount of messages with status delivered to handset |
| statistics.expired | int | Amount of messages that suffered time out |
| statistics.unknown | int | Failed messages without a clear error |
| statistics.rejected | int | Messages not accepted by Operator |
| statistics.undelivered | int | Failed messages. Unlike unknown, an error code was returned |
| statistics.no_dlr | int | Messages still in the process of sending |
| responses_total | int | Number of responses. |
| responses | array | |
| responses.text | string | The content of the response. |
| responses.count | int | The amount of responses with this text. |
Send multiple messages to one or more receivers.
POST /2/sms/
POST /2/sms/<connection id>
POST /2/sms/<connection label>Messages are sent either as single objects, or multiple objects inside an array. So it's easy to send different messages at the same time.
It's like sending a single SMS. Just put your SMS objects into an array.
[
{
"batch_label": "Lottery winner",
"to": "12345",
"message": "You won!",
"from": "Beepsend",
"send_time": 1383225355,
"encoding": "UTF-8",
"message_type": "flash"
},
{
"batch_label": "Lottery contestants",
"to": [
"123456",
"1234567"
],
"message": "Better luck next time!",
"from": "Beepboop",
"send_time": 1383225385,
"encoding": "UTF-8"
}
]
[
{
"id": "03003620013893441731559112345",
"batch": {
"id": 10,
"label": "Lottery winner"
},
"to": "12345",
"from": "Beepsend",
"errors": null
},
{
"id": "030889300138934417315591123456",
"batch": {
"id": 11,
"label": "Lottery contestants"
},
"to": "123456",
"from": "Beepboop",
"errors": null
},
{
"id": "0310373001389344173155911234567",
"batch": {
"id": 11,
"label": "Lottery contestants"
},
"to": "1234567",
"from": "Beepboop",
"errors": null
}
]
Response for message sent to groups:
| Key | Type | Description |
|---|---|---|
| batch | array | null | Object with id and label. null if neither batch_label nor batch_id was supplied or the SMS got rejected. |
| batch.id | int | Unique batch id. |
| batch.label | string | Name of batch. |
| groups | array (string) | Ids of groups to which this message was sent |
| from | string | Input source. |
| errors | null | array | Null if everything went ok. Else an array of errors. See Errors. |
| Status code | Case |
|---|---|
| 201 | All messages sent successfully. |
| 200 | Some messages sent, check errors. |
| 403 | All messages failed. |
Send messages to groups or numbers.
POST /2/batches/Use specific connections to send messages
POST /2/batches/<connection id>
POST /2/batches/<connection label>You can send single SMS or batch SMS but instead using 1 or more to addresses you can import contacts and send to a full contacts group
To send message to contacts groups just add to standard sms parameter groups, parameter to is optional
| Parameter | Type | Description |
|---|---|---|
| groups Required |
string | array | The id of contants group that have to exist in our system. Supports multiple values in an array. |
| to Optional |
string | array | The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array. |
[
{
"batch_label": "Lottery winner",
"groups": [
"1",
"2"
],
"to": [
"123456",
"1234567"
],
"message": "You won!",
"from": "Beepsend",
"send_time": 1383225355,
"encoding": "UTF-8",
"message_type": "flash"
}
]
[
{
"batch": {
"id": 10,
"label": "Lottery winner"
},
"groups": [
"1",
"2"
],
"from": "Beepsend",
"errors": null
},
{
"id": "030889300138934417315591123456",
"batch": {
"id": 10,
"label": "Lottery winner"
},
"to": "123456",
"from": "Beepsend",
"errors": null
},
{
"id": "0310373001389344173155911234567",
"batch": {
"id": 10,
"label": "Lottery winner"
},
"to": "1234567",
"from": "Beepsend",
"errors": null
}
]
Response for message sent to groups:
| Key | Type | Description |
|---|---|---|
| batch | array | null | Object with id and label. null if neither batch_label nor batch_id was supplied or the SMS got rejected. |
| batch.id | int | Unique batch id. |
| batch.label | string | Name of batch. |
| groups | string | array | Ids of groups to which this message was sent |
| from | string | Input source. |
| errors | null | array | Null if everything went ok. Else an array of errors. See Errors. |
| Status code | Case |
|---|---|
| 201 | All messages sent successfully. |
| 200 | Some messages sent, check errors. |
| 403 | All messages failed. |
Send one message to multiple receivers.
POST /2/sms/
POST /2/sms/<connection id>
POST /2/sms/<connection label>To send to multiple destinations, just make to an array of addresses instead of a string.
{
"batch_id": 7,
"to": [
"12345",
"123456",
"1234567"
],
"message": "Hello World!",
"from": "Beepsend",
"send_time": 1383225355,
"encoding": "UTF-8",
"message_type": "flash"
}
You will receive individual objects in response.
[
{
"id": "07177940013893440591559112345",
"batch": {
"id": 7,
"label": "My multi destination batch"
},
"to": "12345",
"from": "Beepsend",
"errors": null
},
{
"id": "072644000138934405915591123456",
"batch": {
"id": 7,
"label": "My multi destination batch"
},
"to": "123456",
"from": "Beepsend",
"errors": null
},
{
"id": "0727961001389344059155911234567",
"batch": {
"id": 7,
"label": "My multi destination batch"
},
"to": "1234567",
"from": "Beepsend",
"errors": null
}
]
| Status code | Case |
|---|---|
| 201 | All messages sent successfully. |
| 200 | Some messages sent, check errors. |
| 403 | All messages failed. |
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '[{"batch_label": "Lottery winner", "to": "46736007518", "message": "You won!", "from": "TheLottery", "send_time": 1383225355, "encoding": "UTF-8", "message_type": "flash"}, {"batch_label": "Lottery contestants", "to": ["46736007502", "46736007505"], "message": "Better luck next time!", "from": "TheLottery", "encoding": "UTF-8"}]' \
"https://api.beepsend.com/2/sms/"
$helper->message({TO}, {FROM}, {MESSAGE}, {ENCODING}, {OPTIONS});
$client->message->multiple({HELPER}, {CONNECTION});
require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;
$client = new Client('abc123');
$connectionId = 1;
$helper = $client->getHelper('message');
$helper->message(
46736007518,
'Beepsend',
'You won!',
'UTF-8',
array(
'batch_label' => 'Lottery winner',
'message_type' => 'flash'
)
);
$helper->message(
array(46736007502, 46736007505),
'Beepboop',
'No win, better luck next time!',
'UTF-8',
array(
'batch_label' => 'Lottery contestants'
)
);
/* Send all messages */
$client->message->multiple($helper, $connectionId)
You can also set null for connection id and then the "me" alias is used to reference the default connection
var client = new beepsend(
{
"api_token" : "abc123"
}
);
client.messages().multiple({beepsend.messagesHelper}, {CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
var aditionalOptions = {
"batch_label": "Lottery winner",
"send_time": 1383225355,
"message_type": "flash"
};
/* Instance of messages helper */
var messages = new beepsend.messagesHelper();
messages.message('Beepsend', ["123","12345"], "Hello World 1 !!!", "UTF-8", aditionalOptions);
messages.message('Beepsend', ["1235123", "1235123", "1235112315"], "Hello world 2 !!!");
/* parameter connection is not required, you have to provide it only if you want to send messages from specific connection, otherwise system will use your default connection */
client.messages().multiple(messages, connection).then(
function(success) {
// Write your success handler function here
},
function(error) {
// Write your error handler function here
}
);
@interface BSConnection
- (NSInteger)sendMultipleSMS:(NSArray *)messages withCompletionBlock:(void(^)(NSArray *messages, NSArray *errors))block;
@end
BSBatch *batch = someBatch;
BSMessage *sms = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
//For batch sending it is necessary to set parameter batch in message
sms.batch = batch;
[[BSConnection currentConnection] sendMultipleSMS:@[sms] withCompletionBlock:^(NSArray *messages, NSArray *errors) {
if (!errors || errors.count == 0) {
//Handle response (array of BSMessage objects)
}
else {
//Handle error (array of BSError objects)
}
}];
If you POST a request with multiple msisdns the result is posted back to your connection's specified DLR Callback URL.
POST /2/hlr/<connection id>| Parameter | Type | Description |
|---|---|---|
| msisdn Required |
string | Mobile number |
| connection Optional |
int | Specify your preferred connection to use for this operation. |
{
"msisdn": [
"46736007518",
"46736007505",
"046736007512"
]
}
As acknowledgement you will receive an array of objects with a unique request ID for every msisdn.
[
{
"id": "08087780013866630151559112345",
"msisdn": "46736007518",
"errors": null
},
{
"id": "08087780013866301515591123456",
"msisdn": "46736007505",
"errors": null
},
{
"id": null,
"msisdn": "046736007512",
"errors": [
{
"code": 1031,
"description": "\"msisdn\" can't have leading zeroes or pluses"
}
]
}
]
| Status code | Case |
|---|---|
| 201 | All HLR lookups sent successfully. |
| 200 | Some HLR lookups sent, check errors. |
| 403 | All HLR lookups failed. |