Download the PHP package smscx/smscx-api-php-library without Composer

smscx-api-php-library

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:

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

To use the library, use Composer's autoload:

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:

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:

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

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

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

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:

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

Class ApplicationsApi

Class AttachmentsApi

Class ConversationsApi

Class GroupsApi

Class MultichannelApi

Class NumbersApi

Class OauthApi

Class OptoutsApi

Class OriginatorsApi

Class OtpApi

Class ReportsApi

Class ShortlinksApi

Class SmsApi

Class TemplatesApi

Class ViberApi

Class WhatsappApi

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:

Author

[email protected]

About this package

• Client library version: 0.1.1
• API version: 1.0.2

License

Apache 2.0 © 2022 SMS Connexion