README

The SMS Connexion API PHP library provides convenient access to the SMS API of SMS.CX from applications written in the PHP language.

Using this library you can:

send SMS (transactional, promotional) - single or bulk SMS
receive SMS
rent phone numbers
validate phone numbers
lookup phone numbers (HLR)
send OTP SMS (2FA)
create groups of contacts
import contacts
create short links
and more

For more information, please visit https://sms.cx

Content:

Installation
Authentication
Usage
Handling errors
Rate limit
Documentation
Available methods

Installation

Requirements

PHP 7.4 and later (works with PHP 8.0).

Composer

To install the library it is recommended that you use Composer:

$ composer require smscx/smscx-api-php-library

The above command will install the library and all required dependencies.

To use the library, use Composer's autoload:

require_once('vendor/autoload.php');

Dependencies

The library require the following extensions in order to work properly:

ext-curl
ext-json
ext-mbstring
Guzzle (PHP HTTP client that makes it easy to send HTTP requests )
GuzzleHttp\Psr7 (PSR-7 interface for requests, responses, and streams)

If you use Composer, these dependencies should be handled automatically. If you install manually, you'll want to make sure that these extensions are available.

Authentication

To use the library you must authenticate. SMS.CX PHP Library supports the authentication methods supported by the SMS Connexion API:

API Key
Oauth2 Access Token

1. API Key

To create a new API Key go to SMS.CX Account > HTTP API > API Keys and click on New API Key.

Copy the API Key and use it in the library.

2. Oauth2 Access Token

Access tokens are used by applications to make API requests.

To create a new application go to SMS.CX Account > HTTP API > Applications and click on New Application.

When you have the Application ID and Application Secret, you can use them to request an access token that you can use to make API calls.

Copy the APPLICATION_ID and APPLICATION_SECRET and use them to request an access token:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

$config = Smscx\Configuration::getDefaultConfiguration()
              ->setApplicationId('YOUR_APPLICATION_ID')
              ->setApplicationSecret('YOUR_APPLICATION_SECRET');

$smscx = new Smscx\Api\OauthApi(
    new GuzzleHttp\Client(),
    $config
);
// A list of space-delimited, case-sensitive strings. If left empty or ommited,
// the issued access token will be granted with all scopes (full privileges)
$scopes = ''; 

try {
    $result = $smscx->getAccessToken($scopes);
    $accessToken = $result->getAccessToken();
    $expiresIn = $result->getExpiresIn();
    print_r($result);
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    //Code for Invalid request
} catch (Smscx\Client\Exception\InvalidCredentialsException $e) {
    //Code for Invalid credentials
} catch (Smscx\Client\Exception\InvalidScopeException $e) {
    //Code for Invalid scope
} catch (Smscx\Client\Exception\ApiException $e) {
    echo 'Exception when calling OauthApi->getAccessToken: ', $e->getMessage(), PHP_EOL;
}

Access tokens provide three main security benefits over using an API Key:

Revocable access. Access tokens can be revoked, removing access for only that token without having to change your API Key everywhere.
Limited access. Access tokens have access scopes which allow for more granular access to API resources. For instance, you can grant access only to send SMS but not to get groups of contacts.
Short lifetime. Access tokens have an expire time (1 day, 1 week) which reduces the risk of the token being compromised.

Usage

The library needs to be configured with your account's Application ID & secret or API Key which are available in your SMS.CX Dashboard.

The following example will send SMS to a single phone number:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

// Use authentication via API Key
$config = Smscx\Configuration::getDefaultConfiguration()->setApiKey('YOUR_API_KEY');

// OR

// Use authentication via Access Token
// $config = Smscx\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

$smscx = new Smscx\Api\SmsApi(
    new GuzzleHttp\Client(),
    $config
);

$send_sms_message_request = [
    'to' => '+31612469xxx',
    'from' => 'InfoText',
    'text' => 'Your confirmation code is 15997',
];

try {
    $result = $smscx->sendSms($send_sms_message_request);
    print_r($result);
    //$result->getInfo()->getTotalCost();
} catch (InvalidArgumentException $e) {
    //Code for Invalid argument provided
} catch (Smscx\Client\Exception\NoCoverageException $e) {
    //Code for No coverage
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    //Code for Invalid request    
} catch (Smscx\Client\Exception\InvalidPhoneNumberException $e) {
    //Code for Invalid phone number    
} catch (Smscx\Client\Exception\InsufficientBalanceException $e) {
    //Code for Insufficient balance
} catch (Smscx\Client\Exception\ApiException $e) {
    echo 'Exception when calling SmsApi->sendSms: ', $e->getMessage(), PHP_EOL;
    // $http_code = $e->getCode();  # For HTTP response code: 400, 401, 403, 429, 500, etc
    // $error_type = $e->getResponseObject()->getError()->getType();  # For type of error: invalid_param, insufficient_credit, rate_limit, etc
    // $error_message = $e->getResponseObject()->getError()->getMessage();  # Short description of the error
    // $error_code = $e->getResponseObject()->getError()->getCode();  # API internal error code: 1208, 1101, 1221, etc    
}

