Messaging Gateway GSMService.pl (0.9.2)

Download OpenAPI specification:Download

Bramka SMS GSMService.pl: bramka@gsmservice.pl URL: https://bramka.gsmservice.pl License: MIT

Introduction

This document was created to explain the process of integration any application or system with the GSMService.pl SMS Gateway via the REST API. Currently, there are several ways to send messages with the GSMService.pl platform:

Directly from the https://bramka.gsmservice.pl website User Panel
Via this REST API and provided SDKs
Via the legacy (deprecated) versions API: Webservices (SOAP) and HTTP
Via the MAIL2SMS service

This document describes the possibilities offered by REST API.

We kindly ask you to read this documentation carefully before starting the integration. This will make the whole process easier and will help you avoid many problems.

Documentation and Try Outs

This documentation is available in two formats: REDOC and SWAGGER. You can test any endpoint directly from documentation using Try Out feature of Swagger. Also you can download a YAML file with doc in OpenApi 3.0 format.

Account signup and setup

Firstly, it is necessary to create your personal account at the GSMService.pl SMS Gateway platform if you haven't one and activate access to the API. To register a new account please signup the form. After signing up and fully activation of an account you have to activate an access to the API.

To do it please use this site - fill the New API Access form with your preferred API login, set your API password, select which API standard you want to activate for this account (select REST API there). Optionally you can add IP adresses (or IP pool with CIDR notation) from which access to your API account will be possible. You can also set a callback address there to collect any messages status updates automatically. When a status of a messaga changes, the callback address will be called with passing parameters with new message status.

After setup an API access you will get an unique API Access Token - please write it down as there won't be possible to display it again (you will have the possibility to regenerate it only). This token will be required to authenticate all the requests made with API on your account.

Authentication of API requests

All the endpoints of this REST API have to be authenticated using your API Access Token with one exception: /rest/ping endpoint which doesn't need an authentication.

To make an authenticated request you should add to all requests an Authorization header which you have generated in previous step:

Authorization: Bearer &lt;YOUR_API_ACCESS_TOKEN&gt;

URLs to connect to API

Please use this SSL secured adresses to connect to REST API:

https://api.gsmservice.pl/rest - for production system
https://api.gsmservice.pl/rest-sandbox - for test system (Sandbox)

[!NOTE] When calling our API, make sure you are using TLS version 1.2 or higher. Older versions are no longer supported.

SDK Client Libraries

For developers integrating SMS functionality into their app, we provide a convenient SDK Libraries.

Our SDKs allow you to quickly start interacting with the Gateway using your favorite programming language. Currently we support the following languages:

PHP 8

To install PHP SDK issue the following command:

composer require gsmservice-pl/messaging-sdk-php

More information and documentation you can find at our GitHub

Typescript

To install Typescript SDK issue the following command:

NPM

npm add @gsmservice-pl/messaging-sdk-typescript

More information and documentation you can find at our GitHub

Outgoing messages

This section describes how to manipulate Mobile Terminated (outgoing) messages. You can send new messages, check their current status and price, cancel scheduled messages or get the full message history from your account.

Get the messages details and status by IDs

Check the current status and details of one or more messages using their ids. You have to pass the unique message IDs as path parameter, which were returned after sending a message. If you want to get the details of multiple messages at once, please separate their IDs with a comma. The system will accept maximum 50 identifiers in one call. If you need to get details of larger volume of messages, please split it to several separate requests.

As a successful result an array with Message objects will be returned, each object per single found message. Response will also include meta-data headers: X-Success-Count (a count of messages which were found and returned correctly) and X-Error-Count (count of messages which were not found).

If you pass duplicated IDs, API will return data of this message only once. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

path Parameters

ids

required

Array of integers [ 1 .. 50 ] items [ items >= 1 ]

Example: 43456

Message IDs assigned by the system (separated by comma). The system will accept a maximum of 50 identifiers in one call.

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->outgoing->getByIds(
    ids: [
        43456,
    ]
);

if ($response->messages !== null) {
    // handle response
}

Response samples

Content type

application/json

