Download the PHP package oxemis/oxisms without Composer

Official OxiSMS PHP Wrapper

Overview

This repository contains the official PHP wrapper for the OxiSMS API. To get started, create an account and request your free credits on this page

This library is a wrapper for the OxiSMS API but you don't have to know how to use the API to get started with this library.

What is OxiSMS ?

OxiMailing is a solution designed to enable you to send your SMS quickly and easily.

We offer worldwide coverage (see details) and sender personalization when authorized by recipient operators.

All our SMS messages are sent via Premium routes, guaranteeing the best possible deliverability.

We're a small team, but we're recognized for the quality of our support and expertise.

Table of contents

• Compatibility
• Installation
• Authentication
• Getting information about your account
• Sending your first sms
• How to send customized messages ?
• Using a custom sender
• How many characters can I put in my message ?
• How to get the number of credits that will be used for a sending ?
• How to specify a strategy for my sending ?
• Other features
• Contribute

Compatibility

This library requires PHP v7.4 or higher.

Installation

Use the below code to install the wrapper:

composer require oxemis/oxisms

Authentication

This library is a wrapper to the OxiSMS API. You can request an API KEY in your OxiSMS Account. Free credits are offered.

You should export your API_LOGIN and API_PASSWORD in order to use them in this library :

Initialize your OxiSms Client:

Getting information about your account

You will find all the information about your OxiSMS account with the "UserAPI" object. Informations returned are documented in the class.

Sending your first SMS

In order to send a mail, you must instantiate a Message object and, send it, via the $client->sendAPI->Send() method.

Here's a simple sample of how to send a SMS :

You can also schedule a sending by using the $message->setScheduledDateTime($selectedDateAndTime) method.

How to send customized messages?

With this library you can send customized messages based on templating. Basically, every content between {{ and }} will be replaced by the corresponding recipient metadata.

Here is a simple sample :

Two messages will be sent. The first one will be "Hi Joe ! This is your ID : 1", the second one : "Hi Jane ! This is your ID : 2".

Using a custom sender

By default, our SMS are sent with a short code (36xxx in France for example) or a specific phone number. But, as we send SMS using Premium routes, you can specify a custom sender in your messages.

Please note that some operators refuse to receive messages with custom senders. In these cases, we'll replace the sender with a short code. You can check the coverage about this.

Custom senders like phone numbers are not allowed to prevent spoofing !

The sender MUST respect these requirements :

• 2 to 11 characters
• Only ascii A-Z 0-9 and spaces

And please not that, if you use the commercial strategy and a custom sender, an unsubscribe method will be added to your message (STOP SMS 36111 for example). This can increase the length of the message.

Ok for you ? So let's set the sender in our previous sample with the setSender method:

How many characters can I put in my message ?

Not an easy answer ! SMS are basically limited to 160 characters.

BUT, if your message contains characters that are not in the GSM alphabet (e.g. emojis or some accented characters like ê) we'll have to send you messages in unicode mode. In this case SMS are limited to 70 characters.

Not enough ? No problem ! Our platform is able to manage long sms so that you can send messages composed by 8 SMS (it's totaly transparent for your recipients, the parts are concatened). But in this case SMS are limited to 153 characters (GSM) or 67 characters (Unicode).

So, TLDR; :

• If your message contains only GSM characters the max length of 1 SMS is 160 characters.
• If your message contains special chars (like emojis), the max length of 1 SMS is 70 characters.
• If your message is GSM and you exceed the 160 chars limit, the number of SMS used to send the message is : number of chars / 157 (max 8).
• If your message is Unicode and you exceed the 70 chars limit, the number of SMS used to send the message is : number of chars / 67 (max 8).

How to get the number of credits that will be used for a sending ?

As we've seen above, calculate the cost of a sending is not as simple as counting the number of recipients 😁

If you want to get the future cost of a sending, use the $client->sendAPI->getCostOfMessage($m) method !

You can also set a MaxCreditsPerSending on your message. If that cost is exceeded, OxiSMS will refuse to send your message.

This example will throw an API Exception :

How to specify a strategy for my sending ?

Strategy is very important for your message.

There are two different stragtegies available :

Please be very careful selecting the strategy. Sending marketing messages with "Notification" strategy will probably lock your account cause of "complaints" from your recipients !

To specify your strategy, set it in the Message :

Other features

You'll find a lot of other features by exploring the *API objects in the APIClient. Here is a non-exhaustive list of these objects (each one is documented with PHPDoc).

• blacklistsAPI : get / set your blacklists (lists of unsubscribed recipients)
• bouncesAPI : get / set your bounces (list of invalid phone numbers)
• sendAPI : send now or schedule your messages
• userAPI : everything about your account

Each object is documented with PHPDoc. Other features will be added in the future. You can also make direct call to the API (and even contribute to this project !). Please take a look at the API Reference 😀

Contribute

Feel free to ask anything, and contribute to this project. Need help ? 👉 [email protected]