Example of bulk SMS sending (up to 25.000 destination phone numbers)

<?php

require_once(__DIR__ . '/vendor/autoload.php');

// Use authentication via API Key
$config = Smscx\Configuration::getDefaultConfiguration()->setApiKey('YOUR_API_KEY');

// OR

// Use authentication via Access Token
// $config = Smscx\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

$smscx = new Smscx\Api\SmsApi(
    new GuzzleHttp\Client(),
    $config
);

$send_sms_message_request = [
    //Max 25.000 phone numbers
    'to' => [
        '+31612469xxx', 
        '+4474005085xx', 
        '+49151238353xx', 
        '+417811126xx', 
        '+3519123350xx', 
        '+4206016090xx',
        '+359483059xx',
        '+336127904xx',
        '+436645595xx',
        '+3519121385xx',
        '+3069125917xx',
    ],
    'from' => 'InfoText',
    'text' => 'Redeem this voucher and you will get 30% discount off all Summer Fashion {{optoutLink}}',
    'allowInvalid' => true,
    'transliteration' => [
        'alphabet' => 'NON_GSM',
        'removeEmojis' => true,
    ],
    'idempotencyId' => '854cd53f-d77d-4aa8-9bd9-fbf720f3332d',
];

try {
    $result = $smscx->sendSms($send_sms_message_request);
    print_r($result);
    //$result->getInfo()->getTotalCost();
    //$result->getInfo()->getInvalid();
} catch (InvalidArgumentException $e) {
    //Code for Invalid argument provided
} catch (Smscx\Client\Exception\NoCoverageException $e) {
    //Code for No coverage
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    //Code for Invalid request    
} catch (Smscx\Client\Exception\InvalidPhoneNumberException $e) {
    //Code for Invalid phone number    
} catch (Smscx\Client\Exception\InsufficientBalanceException $e) {
    //Code for Insufficient balance
} catch (Smscx\Client\Exception\ApiException $e) {
    echo 'Exception when calling SmsApi->sendSms: ', $e->getMessage(), PHP_EOL;
    // $http_code = $e->getCode();  # For HTTP response code: 400, 401, 403, 429, 500, etc
    // $error_type = $e->getResponseObject()->getError()->getType();  # For type of error: invalid_param, insufficient_credit, rate_limit, etc
    // $error_message = $e->getResponseObject()->getError()->getMessage();  # Short description of the error
    // $error_code = $e->getResponseObject()->getError()->getCode();  # API internal error code: 1208, 1101, 1221, etc    
}

Handling errors

With this client library, you don’t need to check for non-200 HTTP responses. The library translates them as exceptions.

In some specific rare cases you may need to analyze the Error object for type and code properties.

To handle errors, use these two techniques:

Catch Exceptions
Analyze and handle the Error object provided in the response body

1. Catch Exceptions

The SMS.CX PHP library raises an exception for every error type. It is recommended to catch and handle exceptions.

To catch an exception, use PHP’s try/catch syntax. SMS Connexion provides many exception classes you can catch. Each one represents a different kind of error. When you catch an exception, you can use its class to choose a response.

General exceptions:

DuplicateIdException - A resource with the same ID already exist
DuplicateValueException - You are trying to create/update a resource that must be unique (eg. originators, group name, shortlinks, template name)
InsufficientScopeException - Your application does not have the privilege to access a resource
InvalidCredentialsException - Unable to authenticate you based on the information provided.
InvalidRequestException - The parameters provided were invalid
InvalidScopeException - The scope requested does not exist
RateLimitExcedeedException - You made too many API calls in short period of time.
ResourceNotFoundException - The ID of the requested resource was not found (eg. group, campaign, otp, shortlink, template, etc.)
ApiMethodNotAllowedException - The target resource doesn’t support this HTTP method
AccessDeniedException - You don’t have permission to perform an action (eg. editing a template that was locked, replying to an Whatsapp after more than 24 hours passed from client reply, etc.)
ServerErrorException - Something went wrong on SMS Connexion’s side.
ApiException - Something went wrong on SMS Connexion’s side

Exceptions for methods that validate numbers or incur costs (to send SMS, add phone numbers to groups, validate number, etc.):

InsufficientBalanceException - Your request incurs charges in excess of your existing balance.
InvalidPhoneNumberException - The phone number provided is not valid

Exceptions for methods that require network coverage (send SMS, Viber, Whatsapp):