[{"id": 323234,
"cid": "custom-id-A44445T",
"type": 1,
"recipient": "+48999999999",
"sender": "Bramka SMS",
"parts": 1,
"sent_date": "2024-06-01T16:22:05Z",
"status_date": "2024-06-01T16:22:07Z",
"status_code": "QUEUED",
"status_description": "The message has been accepted",
"unicode": true,
"flash": false,
"price": 0.16
}
]

Cancel a scheduled messages

Cancel messages using their ids which were scheduled to be sent at a specific time. You have to pass the unique message IDs as path parameter, which were returned after sending a message. If you want to cancel multiple messages at once, please separate their IDs with a comma. The system will accept maximum 50 identifiers in one call. If you need to cancel larger volume of messages, please split it to several separate requests. You can cancel only messages with SCHEDULED status.

As a successful result an array with CancelledMessage objects will be returned, each object per single message id. The status property will contain a status code of operation - 204 if message was cancelled successfully and other code if an error occured with cancelling a given message. In case of an error, an error property will contain ErrorResponse object with the details of an error.

Response will also include meta-data headers: X-Success-Count (a count of messages which were cancelled successfully), X-Error-Count (count of messages which were not cancelled) and X-Sandbox (if a request was made in Sandbox or Production system).

If you pass duplicated message IDs in one call, API will process them only once. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

path Parameters

ids

required

Array of integers [ 1 .. 50 ] items [ items >= 1 ]

Example: 43456

Message IDs assigned by the system (separated by comma). The system will accept a maximum of 50 identifiers in one call.

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->outgoing->cancelScheduled(
    ids: [
        43456,
    ]
);

if ($response->cancelledMessages !== null) {
    // handle response
}

Response samples

Content type

application/json

[{"id": 43456,
"status": 400,
"error": {"type": "https://problems-registry.smartbear.com/invalid-body-property-format",
"status": 400,
"title": "Invalid Body property format",
"detail": "The request body contains a malformed property",
"code": "400-21",
"instance": "/rest/messages/sms"
}
}
]

Check the price of SMS Messages

Check the price of single or multiple SMS messages at the same time before sending them. You have to pass as request body the SmsMessage object (for single message) or array of SmsMessage objects (for multiple messages). Each object has several properties, describing message parameters such recipient phone number, content of the message, type, etc. Please mind that some of them are required. The system will accept maximum 100 messages in one call. If you need to check the price of larger volume of messages, please split it to several separate requests.

As a successful result an array of Price objects will be returned, one object per each single message. You should check the error property of each message in a response body to make sure which were priced successfully and which finished with an error. Successfully priced messages will have null value of error property. Response will also include meta-data headers: X-Success-Count (a count of messages which were processed successfully) and X-Error-Count (count of messages which were rejected).

If you send duplicated messages in one call, API will process such message only once. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

Request Body schema: application/json
required

To check the price of a single SMS or messages with the same content to multiple recipients, pass in the Request Body a single SmsMessage object with the properties of this message. To check the price of multiple messages with different content at the same time, pass in the Request Body an array of SmsMessage objects with the properties of each message.

One of

required

string or array or object

The recipient number or multiple recipients numbers of single message. To set one recipient, simply pass here a string with his phone number. To set multiple recipients, pass here a simple array of string. Optionally you can also set custom id (user identifier) for each message - pass PhoneNumberWithCid object (in case of single recipient) or Array of PhoneNumberWithCid (in case of multiple recipients).

One of

[ 7 .. 16 ] characters

string (string) [ 7 .. 16 ] characters ^\+[0-9]+$

A telephone number in international format (with a plus sign and the country code at the beginning, e.g. +48 for Poland)

message

required

string

Example: "To jest treść wiadomości"

SMS message content

sender

string <= 11 characters

Default: "Bramka SMS"

Example: "Bramka SMS"

SMS sender name

type

integer (SmsType)

Default: 1

Enum: 1 3 4

Example: "1"

SMS type according to the table

type	Description
1	SMS PRO
3	SMS ECO
4	SMS 2WAY

unicode

boolean

Default: false

Example: "true"

