Send scheduled SMS in PHP via REST API

Send scheduled SMS in PHP via REST API

By Guest Post

6 min read time.

Dev Tips and Sample Code

The humble SMS packs a punch.

People check their phones constantly, and 98 percent of texts are read within 3 minutes, versus 20 percent of emails.

You can double down on the benefits of text messaging by reprogramming SMS to be sent at a specific date and time. In simple terms, you can program or schedule messages to be set and forget — and your team will thank you for reducing their admin time.

You can easily set up your scheduled text messages with our SMS API. It offers a quick way to send messages anywhere in the world via trusted, direct routes.

Good news for devs, our API supports multiple programming languages including PHP. Using our REST API, you can post up to 1,000 SMS messages for each API call or post to a list of up to 20,000 subscribers with each API call for larger campaigns. Learn how to use the our REST API to send scheduled SMS in PHP.

Why schedule text messages?

You don’t have to schedule messages for these specific use cases, but here are example messages that work best when you set them to be sent automatically.

  • Promotional campaigns: For example, you can schedule your Black Friday or Cyber Monday texts months ahead of both events.

  • Birthday or anniversary messages: Customers love getting these, and you can send them every year.

  • Post-event notifications: Schedule these for twenty-four hours after an event to get feedback or to promote the next event.

  • Booking/appointment reminders: Schedule these to be sent a few times before an event to reduce no-shows.

How to send scheduled SMS in PHP

Our SMS API documentation offers straightforward instructions for integrating SMS into your PHP application. To implement scheduled messages in PHP using our API, follow the steps below. You can find a sample application here if needed.

Register for a free ClickSend account

You’ll need to sign up for an account, if you haven’t already.

Once you register, we’ll send you an activation PIN via text message in order to confirm that you are the owner of the mobile number that you provided during sign-up.

Enter the activation PIN on the verification pag

ClickSend dashboard screenshot home

Once you're in, you’ll get access to a variety of tools and some free credit to use for testing.

Copy your API Key

Next, copy your API key from the API Credentials area. You need the API key to validate your account before using any of our tools or API.

To retrieve your API credentials, navigate to the Developers dropdown option on your dashboard and click API Credentials. The accessible API keys for each individual user in your account will be displayed on the Subaccounts page:

ClickSend dashboard screenshot of subaccounts page for API key

Install the PHP library

We offer a PHP library that can be used to integrate services into your PHP application. Make sure you have PHP 5.5 or any later version installed before you begin.

Run the following command in the terminal inside your PHP project directory to install the library via Composer:

composer require clicksend/clicksend-php

The command will also install all of the necessary dependencies for the PHP library:

bash
Info from https://repo.packagist.org: #StandWithUkraine
Using version ^5.0 for clicksend/clicksend-php
- composer.json has been created
- Running composer update clicksend/clicksend-php
- Loading composer repositories with package information
- Updating dependencies
- Lock file operations: 9 installs, 0 updates, 0 removals
  - Locking clicksend/clicksend-php (v5.0.75)
  - Locking guzzlehttp/guzzle (7.4.3)
  - Locking guzzlehttp/promises (1.5.1)
  - Locking guzzlehttp/psr7 (2.3.0)
  - Locking psr/http-client (1.0.1)
  - Locking psr/http-factory (1.0.1)
  - Locking psr/http-message (1.0.1)
  - Locking ralouphie/getallheaders (3.0.3)
  - Locking symfony/deprecation-contracts (v2.5.1)
- Writing lock file
- Installing dependencies from lock file (including require-dev)
- Package operations: 9 installs, 0 updates, 0 removals
  - Downloading guzzlehttp/psr7 (2.3.0)
  - Downloading guzzlehttp/guzzle (7.4.3)
  - Downloading clicksend/clicksend-php (v5.0.75)
  - Installing symfony/deprecation-contracts (v2.5.1): Extracting archive
  - Installing psr/htto-message (1.0.1): Extracting archive
  - Installing psr/http-client (1.0.1): Extracting archive
  - Installing ralouphie/getallheaders (3.0.3): Extracting archive
  - Installing sr/http-factory (1.0.1): Extracting archive
  - Installing guzzlehtto/psr7 (2.3.0): Extracting archive
  - Installing guzzlehttp/promises (1.5.1): Extracting archive
  - Installing guzzlehttp/auzzle (7.4.3): Extracting archive
  - Installing clicksend/clicksend-pho (v5.0.75): Extracting archive
- 2 package suggestions were added by new dependencies, use
  "composer suggest"
  to see details.
- Generating autoload files
- 4 packages you are using are looking for funding.
  Use the
  composer fund' command to find out more!

Write the PHP code for sending SMS messages

After the library has been installed, create a PHP file named schedule.php in your project directory. You’ll use our API to schedule a message in this file.

Add the following code to the PHP file, per the documentation:

php
<?php
require_once(__DIR__ . '/vendor/autoload.php');  // #1

// Configure HTTP basic authorization: BasicAuth  #2 
$config = ClickSend\Configuration::getDefaultConfiguration()
    ->setUsername('USERNAME')
    ->setPassword('API KEY');

