SMS Quickstart

Before you start

1. You need a ClickSend account with credit to start sending. If you don’t have an account, create one here.
2. If you need to add more credit to your account, you can top up here. You’ll be credited $2 AUD free credit when you sign up.

Installation

Install via Github

Our Perl SDK is hosted on Github, and can be installed by downloading the repository and copying the contents of the lib directory to a location that perl searches.

Note: git needs to be installed first using your operating system’s usual method. e.g. “sudo apt update; sudo apt install git” for Debian/Ubuntu systems or “sudo yum install git” for RedHat/CentOS.

            
                git clone https://github.com/ClickSend/clicksend-perl.git
            
        

Copy the WWW directory and contents from the lib directory created above to your project’s directory or to one of the system locations that Perl searches. To view the locations that Perl searches on your system, run:

            
                perl -e 'for (@INC) { print "$_\n"; }'
            
        

Individual ClickSend modules can then be included in your code with the “use” directive. e.g.

            
                use WWW::ClickSendClient::SMSApi;
            
        

Send your first message

Below is the full snippet you can use to send an SMS. It includes placeholders that will need to be replaced when implementing the code in your project.

            
                #!/usr/bin/perl -w
use WWW::ClickSendClient::SMSApi;
use WWW::ClickSendClient::Object::SmsMessageCollection;

my $USERNAME = 'my-clicksend-username@example.com';
my $API_KEY = 'FEDC0123-0123-4567-89AB-CDEF01234567';
my $TO_PHONE_NUMBER = '+61411111111';
my $MESSAGE = "Test message from perl";

my $api = WWW::ClickSendClient::SMSApi->new(username => "$USERNAME",
password => "$API_KEY");

my $sms_messages = WWW::ClickSendClient::Object::SmsMessageCollection-
>new(
  messages => [{
    source => 'perl',
    to => "$TO_PHONE_NUMBER",
    body => "$MESSAGE"
  }]);
  
my $json_output = $api->sms_send_post(sms_messages => $sms_messages);

print $json_output;
            
        

The code: explained

Import functions

Start by preparing your environment to use the ClickSend API. Import the necessary modules, including the ClickSend SMS API and Message Collection object.

            
                use WWW::ClickSendClient::SMSApi;
use WWW::ClickSendClient::Object::SmsMessageCollection;
            
        

Authorisation and create an instance of the API class

Next, set up your Username and API Key so you can use the ClickSend API in your project.

In the following snippet, simply replace the placeholders $USERNAME and $API_KEY with your own Username and API Key. These can be found in the Dashboard here.

This API instance returned from this call will allow you to interact with the ClickSend API's account-related functionality.

            
                my $api = WWW::ClickSendClient::SMSApi->new(
username => "$USERNAME",
password => "$API_KEY");
            
        

Configure your message

Next, configure the content of your message and define who you’re sending to-and- from.

Here you will want to replace the placeholder ‘$SOURCE’ with your preferred source (eg. the name of your application). This is not seen by recipients but will help you to identify messages sent from various applications.

Replace “$MESSAGE” with a message of your choice, and replace “$TO_PHONE_NUMBER” with the number that you’ll be sending the message to.

For testing purposes, we recommend you start by sending to your own number.

The messages parameter is an array of hashes. Each hash makes up a single SMS message to be sent. In this example we only include a single SMS message.

For additional properties that you can use here, see the Full API Reference.

            
                my $sms_messages = WWW::ClickSendClient::Object::SmsMessageCollection-
>new(
  messages => [{
    source => "$SOURCE",
    to => "$TO_PHONE_NUMBER",
    body => "$MESSAGE"
  }]);

            
        

Send SMS message

Finally, try to call the SMS_SEND_POST method using the API_INSTANCE you've created. If everything works as expected then it will print the response as raw JSON. The outcome of the call can be seen from the http_code and response_code attributes in the JSON response. There is also an array called ‘messages’ within the ‘data’ structure and each message within this array has a ‘status’ attribute.the formatted response.

            
                my $json_output = $api->sms_send_post(sms_messages => $sms_messages);
print $json_output;