Should the message be sent with special characters, e.g. Polish diacritics (if any)? If false, those characters will be automatically replaced with their equivalents. If true your message will be sent as unicode but the message will be able to consist of fewer characters.

flash

boolean

Default: false

Example: "false"

Should the message to be sent with class 0 (FLASH)?

date

string or null <date-time>

Default: null

Example: "null"

Scheduled future date and time of sending the message (in ISO 8601 format). If missing or null - message will be sent immediately

Responses

Request samples

Content type

application/json

Example

SMS to single recipient

Example of checking the price of a single message to one recipient.

{"recipients": "+48999999999",
"message": "This is SMS message content.",
"sender": "Bramka SMS",
"type": 1,
"unicode": true,
"flash": false
}

Response samples

200
400
401
4XX
5XX

Content type

application/json

[{"error": null,
"cid": "custom-id-A44445T",
"type": 1,
"recipient": "+48999999999",
"sender": "Bramka SMS",
"parts": 1,
"unicode": true,
"flash": false,
"price": 0.16
}
]

Send SMS Messages

Send single or multiple SMS messages at the same time. You have to pass as request body the SmsMessage object (for single message) or array of SmsMessage objects (for multiple messages). Each object has several properties, describing message parameters such recipient phone number, content of the message, type or scheduled sending date, etc. Please mind that some of them are required. The system will accept maximum 100 messages in one call. If you need to send larger volume of messages, please split it to several separate requests.

As a successful result an array with Message objects will be returned, one object per each single message. You should check the status_code property of each message in a response body to make sure which were accepted by gateway (queued) and which were rejected. In case of rejection, status_description property will include a reason. Response will also include meta-data headers: X-Success-Count (a count of messages which were processed successfully), X-Error-Count (count of messages which were rejected) and X-Sandbox (if a request was made in Sandbox or Production system).

If you send duplicated messages in one call, API will process such message only once. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

Request Body schema: application/json
required

To send a single SMS or messages with the same content to multiple recipients, pass in the Request Body a single SmsMessage object with the properties of this message. To send multiple messages with different content at the same time, pass in the Request Body an array of SmsMessage objects with the properties of each message.

One of

required

string or array or object

The recipient number or multiple recipients numbers of single message. To set one recipient, simply pass here a string with his phone number. To set multiple recipients, pass here a simple array of string. Optionally you can also set custom id (user identifier) for each message - pass PhoneNumberWithCid object (in case of single recipient) or Array of PhoneNumberWithCid (in case of multiple recipients).

One of

[ 7 .. 16 ] characters

string (string) [ 7 .. 16 ] characters ^\+[0-9]+$

A telephone number in international format (with a plus sign and the country code at the beginning, e.g. +48 for Poland)

message

required

string

Example: "To jest treść wiadomości"

SMS message content

sender

string <= 11 characters

Default: "Bramka SMS"

Example: "Bramka SMS"

SMS sender name

type

integer (SmsType)

Default: 1

Enum: 1 3 4

Example: "1"

SMS type according to the table

type	Description
1	SMS PRO
3	SMS ECO
4	SMS 2WAY

unicode

boolean

Default: false

Example: "true"

Should the message be sent with special characters, e.g. Polish diacritics (if any)? If false, those characters will be automatically replaced with their equivalents. If true your message will be sent as unicode but the message will be able to consist of fewer characters.

flash

boolean

Default: false

Example: "false"

Should the message to be sent with class 0 (FLASH)?

date

string or null <date-time>

Default: null

Example: "null"

Scheduled future date and time of sending the message (in ISO 8601 format). If missing or null - message will be sent immediately

Responses

Request samples

Content type

application/json

Example

SMS to single recipient

Example of sending a single message to one recipient.

{"recipients": "+48999999999",
"message": "This is SMS message content.",
"sender": "Bramka SMS",
"type": 1,
"unicode": true,
"flash": false
}

Response samples

Content type

application/json

