Getting started with One API
Archived on 31 August 2020
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 portal
Sign up and create your free Clickatell account. Once you’ve verified your account, log in to your Clickatell portal. The first page you see is the Launchpad which is the home page that gives you an overview of the channels and products available in Clickatell and also gives you a summary of all the channels and products you have activated on your account. From here you can activate and set up the channels and products that you want to utilize. You can also use the left panel to navigate to the specific sections for more details.
Step 2: Acquire a number
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.
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 do not allow the sending of one-way messages.
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.
You can also purchase short codes / long numbers by navigating to My Workspace –> SMS and then Get Long Number or Get Short Code.
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 use to configure your integration:
- Enable delivery notifications and specify how callbacks should be returned to your system
- Enable Authentication for the above (optional)
- Enable message parts
Your One API Details are displayed.
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 when you click ‘Apply Now‘ from your Launchpad and follow the prompts. The number you will use for your business WhatsApp account forms part of this application and will only be available once your application has been approved by WhatsApp. Clickatell provides you with a demo number to use for testing while you await approval.
There are several settings you can edit to customize your integration to fit your needs, e.g. around reply callbacks and status notifications. You can also select the channels you want to activate on this API.
To activate the WhatsApp channel on your One API, switch the toggle next to ‘WhatsApp Channel‘ to ‘On‘.
- If you don’t have the WhatsApp channel set up yet, you will be prompted to ‘Apply for a WhatsApp number‘. This will take you through the same process as stipulated in the WhatsApp Channel section.
- If you have approved WhatsApp profiles/numbers already, you can select the one you want to link to this One API from a drop-down.
Once you are happy with your setup, click on the ‘Generate API‘ button.
Your newly generated API Key and Integration ID will be displayed on the screen.
At the bottom of the page an example is displayed of how to send an API call:
To view and edit your One API setup at any stage, navigate to ‘My APIs → Configure One API‘ from the panel on the left, and select the integration you want to view and/or edit from the table.
Step 4: Add test phone numbers (optional)
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. All messages sent to your test phones are free.
Note: Your test phones only apply for a Sandbox integration. For a Production integration, all destination numbers are billable.
To add test phones, click the ‘Add a Test Phone‘ button on your Launchpad and follow the prompts. Once at least one test phone has been set up, you can test your API.
Step 5: Publish your integration on the Production environment
To configure a production-ready integration, or to publish your integration from the Sandbox to the Production environment, you need to complete your company billing details first. 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.
Once you are happy with your API setup, have tested it in your Sandbox environment, and have setup your billing details, you can publish it to Production by navigating to ‘My APIs → Configure One API‘ and selecting the API setup you want to publish from the table. Change the integration type to ‘Production’ and click ‘Save Changes‘ at the bottom of the page.
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