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

1. Download and install Ruby (choose the first installer in the 'WITH DEVKIT' list).
2. Install json if you haven’t already “gem install json”
3. Install ClickSend client “gem install clicksend_client”

Full snippet

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.

            
                # load the gem
require 'clicksend_client'
require 'json'

# setup authorization
ClickSendClient.configure do |config|
  config.username = USERNAME
  config.password = 'API_KEY'
end

api_instance = ClickSendClient::SMSApi.new

# SmsMessageCollection | SmsMessageCollection model
sms_messages = ClickSendClient::SmsMessageCollection.new

sms_messages.messages = [
  ClickSendClient::SmsMessage.new(
    "to": "TO_PHONE_NUMBER",
    "source": "SOURCE",
    "body": "MESSAGE"
  ),
]

begin
  # Send sms message(s)
  result = api_instance.sms_send_post(sms_messages)
  p JSON.parse(result)
rescue ClickSendClient::ApiError => e
  puts e
  puts "Exception when calling SMSApi->sms_send_post: #{e.response_body}"
end

            
        

The code explained

Import functions

Start by preparing your environment to use the ClickSend API. Import the necessary modules, including the ClickSend client library and exception handling classes.

            
                require 'clicksend_client'
require 'json'
            
        

Authorisation

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 USERNAME and API_KEY placeholders with your own Username and API Key. These can be found on the Dashboard here.

            
                ClickSendClient.configure do |config|
  config.username = USERNAME
  config.password = 'API_KEY'
end
            
        

Create an instance of the API class

The following line of code will create an instance of the ACCOUNTAPI class, which is configured to use the APICLIENT with the credentials that we set up in the previous step. This instance will allow you to interact with the ClickSend API's account-related functionality.

            
                api_instance = ClickSendClient::SMSApi.new
            
        

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.

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

            
                sms_messages = ClickSendClient::SmsMessageCollection.new

sms_messages.messages = [
  ClickSendClient::SmsMessage.new(
    "to": "+61411111111",
    "source": "myNumber",
    "body": "test 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 formatted response.

If an exception occurs during the API call, it catches the APIEXCEPTION and prints an error message with the exception details. This structure helps you handle both successful API calls and potential errors that might occur during the process.

            
                begin
  # Send sms message(s)
  result = api_instance.sms_send_post(sms_messages)
  p JSON.parse(result)
rescue ClickSendClient::ApiError => e
  puts e
  puts "Exception when calling SMSApi->sms_send_post: #{e.response_body}"
end