Loader

Getting started


Overview

In this short tutorial, we introduce you to Clickatell’s One API and how it can help reduce the cost of development and assist you with scaling your messaging.


Why use this API?

Clickatell’s RESTful-based One API allows you to communicate with your mobile customers on multiple communication channels with a single integration. Using the One API, you will be able to send and receive messages on both WhatsApp and SMS without the overhead of programming individual channels. One API makes your implementation future-proof as we continue to add support for additional channels to the Clickatell platform.

Encryption can be configured and enabled for secure messaging needs. Unified reporting also allows for a single view of all your messaging activity regardless of the channel.

 

Message types available for each available channel:

Message Type
SMS
WhatsApp
Plain text Yes Yes
Rich text No Yes
Plain text with URL support No Yes
Templated message No Yes
Media No Yes
 

When to use this API

Use the One API if you want to engage with customers via both WhatsApp and SMS channels, or are planning to scale your messaging and add more channels in the future as they become available. With One API you only need to integrate once and Clickatell handles the interpretation of all the different channel requirements.


Getting started with the One 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. 

 

Step 2: Create a new channel setup

You will have the opportunity to configure a One API integration whenever you add a new SMS or WhatsApp setup to your account.

SMS 

When creating a new SMS setup from the user portal, a wizard will take you through all the steps required.

Firstly, you have a choice between using an API or the Campaign Manager tool. Select API. Before configuring your One API integration, determine whether you need to acquire a number. This depends on the type of messages you plan to send with this SMS setup: 

  • One-way SMS: If you only want to send SMS messages (i.e. no replies required), you can do that straight-away without applying for a dedicated number. Note: country-specific regulations may apply since certain countries (e.g. Canada, USA) 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 an option and following the prompts. If you have already purchased a long number or short code, you can connect it to this SMS setup by selecting it from the drop-down. 

You can also purchase short codes / long numbers by navigating to My Workspace –> SMS and then selecting Get Long Number or Get Short Code.

 

In the next step, select One API. You can either link an existing One API integration to this SMS setup or create a new one. 

 

Finally, enter a name and description for your new One API, and select the type of integration (Sandbox or Production).

Note: we recommend setting up your integration in Sandbox so you can test it before deploying it to production where it will be live and available to your end-users.

There are several API and SMS channel settings you can configure, such as:

  • Delivery notifications and callbacks
  • Authentication for the above (optional)
  • Enabling message parts 
  • Various two-way SMS settings

 

Upon clicking ‘Next’ your API integration is created and a unique API key is displayed. This is the authorization key you need to interface with the Clickatell platform (also see One API Reference). The API key is prepopulated in our example scripts which you can copy and paste. Click ‘Complete‘.

 

WhatsApp

To use WhatsApp as a communication channel, you will automatically make use of Clickatell’s One API.

If you want to configure the WhatsApp channel for your account, your business first has to be verified by WhatsApp themselves. Clickatell assists you in submitting your application via a setup wizard when you click ‘+ Create New WhatsApp account‘ from your My Workspace tab.

 

Once you have submitted your application, you can test your WhatsApp integration while awaiting approval using the test One API integration and temporary demo number that Clickatell provides you with. There are several settings you can edit, but since this is a test profile and number you will not be able to edit the name, number or setup type at this point.

 

Upon clicking ‘Next’ your test One API integration is created and a unique API key is displayed. This is the authorization key you need to interface with the Clickatell platform (also see One API Reference). The API key is pre-populated in our example scripts which you can copy and paste.

 

Once your application has been approved and your WhatsApp Business account is active, you can set up a new business profile with your display name and business phone number, and apply for template messages.

 

Step 3: View and edit One API integrations

You can view and update your One API integrations at any stage by navigating to My Workspace –> API Integrations and selecting the API you are interested in from the table.

 
Step 4: Publish your integration on the Production environment 

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 –> 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.

Note: If you have WhatsApp as a channel, you can only promote the integration to Production once your WhatsApp application has been approved and your number verified.

 

 

Did you find this information informative?

Other Resources

Ask the Community

Visit Stack Overflow to join our community of developers and find the answer you need

Contact Support

Contact our support team and one of our agents will be in touch with you to answer any questions you have