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:
|Plain text with URL support||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.
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 do not need 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 apply for a short code or purchase a long number. 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.
Note: 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 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.
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 and wait for approval, you can test your WhatsApp integration using the test One API integration and temporary demo number that Clickatell provides you.
Note: 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.
For more information about the WhatsApp application and setup process, see here.
Step 3: View and edit One API integrations
You can view and update your One API integrations by navigating to My Workspace –> API Integrations and selecting the API from the table.
Step 4: Publish your integration on the Production environment
To publish your API integration to Production, navigate to My Workspace –> API Integrations and select 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.
Make sure you have tested your API setup it in your Sandbox environment and have set up your billing details before publishing it.
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.
For more information on using the API, see the One API Reference document.
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