Messaging Gateway GSMService.pl (1.1.3)

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 platform 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 this specification 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 API ID.

To do it please use this site - fill the New API ID form with your preferred API ID, 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 account via API will be possible. You can also set a callback address there to collect any messages status updates automatically. When a status of a message 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 <YOUR_API_ACCESS_TOKEN>;

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.2

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 add @gsmservice-pl/messaging-sdk-typescript

More information and documentation you can find at our GitHub

Python ≥ 3.8

To install Python SDK issue the following command:

pip install gsmservice-gateway

More information and documentation you can find at our GitHub

C# (.Net ≥ 8.0)

To install C# SDK issue the following command:

dotnet add package Gsmservice.Gateway

More information and documentation you can find at our GitHub

Java ≥ 11

To install Java SDK with Gradle issue the following command:

implementation 'pl.gsmservice:gateway:1.0.1'

More information and documentation you can find at our GitHub

Go ≥ 1.14

To install C# SDK issue the following command:

go get github.com/gsmservice-pl/messaging-sdk-go

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
[]

Check the price of MMS Messages

Check the price of single or multiple MMS messages at the same time before sending them. You have to pass as request body the MmsMessage object (for single message) or array of MmsMessage objects (for multiple messages). Each object has several properties, describing message parameters such recipient phone number, content of the message, attachments, etc. Please mind that some of them are required. The system will accept maximum 50 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 check 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 MMS or messages with the same content to multiple recipients, pass in the Request Body a single MmsMessage 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 MmsMessage 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)

subject
string or null
Example: "To jest temat wiadomości"

MMS message subject

message
string or null
Example: "To jest treść wiadomości"

MMS message content

string or array

Attachments for the message. You can pass here images, audio and video files bodies. To set one attachment please pass a string with attachment body encoded by base64. To set multiple attachments - pass an array of strings with attachment bodies encoded by base64. Max 3 attachments per message.

One of
string <byte> (string)

An image, audio or video file body encoded by base64

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

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

{
  • "recipients": "+48999999999",
  • "message": "This is MMS message content.",
  • "subject": "This is a subject of the message",
  • "attachments": "<file body in base64 format>"
}

Response samples

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
    }
]

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 check 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

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

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 MMS Messages

Send single or multiple MMS messages at the same time. You have to pass as request body the MmsMessage object (for single message) or array of MmsMessage objects (for multiple messages). Each object has several properties, describing message parameters such recipient phone number, content of the message, attachments or scheduled sending date, etc. Please mind that some of them are required. The system will accept maximum 50 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 MMS or messages with the same content to multiple recipients, pass in the Request Body a single MmsMessage 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 MmsMessage 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)

subject
string or null
Example: "To jest temat wiadomości"

MMS message subject

message
string or null
Example: "To jest treść wiadomości"

MMS message content

string or array

Attachments for the message. You can pass here images, audio and video files bodies. To set one attachment please pass a string with attachment body encoded by base64. To set multiple attachments - pass an array of strings with attachment bodies encoded by base64. Max 3 attachments per message.

One of
string <byte> (string)

An image, audio or video file body encoded by base64

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

Example of sending a single message to one recipient.

{
  • "recipients": "+48999999999",
  • "message": "This is MMS message content.",
  • "subject": "This is a subject of the message",
  • "attachments": "<file body in base64 format>"
}

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
    }
]

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

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
{}

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
{}

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

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

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 can pass information about up to 50 messages status changes.

You can optionally configure User Token - all calllbacks will be triggered then with Authorization: Bearer <token> header.

After receiving a Callback you should response with correct HTTP code (200). If a response will contain another code (4XX or 5XX), a callback will be triggered by system again after 5 minutes then 15 minutes, 1 hour and last attempt after 6 hours.

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

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.

You can optionally configure User Token - all calllbacks will be triggered then with Authorization: Bearer <token> header.

After receiving a Callback you should response with correct HTTP code (200). If a response will contain another code (4XX or 5XX), a callback will be triggered by system again after 5 minutes then 15 minutes, 1 hour and last attempt after 6 hours.

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

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"
    }
]