$apiInstance = new ClickSend\Api\SMSApi(new GuzzleHttp\Client(), $config);  // #3

$message = new \ClickSend\Model\SmsMessage();  // #4
$message->setBody("We have a new offer for the upcoming holiday season. Visit our website to view the offers of various products you can buy.");  // #5
$message->setTo("0451111111");  // #6
$message->setSchedule("1655206230");  // #7

// \ClickSend\Model\SmsMessageCollection | SmsMessageCollection model
$sms_messages = new \ClickSend\Model\SmsMessageCollection();  // #8
$sms_messages->setMessages([$message]);

try {  // #9
    $result = $apiInstance->smsSendPost($sms_messages);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SMSApi->smsSendPost: ', $e->getMessage(), PHP_EOL;
}
?>

he above code does the following, according to the comment numbers:

  1. Includes the Composer autoloader file that will load the library you installed.

  2. Configures the basic authentication by entering your username and API key, which you obtained earlier and should place in the code.

  3. Instantiates a new API object to connect to the ClickSend API to handle API requests.

  4. Creates a new message object to schedule using the SmsMessage() method.

  5. Sets the body of the message you want to schedule.

  6. Sets the phone number to send the SMS. The above is one of several example phone numbers that you can use.

  7. Sets the date and time for the scheduled SMS, which must be in Unix format. ClickSend uses this format because it's in universal time, so it’s the same for everyone regardless of time zone.

  8. Creates a new array of SmsMessage items and sets the message object you have created to the new SmsMessageCollection.

  9. Sends the message by using the API instance. If executed successfully, it will return the result in JSON format; otherwise, it will return an exception message.

Run the code

Run the following command in the terminal while you are in the project directory to execute the PHP code in the schedule.php file:

bash
php schedule.php

Evaluate the results

You should be able to see the following result in the terminal, formatted as a JSON string:

bash
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Messages queued for delivery.",
  "data": {
    "total_price": 0.1225,
    "total_count": 1,
    "queued_count": 1,
    "messages": [
      {
        "direction": "out",
        "date": 1654770216,
        "to": "+255737161310",
        "body": "We have a new offer for the upcoming holiday season. Visit our website to view the offers of various products you can buy.",
        "from": "ClickSend",
        "schedule": "1655206230",
        "message_id": "14B6C1C7-262F-4E63-91C4-7265F0E78EE7",
        "message_parts": 1,
        "message_price": "0.1225",
        "from_email": null,
        "list_id": null,
        "custom_string": "",
        "contact_id": null,
        "user_id": 335017,
        "subaccount_id": 380390,
        "country": "TZ",
        "carrier": "Tanzania Telecom",
        "status": "SUCCESS"
      }
    ],
    "_currency": {
      "currency_name_short": "USD",
      "currency_prefix_d": "$",
      "currency_prefix_c": "¢",
      "currency_name_long": "US Dollars"
    }
  }
}

In the above result, "http_code": 200 and "response_code": "SUCCESS" indicate that the request was completed successfully. The response_msg tells you that messages are queued for delivery, and the rest of the string shows the data that was submitted when executing the PHP code.

Cancel scheduled SMS message

If you want to cancel a planned text message because a scheduled event has passed or a sale is over, you can handle this easily.

To do this, you need to provide the message ID in the smsCancelByMessageIdPut() method. Create a PHP file called cancel.php and add the following code:

php
<?php
require_once(__DIR__ . '/vendor/autoload.php');  // #1

// Configure HTTP basic authorization: BasicAuth  #2 
$config = ClickSend\Configuration::getDefaultConfiguration()
    ->setUsername('USERNAME')
    ->setPassword('API_KEY');

$apiInstance = new ClickSend\Api\SMSApi(new GuzzleHttp\Client(), $config);  // #3
$message_id = "14B6C1C7-262F-4E63-91C4-7265C0E78JE7";  // #4

try {
    $result = $apiInstance->smsCancelByMessageIdPut($message_id);  // #5
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SMSApi->smsCancelByMessageIdPut: ', $e->getMessage(), PHP_EOL;
}
?>

The above code does the following, according to the comment number:

  1. Includes the Composer autoloader file that will load the library you installed.

  2. Configures the basic authentication by entering your username and API key.

  3. Instantiates a new API object to connect to the ClickSend API to handle requests.

  4. Adds the ID of the message you want to cancel in string format.

  5. Cancels the scheduled SMS by using the smsCancelByMessageIdPut() method.

After adding your username, API key, and message ID to the code, run the following command in the terminal:

php
php cancel.php

The results will be displayed in JSON format after executing the PHP code, indicating that the cancellation request for the scheduled SMS was successful:

php
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Scheduled SMS message has been cancelled.",
  "data": []
}

Easy set-up for set-and-forget messages

Scheduled messages are useful to help businesses interact with their audience and increase productivity of internal teams. We love working with developers and our well-loved API docs make set-up and programming easy.

Sign up to see how easy it is to add custom, scheduled SMS to your PHP-based systems.

Related Posts