[{"id": 323234,
"cid": "custom-id-A44445T",
"type": 1,
"recipient": "+48999999999",
"sender": "Bramka SMS",
"parts": 1,
"sent_date": "2024-06-01T16:22:05Z",
"status_date": "2024-06-01T16:22:07Z",
"status_code": "QUEUED",
"status_description": "The message has been accepted",
"unicode": true,
"flash": false,
"price": 0.16
}
]

Lists the history of sent messages

Get the details and current status of all of sent messages from your account message history. This endpoint supports pagination so you have to pass as query parameters a page value (number of page with messages which you want to access) and a limit value (max of messages per page). Messages are fetched from the latest one. The system will accept maximum 50 as limit parameter value. If you need to get details of larger volume of messages, please access them with next pages.

As a successful result an array with Message objects will be returned, each object per single message. Response will also include meta-data headers: X-Total-Results (a total count of all messages which are available in history on your account), X-Total-Pages (a total number of all pages with results), X-Current-Page (A current page number) and X-Limit (messages count per single page). This request have to be authenticated using API Access Token.

A response contains also a special Link header which includes URIs to access next, previous, first and last page with messages (which complies with RFC 5988).

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

query Parameters

page	integer >= 1 Default: 1 Example: page=1 Page number of results
limit	integer [ 1 .. 50 ] Default: 10 Example: limit=10 Number of results on one page

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->outgoing->list(
    page: 1,
    limit: 10

);

if ($response->messages !== null) {
    // handle response
}

Response samples

Content type

application/json

[{"id": 323234,
"cid": "custom-id-A44445T",
"type": 1,
"recipient": "+48999999999",
"sender": "Bramka SMS",
"parts": 1,
"sent_date": "2024-06-01T16:22:05Z",
"status_date": "2024-06-01T16:22:07Z",
"status_code": "QUEUED",
"status_description": "The message has been accepted",
"unicode": true,
"flash": false,
"price": 0.16
}
]

Incoming messages

This section describes how to access Mobile Originated (incoming) messages. You can retrieve received messages or access incoming message box on your account.

List the received SMS messages

Get the details of all of received messages from your account incoming messages box. This endpoint supports pagination so you have to pass as query parameters a page value (number of page with received messages which you want to access) and a limit value (max of received messages per page). Messages are fetched from the latest one. The system will accept maximum 50 as limit parameter value. If you need to get details of larger volume of messages, please access them with next pages.

As a successful result an array with IncomingMessage objects will be returned, each object per single received message. Response will also include meta-data headers: X-Total-Results (a total count of all received messages which are available in incoming box on your account), X-Total-Pages (a total number of all pages with results), X-Current-Page (A current page number) and X-Limit (messages count per single page). This request have to be authenticated using API Access Token.

A response contains also a special Link header which includes URIs to access next, previous, first and last page with received messages (which complies with RFC 5988).

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

query Parameters

page	integer >= 1 Default: 1 Example: page=1 Page number of results
limit	integer [ 1 .. 50 ] Default: 10 Example: limit=10 Number of results on one page

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->incoming->list(
    page: 1,
    limit: 10

);

if ($response->incomingMessages !== null) {
    // handle response
}

Response samples

Content type

application/json

[{"id": 45544,
"login": "some-user",
"recipient": "+48999000555",
"sender": "+48999888777",
"phonebook_sender_name": "Jan Nowak",
"date": "2024-05-31T05:17:35Z",
"message": "To jest treść odebranego SMSa",
"dedicated_number": "+48111222444",
"dedicated_prefix": "LATO"
}
]

Get the incoming messages by IDs

Get the details of one or more received messages using their ids. You have to pass the unique incoming message IDs as path parameter, which were given while receiving a messages. If you want to get the details of multiple messages at once, please separate their IDs with a comma. The system will accept maximum 50 identifiers in one call. If you need to get details of larger volume of incoming messages, please split it to several separate requests.

As a successful result an array with IncomingMessage objects will be returned, each object per single found message. Response will also include meta-data headers: X-Success-Count (a count of incoming messages which were found and returned correctly) and X-Error-Count (count of incoming messages which were not found).

If you pass duplicated IDs, API will return data of this message only once. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

path Parameters

ids

required

Array of integers [ 1 .. 50 ] items [ items >= 1 ]