NoCoverageException - There is no coverage for the destination requested (these are rare)

Exceptions for Otp:

InvalidPinException - The PIN provided does not verify with our records
OtpAlreadyVerifiedException - The OTP was already verified
OtpCancelledException - You cannot verify an OTP that was cancelled
OtpActionNotAllowedException - You cannot cancel an OTP that has non-pending status (eg. was already verified, canceled, or expired)
OtpExpiredException - You cannot verify an OTP that was expired
OtpFailedException - The OTP verification has failed because the numbers of max attempts was reached

Exceptions for Viber/Whatsapp:

ChannelNotActiveException - Channel is not active. You need to register Viber and Whatsapp by contacting us
TemplateNotApprovedException - Template for sending Viber or Whatsapp is not approved

2. Analyze Error object

The error object ( \Smscx\Client\Model\Error ), which is present in all Exceptions, store information about failures.

If you don’t want to rely on our existing Exceptions, you might need to analyze the details of the Error object.

You can retrieve the error object and examine it to learn more about the failure. Choose an appropriate response according on the error type. Check the examples provided to learn how to get the HTTP code and the error object.

A range of different error types are returned by the API, correlated with their HTTP codes:

HTTP 400 Bad Request for error type invalid_param, insufficient_credit
HTTP 401 Unauthorized for invalid_api_key, invalid_client
HTTP 404 Not Found for not_found
HTTP 429 Too Many Requests for rate_limit

Read the complete list of error types and codes from the API specification.

Example of error handling

try {
    // Method
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    // Code for this situation
} catch (Smscx\Client\Exception\RateLimitExcedeedException $e) {
    // Wait some time and retry the request
    $retryAfter = $e->getHeader('X-Rate-Limit-Reset'); //Unix timestamp eg. 1664103086
} catch (Smscx\Client\Exception\ServerErrorException $e) {
    // Code for this situation
} catch (Smscx\Client\Exception\ApiException $e) {
    // If you want to analyze the Error object
    $httpCode = $e->getCode();
    $errorType = $e->getResponseObject()->getError()->getType();
    $errorMessage = $e->getResponseObject()->getError()->getMessage();
    $errorCode = $e->getResponseObject()->getError()->getCode();
}

In special cases, when using methods to validate phone numbers in bulk or when adding phone numbers to an existing group, the Error object will contain a list with invalid phone numbers (if the parameter allowInvalid was not set to true or if not a single valid number was detected).

$invalidPhoneNumbers = $e->getResponseObject()->getError()->getInvalid();
/*
Returns array of invalid numbers:
[
  "+336123",
  "+336123",
  "+44158994578",
  "+39677814354",
  "+336259987345",
]
*/

Rate limit

To detect an API rate limit error, you can catch the Exception RateLimitExcedeedException or check the Error object for error type rate_limit or check if the HTTP code is 429:

try {
    // Method
} catch (Smscx\Client\Exception\RateLimitExcedeedException $e) {
    //Rate limited
    $retryAfter = $e->getHeader('X-Rate-Limit-Reset'); //Unix timestamp eg. 1664103086
}

Documentation

The docs folder provides detailed guides for using this library (methods, models, examples).

The examples folder provides an example for each method.

Full documentation of the API is available here.

Available methods

Read the documentation for each method to get more examples, complete parameter list, expected responses and list of error codes.

Class AccountApi

Method	Description
getAccountBalance()	Get account balance
getChannelPricing()	Get channels pricing
getChannelPricingByCountryIso()	Get pricing for channel by country iso
getChannelsStatus()	Get status of all channels

Class ApplicationsApi

Method	Description
getApplicationSettings()	Get application settings
getApplicationsList()	Get applications list
getScopes()	Get scopes

Class AttachmentsApi

Method	Description
deleteAttachment()	Delete attachment
exportAttachmentHitsToCSV()	Export attachment hits to CSV
exportAttachmentHitsToXLSX()	Export attachment hits to XLSX
getAttachmentHits()	Get attachment hits
getAttachmentsList()	Get attachments list

Class ConversationsApi

Method	Description
getConversation()	Get conversation
getConverstionsList()	Get conversations list
markConversationAsRead()	Mark conversation as read
sendConversationReplySms() 💰	Send conversation reply via SMS
sendConversationReplyViber() 💰	Send conversation reply via Viber
sendConversationReplyWhatsapp() 💰	Send conversation reply via Whatsapp

Class GroupsApi

Method	Description
addContactsToGroup()	Add contacts to group
createGroup()	Create new group
deleteContactFromGroup()	Delete contact from group
deleteGroup()	Delete group
emptyGroup()	Empty group
exportGroupToCSV()	Export group to CSV
exportGroupToXLSX()	Export group to XLSX
getGroupDetails()	Get group details
getGroupsList()	Get list of groups
updateContactFromGroup()	Update contact from group

