In this short tutorial, we introduce you to Clickatell’s SMS HTTP API and how it can be used to communicate with end-users.
You can also use our One API to engage with customers via the SMS channel. For more information, see here.
Why use this API?
This API enables one- and two-way communication with your customers via SMS messages. You can send one or more SMS messages by making HTTPS calls directly to the API. You can also configure your integration to cater for two-way messaging by specifying a message status callback method and destination.
When to use this API?
This API is ideal if you want to send bulk SMS messages securely, reliably and instantly. You can SMS-enable any application, website or system and facilitate international two-way messaging with an easy one-step integration process. SMS is a budget-conscious channel between your business and mobile users all across the world and enables you to cut costs and scale faster. The API supports the UTF8 character set.
Note: If you are planning to make use of other communication channels in addition to SMS, now or in the future, you might want to consider using our One API instead.
Getting started with the SMS API
Step 1: Register your Clickatell account & log in to the portal
Sign up and create your free Clickatell account. Once you’ve verified your account, log in to the Clickatell portal. From the Products & Services tab, you can activate the channels and products that you want to utilize. The My Workspace tab provides access to all the channels and products you have activated on your account and allows you to configure and manage each.
To activate SMS as a channel on your account, click on the SMS card under Channels on the Products & Services tab and click on the ‘+ Activate channel’ button. This will add SMS as a channel under the My Workspace tab.
Step 2: Add new SMS setup
Navigate to My Workspace –> SMS and click the ‘+New SMS Setup‘ button. A setup wizard will take you through the required steps to set up your new SMS integration. The resulting API Key is the authentication token used to call and unlock your specific integration service.
Step 2.1: Setup type and regions
In the first step, indicate how you want to use your SMS channel. In this case, select API. (For information on using the Campaign Manager tool, see here.)
You also need to select the type of messages you plan on sending:
- One-way SMS: If you only want to send SMS messages (i.e. no replies required), you do not require a dedicated number. Note: country-specific regulations may apply since certain countries do not allow the sending of one-way messages.
- Two-way SMS: If you want to both send SMS messages and receive replies, you need to acquire a two-way number. You can either apply for a short code or purchase a long number by selecting your preferred option and following the prompts.
If you’ve selected two-way communication, you will also be required to select whether you want to use a long number or a short code, and for each of these indicate whether you are using an existing number or need to purchase a new one.
Step 2.2: Select API type
In the next step, select Basic HTTP API. You can either link an existing API integration to this SMS setup or create a new one.
Step 2.3: Setup API details
Note: this step is skipped if you selected an existing API to link to this setup.
Enter a name for your new API and select whether this must be added in the Sandbox (recommended) or Production environment. Select the delivery type (standard or time-critical). There are several other optional settings you can edit by using the toggles, e.g. enabling message parts and delivery notifications. Click ‘Next‘.
Step 2.4: API details and testing (optional)
Your API details are displayed. The unique API key is the authorization key you need to interface with the Clickatell platform. The API key is prepopulated in our example scripts which you can copy and paste.
To test the sending and/or receiving of messages from the Sandbox environment, you can add up to three test phone numbers to your account. Click on the ‘+ Add number’ button and follow the prompts. Note that phone numbers must be entered in international format and must contain no spaces or other non-numeric characters.
Note: All messages to test phone numbers are free. Once the integration is promoted to production, you will be charged for messages sent.
Click ‘Complete‘. Your new SMS Setup will be added to your ‘My SMS Setups‘ table from where you can view and manage it.
Step 3: Activate your API on Production
Once you are happy with your API setup, have tested it in your Sandbox environment, and have set up your billing details, you can publish it to Production by navigating to My Workspace –> SMS or My Workspace –> API Integrations and selecting the API integration you want to publish from the table. Change the setup type to ‘Production’ and click ‘Update Changes‘ at the top right of the page.
Step 4: Using your API
To view and edit the details of your API, navigate to My Workspace –> SMS or My Workspace –> API Integrations. Click on the relevant API from the table. From here you will be able to update any of your API details or move the API integration back into the Sandbox. You can also view the API Key and renew it if it was compromised. It gives you access to the code library of your integration with an example. To send your first message, you can simply copy this example URL directly into your web browser replacing the text message with your own. The server will respond with a unique identifier for each message (referred to as an API Message ID). This API Message ID can be used to track and monitor the status of your message.
Note: You will only be able to send messages in your Production environment if you have added a payment method and topped up your balance. Where test messages are free, the cost for live messages is subtracted from your account balance.
Submit a Comment
Ask the Community
Visit Stack Overflow to join our community of developers and find the answer you need
Contact our support team and one of our agents will be in touch with you to answer any questions you have