Example: 43456

Message IDs assigned by the system (separated by comma). The system will accept a maximum of 50 identifiers in one call.

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->incoming->getByIds(
    ids: [
        43456,
    ]
);

if ($response->incomingMessages !== null) {
    // handle response
}

Response samples

Content type

application/json

[{"id": 45544,
"login": "some-user",
"recipient": "+48999000555",
"sender": "+48999888777",
"phonebook_sender_name": "Jan Nowak",
"date": "2024-05-31T05:17:35Z",
"message": "To jest treść odebranego SMSa",
"dedicated_number": "+48111222444",
"dedicated_prefix": "LATO"
}
]

Senders

This section describes how to manage message senders names on your account. You can add, delete, get or set as default a sender name, which can be used to send messages.

List allowed senders names

Get a list of allowed senders defined in your account. The request doesn't contain a body or any parameters.

As a successful result an array with Sender objects will be returned, each object per single sender. Senders are being registered by providers and operators. Registered senders get Active status and can be used then to send messages. Pending senders are also returned by API (with proper status) but until registration they cannot be used. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->senders->list(

);

if ($response->senders !== null) {
    // handle response
}

Response samples

Content type

application/json

[{"sender": "Bramka SMS",
"status": "Active",
"is_default": true
}
]

Add a new sender name

Define a new allowed sender on your account. The request body should contain a Sender object with two properties: sender (defines sender name) and description. The secont parameter is very important - sender names are being registered by providers and operators. Only fully registered sender names can be used to send messages. Providers need sometimes detailed description of case in which the sender will be used to eliminate frauds. After verifing it they make a decisions if such sender name can be registered. Please carefully fill this property with the extensive description of a sender name (what will be its use, what the name mean, etc).

As a successful result a single Sender object will be returned. Registered senders get Active status and can be used then to send messages. Pending Senders are also returned by API (with proper status) but until registration they cannot be used. Response will also include meta-data header: X-Sandbox (if a request was made in Sandbox or Production system). This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

Request Body schema: application/json
required

To add a new sender in the request body pass an object with the properties of the sender.

sender required	string [ 2 .. 11 ] characters Example: "Bramka SMS" Message sender name
description required	string Example: "This is our company name. It contains our registered trademark." Description of the purpose of the sender name (required when adding new sender name)

Responses

Request samples

Content type

application/json

{"sender": "Bramka SMS",
"description": "This is our company name. It contains our registered trademark."
}

Response samples

Content type

application/json

{"sender": "Bramka SMS",
"status": "Active",
"is_default": true
}

Delete a sender name

Removes defined sender name from your account. This endpoint accepts a path sender parameter with empty request body. You should pass the full sender name to delete it. Sender name will be deleted immediately.

As a successful response only HTTP status code of 204 will be returned in header with empty response body. Response will also include meta-data header: X-Sandbox (if a request was made in Sandbox or Production system). This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

path Parameters

sender

required

string

Example: Podpis

Sender name to be removed

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->senders->delete(
    sender: 'Podpis'
);

if ($response->statusCode === 200) {
    // handle response
}

Response samples

Content type

application/problem+json

{"type": "https://problems-registry.smartbear.com/invalid-body-property-format",
"status": 400,
"title": "Invalid Body property format",
"detail": "The request body contains a malformed property",
"code": "400-21",
"instance": "/rest/messages/sms"
}

Set default sender name

Set default sender name to one of the senders names already defined on your account. Default sender name can be used while sending messages when you not pass any other defined sender to SmsMessage object while sending message.

This endpoint accepts a path sender parameter with empty request body. You should pass the full sender name to set it as default on your account.

As a successful response only HTTP status code of 204 will be returned in header with empty response body. Response will also include meta-data header: X-Sandbox (if a request was made in Sandbox or Production system). This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

path Parameters

sender

required

string

Example: Podpis

Sender name to set as default

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->senders->setDefault(
    sender: 'Podpis'
);

if ($response->statusCode === 200) {
    // handle response
}

Response samples

Content type

application/problem+json

