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. In this short tutorial, we introduce you to Clickatell’s SMS HTTP API and how it can be used to communicate with end-users via SMS.
You can also use our One API to engage with customers via the SMS channel.
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, and 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. 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, 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 the SMS card under Channels on the Products & Services tab and then 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 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. Select whether you want to use a long number or a short code and 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 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 to link an existing API in the previous step.
Enter a name for your new API. Select whether it must be added in the Sandbox (recommended) or Production environment and select the relevant SMS service class. There are several other optional settings you can edit by using the toggles, e.g. enabling message parts and delivery notifications.
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. Phone numbers must be entered in the international format and 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.
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
To publish your API integration to Production, navigate to My Workspace –> SMS or My Workspace –> API Integrations and select the API integration. Change the setup type to ‘Production’ and click ‘Update Changes‘ at the top right of the page.
Ensure you have tested the integration and have set up your billing details before publishing.
Step 4: Using your API
To view and edit the details of your API, or move the API integration back into the Sandbox, navigate to My Workspace –> SMS or My Workspace –> API Integrations and select the API from the table. You can also view and renew the API Key, and access the code library of your integration with an example.
To send your first message, 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