Class MultichannelApi

Method	Description
deleteScheduledMultichannelCampaign()	Delete scheduled Multichannel campaign
deleteScheduledMultichannelMessage()	Delete scheduled Multichannel message
estimateMultichannelCampaign()	Estimate Multichannel campaign
estimateMultichannelMessage()	Estimate Multichannel message
sendMultichannelCampaign() 💰	Send Multichannel campaign
sendMultichannelMessage() 💰	Send Multichannel message

Class NumbersApi

Method	Description
getBulkLookupStatus()	Get Bulk Lookup result
getSingleLookupStatus()	Get Single Lookup result
getBulkLookupCampaigns()	Get list of bulk lookup campaigns
lookupNumber() 💰	Lookup number
lookupNumbers() 💰	Lookup numbers in bulk
exportNumberLookupReportToCSV()	Export number lookup campaign to CSV
exportNumberLookupReportToXLSX()	Export number lookup campaign to XLSX
validateNumber()	Validate number
validateNumbers()	Validate numbers in bulk
getAvailableNumbers()	Get available numbers for rent
rentNumber() 💰	Rent phone number
cancelRent()	Cancel rent for phone number
renewRent() 💰	Renew rent for phone number
getRentStatus()	Get status of rent
getRentedNumbers()	Get list of your rented numbers
getInboundSms()	Get inbound SMS from rented number
editRentSettings()	Edit settings for active rent

Class OauthApi

Method	Description
getAccessToken()	Get access token

Class OptoutsApi

Method	Description
addContactToOptoutsList()	Add contact to optouts list
deleteContactFromOptoutsList()	Delete contact from optouts list
exportOptoutsToCSV()	Export optouts to CSV
exportOptoutsToXLSX()	Export optouts to XLSX
getOptoutsList()	Get optouts list

Class OriginatorsApi

Method	Description
createOriginator()	Create new originator
deleteOriginator()	Delete originator
getOriginatorsList()	Get originators list

Class OtpApi

Method	Description
cancelOtp()	Cancel OTP
getOtpStatus()	Get OTP status
newOtp() 💰	New OTP
verifyOtp()	Verify OTP

Class ReportsApi

Method	Description
exportAdvancedReportToCSV()	Export advanced report to CSV
exportAdvancedReportToXLSX()	Export advanced report to XLSX
exportCampaignReportToCSV()	Export campaign report to CSV
exportCampaignReportToXLSX()	Export campaign report to XLSX
getAdvancedReport()	Get advanced report
getCampaignReport()	Get campaign report
getCampaignsList()	Get list of sent campaigns
getSingleReport()	Get report for single SMS or Viber or Whatsapp or Multichannel
getSummaryReports()	Get summary reports for a dimension

Class ShortlinksApi

Method	Description
createShortlink()	Create shortlink
deleteShortlink()	Delete shortlink
exportShortlinkHitsToCSV()	Export shortlink hits to CSV
exportShortlinkHitsToXLSX()	Export shortlink hits to XLSX
getShortlinkHits()	Get shortlink hits
getShortlinksList()	Get shortlinks list
updateShortlink()	Update shortlink

Class SmsApi

Method	Description
deleteScheduledSms()	Delete scheduled SMS
deleteScheduledSmsCampaign()	Delete scheduled SMS campaign
estimateSms()	Estimate new SMS
estimateSmsCampaign()	Estimate SMS campaign
sendSms() 💰	Send SMS
sendSmsCampaign() 💰	Send SMS campaign

Class TemplatesApi

Method	Description
createTemplate()	Create template
deleteTemplate()	Delete template
getTemplate()	Get template
getTemplatesList()	Get templates list
updateTemplate()	Update template

Class ViberApi

Method	Description
deleteScheduledViberCampaign()	Delete scheduled Viber campaign
deleteScheduledViberMessage()	Delete scheduled Viber message
estimateViberCampaign()	Estimate Viber campaign
estimateViberMessage()	Estimate Viber message
sendViberCampaign() 💰	Send Viber campaign
sendViberMessage() 💰	Send Viber message

Class WhatsappApi

Method	Description
deleteScheduledWhatsappMessage()	Delete scheduled Whatsapp message
estimateWhatsappMessage()	Estimate Whatsapp message
sendWhatsappMessage() 💰	Send Whatsapp message

Authorization

ApiKeyAuth

Type: API key
API key parameter name: X-API-KEY
Location: HTTP header

BasicAuth

Type: HTTP basic authentication

BearerAuth

Type: Bearer authentication

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

dev@sms.cx

About this package

Client library version: 0.1.1
API version: 1.0.2

smscx / smscx-api-php-library

Maintainers

Details