{"type": "https://problems-registry.smartbear.com/invalid-body-property-format",
"status": 400,
"title": "Invalid Body property format",
"detail": "The request body contains a malformed property",
"code": "400-21",
"instance": "/rest/messages/sms"
}

Accounts

This section describes simple operations on user accounts.

Get account details

Get current account balance and other details of your account. You can check also account limit and if account is main one. Main accounts have unlimited privileges and using User Panel you can create as many subaccounts as you need.

The request doesn't contain a body or any parameters. As a successful result an AccountResponse object will be returned with properties describing details of current account you are logged in to using API Access Token. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->accounts->get(

);

if ($response->accountResponse !== null) {
    // handle response
}

Response samples

200
401
403
4XX
5XX

Content type

application/json

{"login": "some_login",
"account_type": "PRE-PAID",
"limit": 0,
"credit": 130.44,
"subcredit": 65.32,
"currency": "PLN",
"name": "Andrzej Nowak",
"is_main": true
}

Get subaccount details

Check account balance and other details such subcredit balance of a subaccount. Subaccounts are additional users who can access your account services and the details. You can restrict access level and setup privileges to subaccounts using user panel.

This endpoint accepts a path user_login parameter with empty request body. You should pass the full subaccount login to access its data.

As a successful result an AccountResponse object will be returned with properties describing details of subaccount with provided login. This request have to be authenticated using API Access Token.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Authorizations:

Bearer

path Parameters

user_login

required

string

Example: some-login

Login of the subaccount (user) to get the data for

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$security = '<YOUR API ACCESS TOKEN>';

$sdk = Gateway\Client::builder()->setSecurity($security)->build();



$response = $sdk->accounts->getSubaccount(
    userLogin: 'some-login'
);

if ($response->accountResponse !== null) {
    // handle response
}

Response samples

Content type

application/json

{"login": "some_login",
"account_type": "PRE-PAID",
"limit": 0,
"credit": 130.44,
"subcredit": 65.32,
"currency": "PLN",
"name": "Andrzej Nowak",
"is_main": true
}

Common

This section describes other usefull operations and tools

Checks API availability and version

Check the API connection and the current API availability status. Also you will get the current API version number. The request doesn't contain a body or any parameters.

As a successful result a PingResponse object will be returned. This request doesn't need to be authenticated.

In case of an error, the ErrorResponse object will be returned with proper HTTP header status code (our error response complies with RFC 9457).

Responses

Request samples

declare(strict_types=1);

require 'vendor/autoload.php';

use Gsmservice\Gateway;

$sdk = Gateway\Client::builder()->build();



$response = $sdk->common->ping(

);

if ($response->pingResponse !== null) {
    // handle response
}

Response samples

200
400
503
4XX
5XX

Content type

application/json

{"status": "OK",
"version": "1.0",
"sandbox": false
}

Callbacks

This section describes Callbacks generated and triggered by API Server to pass information to developer's apps and systems about new statuses of messages and new received messages

Messages status change Webhook

If a message status changes, the configured custom Callback URL will be automatically trigerred with an array of Message objects sent by POST request (in request body), containing information about new status of a messages. You can setup a callback URL in User Panel in API configuration section. In one call system will pass information about up to 50 messages status changes.

After receiving a Callback you should response with correct HTTP code (ex. 200). If a response will contain another code (4XX or 5XX), a callback will be triggered by system again in few minutes.

Authorizations:

User_BearerNone

Request Body schema: application/json
required

Array ([ 1 .. 50 ] items)

id

integer or null

Example: "323234"

Unique message identifier

cid

string or null

Example: "custom-id-A44445T"

Custom message ID assigned by the User

type

integer (MessageType)

Enum: 1 3 4 10

Example: "1"

Message type according to the table:

type	Description
1	SMS PRO
3	SMS ECO
4	SMS 2WAY
10	MMS

recipient

string (string) [ 7 .. 16 ] characters ^\+[0-9]+$

Example: "+48999999999"

A telephone number in international format (with a plus sign and the country code at the beginning, e.g. +48 for Poland)

sender

string or null

Example: "Bramka SMS"

Message sender name

parts

