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:
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.
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.
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.
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>;
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.
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:
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
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
To install Python SDK issue the following command:
pip install gsmservice-gateway
More information and documentation you can find at our GitHub
To install C# SDK issue the following command:
dotnet add package Gsmservice.Gateway
More information and documentation you can find at our GitHub
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
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
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.
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).
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. |
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 }
[- {
- "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 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).
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. |
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 }
[- {
- "id": 43456,
- "status": 400,
- "error": {
- "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 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).
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.
required | string or array or object The recipient number or multiple recipients numbers of single message. To set one recipient, simply pass here a |
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 | |
One of string <byte> (string) An image, audio or video file body encoded by | |
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 |
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>"
}
[- {
- "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 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).
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.
required | string or array or object The recipient number or multiple recipients numbers of single message. To set one recipient, simply pass here a | ||||||||
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
| ||||||||
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 |
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
}
[- {
- "error": null,
- "cid": "custom-id-A44445T",
- "type": 1,
- "recipient": "+48999999999",
- "sender": "Bramka SMS",
- "parts": 1,
- "unicode": true,
- "flash": false,
- "price": 0.16
}
]
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).
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.
required | string or array or object The recipient number or multiple recipients numbers of single message. To set one recipient, simply pass here a |
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 | |
One of string <byte> (string) An image, audio or video file body encoded by | |
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 |
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>"
}
[- {
- "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 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).
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.
required | string or array or object The recipient number or multiple recipients numbers of single message. To set one recipient, simply pass here a | ||||||||
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
| ||||||||
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 |
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
}
[- {
- "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
}
]
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).
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 |
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 }
[- {
- "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
}
]
This section describes how to access Mobile Originated (incoming) messages. You can retrieve received messages or access incoming message box on your account.
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).
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 |
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 }
[- {
- "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 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).
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. |
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 }
[- {
- "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"
}
]
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.
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).
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 }
[- {
- "sender": "Bramka SMS",
- "status": "Active",
- "is_default": true
}
]
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).
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) |
{- "sender": "Bramka SMS",
- "description": "This is our company name. It contains our registered trademark."
}
{- "sender": "Bramka SMS",
- "status": "Active",
- "is_default": true
}
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).
sender required | string Example: Podpis Sender name to be removed |
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 }
{- "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 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).
sender required | string Example: Podpis Sender name to set as default |
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 }
{- "status": 400,
- "title": "Invalid Body property format",
- "detail": "The request body contains a malformed property",
- "code": "400-21",
- "instance": "/rest/messages/sms"
}
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).
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 }
{- "login": "some_login",
- "account_type": "PRE-PAID",
- "limit": 0,
- "credit": 130.44,
- "subcredit": 65.32,
- "currency": "PLN",
- "name": "Andrzej Nowak",
- "is_main": true
}
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).
user_login required | string Example: some-login Login of the subaccount (user) to get the data for |
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 }
{- "login": "some_login",
- "account_type": "PRE-PAID",
- "limit": 0,
- "credit": 130.44,
- "subcredit": 65.32,
- "currency": "PLN",
- "name": "Andrzej Nowak",
- "is_main": true
}
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).
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 }
{- "status": "OK",
- "version": "1.0",
- "sandbox": false
}
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
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.
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:
| ||||||||||
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) |
[- {
- "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
}
]
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.
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) |
[- {
- "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"
}
]