integer or null

Example: "1"

The count of parts that message consists of

sent_date

string or null <date-time>

Example: "2024-06-01T16:22:05Z"

Sending date and time (in ISO 8601 format)

status_date

string or null <date-time>

Example: "2024-06-01T16:22:07Z"

Date and time of last status change (in ISO 8601 format)

status_code

string

Example: "QUEUED"

Message status code

status_description

string

Example: "The message has been accepted"

Human redable description of message status

unicode

boolean

Example: "true"

Did the message contain special characters, e.g. Polish diacritics?

flash

boolean

Example: "false"

Was the message sent with class 0 (FLASH)?

price

number <float>

Example: "0.16"

The price of message (in PLN)

Responses

Request samples

Payload

Content type

application/json

[{"id": 323234,
"cid": "custom-id-A44445T",
"type": 1,
"recipient": "+48999999999",
"sender": "Bramka SMS",
"parts": 1,
"sent_date": "2024-06-01T16:22:05Z",
"status_date": "2024-06-01T16:22:07Z",
"status_code": "QUEUED",
"status_description": "The message has been accepted",
"unicode": true,
"flash": false,
"price": 0.16
}
]

New incoming messages Webhook

If a new incoming message will be received by the Gateway, the configured custom Callback URL will be automatically trigerred with an array of IncomingMessage objects sent by POST request (in request body), containing information about new incoming messages. You can setup a callback URL in User Panel in Incoming Messages configuration section. In one call system will pass information about up to 50 incoming messages.

After receiving a Callback you should response with correct HTTP code (ex. 200). If a response will contain another code (4XX or 5XX), a callback will be triggered by system again in few minutes.

Authorizations:

User_BearerNone

Request Body schema: application/json
required

Array ([ 1 .. 50 ] items)

id	integer Example: "45544" Unique identifier of incoming message
login	string Example: "some-user" Login of the account (sub-account) on which the message was received
recipient	string Example: "+48999000555" Recipient number (or service name)
sender	string Example: "+48999888777" Message sender number (or alphanumeric name)
phonebook_sender_name	string or null Example: "Jan Nowak" Sender name (matched with phonebook)
date	string <date-time> Example: "2024-05-31T05:17:35Z" Date and time of message receipt in ISO 8601 format
message	string Example: "To jest treść odebranego SMSa" Received message content
dedicated_number	string or null Example: "+48111222444" Dedicated Mobile Originated service number (if the message was received on this number)
dedicated_prefix	string or null Example: "LATO" Dedicated Mobile Originated service prefix (if the message was received on this number with such prefix)

Responses

Request samples

Payload

Content type

application/json

[{"id": 45544,
"login": "some-user",
"recipient": "+48999000555",
"sender": "+48999888777",
"phonebook_sender_name": "Jan Nowak",
"date": "2024-05-31T05:17:35Z",
"message": "To jest treść odebranego SMSa",
"dedicated_number": "+48111222444",
"dedicated_prefix": "LATO"
}
]

Messaging Gateway GSMService.pl (0.9.2)

Introduction

Documentation and Try Outs

Account signup and setup

Authentication of API requests

URLs to connect to API

SDK Client Libraries

PHP 8

Typescript

NPM

Outgoing messages

Get the messages details and status by IDs

Authorizations:

path Parameters

Responses

Request samples

Response samples

Cancel a scheduled messages

Authorizations:

path Parameters

Responses

Request samples

Response samples

Check the price of SMS Messages

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send SMS Messages

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Lists the history of sent messages

Authorizations:

query Parameters

Responses

Request samples

Response samples

Incoming messages

List the received SMS messages

Authorizations:

query Parameters

Responses

Request samples

Response samples

Get the incoming messages by IDs

Authorizations:

path Parameters

Responses

Request samples

Response samples

Senders

List allowed senders names

Authorizations:

Responses

Request samples

Response samples

Add a new sender name

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete a sender name

Authorizations:

path Parameters

Responses

Request samples

Response samples

Set default sender name

Authorizations:

path Parameters

Responses

Request samples

Response samples

Accounts

Get account details

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required