What it handles
Template messages
Approved WhatsApp templates with text and media headers, body variables, buttons,
limited-time offers, and carousels.
Freeform messages
Text, image, video, document, and audio messages inside an open 24-hour conversation.
RCS and SMS fallback
If WhatsApp fails or is not delivered within the wait time, OneXtel retries over RCS, SMS,
or both, in the order your fallback configuration sets.
Template import
CleverTap imports your approved OneXtel WhatsApp templates straight from the connector.
Delivery, replies, and clicks
Sent, delivered, read, failed, and clicked statuses, plus customer replies, relayed into
CleverTap — including the outcome of a fallback.
Before you start
Have these ready:- Your OneXtel API key — see API keys. The same key must own your WhatsApp sender, your fallback senders, and every callback on this page.
- Your WhatsApp business number — the registered phone number with country code, for
example
919876543210. You also need its WABA ID for template import. - Approved WhatsApp templates on that WABA in OneXtel.
- CleverTap access to Settings → Channels → WhatsApp, with permission to add a provider.
- OneXtel access to callback configuration.
- For fallback: a Fallback ID from the OneXtel portal — see Configure fallback — plus an RCS sender and template for an RCS leg, or a DLT-registered SMS sender and template for an SMS leg. See DLT registration.
Connector endpoints
Set up
Part A — Create the Generic WhatsApp provider
1
Create the provider
In CleverTap, go to Settings → Channels → WhatsApp, add a provider, and choose
Generic WhatsApp. There is no OneXtel-specific entry in CleverTap’s list; the generic
provider pointed at the connector is the integration.
2
Set the messaging endpoint
3
Save the provider
When you save, CleverTap sends a validation request to the endpoint. The connector answers it
directly and sends no message, so saving costs nothing and reaches no one.
4
Copy the callback URLs
Reopen the saved provider and copy the URLs under Callback Config. You paste them into
OneXtel in Part C.
Part B — Import your templates
CleverTap can pull your approved WhatsApp templates from the connector, so campaign builders pick from the same list OneXtel will send. In the provider’s template import settings, enter:
Only approved templates are returned, 50 per page by default. The connector pages through the
full list for CleverTap, and you can import again whenever new templates are approved.
If the import fails, CleverTap shows an error rather than an empty list: a missing
wabaid header
is refused with HTTP 400, and a failure on the OneXtel side with HTTP 502. An empty, successful
import means the WABA has no approved templates under that key.
Part C — Configure the callbacks
Create these callbacks in OneXtel on the same API key as the provider. Each needs a custom header namedcallback, set to one of the CleverTap URLs you copied in Part A. All use HTTP
Method POST.
If you use fallback, OneXtel reports the fallback message on the RCS or SMS delivery callback,
not the WhatsApp one. Make sure these also exist on the same API key:
If you already created these for an RCS or SMS provider on the same key, keep them as they are —
one callback per channel serves both. The connector recognises a WhatsApp campaign’s fallback
report and records it against the original WhatsApp message in CleverTap.
See Callback configuration for how to add a callback
and its headers.
Part D — Build the campaign
1
Create the campaign
In CleverTap, create a WhatsApp campaign. Under From, select the provider from Part A,
and choose your audience under Who.
2
Choose the message
Under What, pick an imported template and fill its variables, media, and button values.
CleverTap sends them in template order, and the connector passes them to OneXtel in that same
order.To send a freeform message instead, choose a non-template message. Freeform messages reach
only recipients who messaged your business number in the last 24 hours — outside that window,
WhatsApp fails the message.
3
Add fallback, if you want it
Add the fallback keys below as the campaign’s custom key-value pairs. Leave them all out for
a WhatsApp-only campaign. See Fallback for what each key does.
4
Save the campaign as a draft
Save it, but do not publish until the Part C callbacks are in place — otherwise reports from
the first send never reach CleverTap.
Part E — Send and validate
1
Publish to a test audience
Send to test devices you control. For a fallback check, include a number that is not on
WhatsApp.
2
Confirm the send was accepted
A refused send comes back in the provider’s reply with a code and a reason — see
Send responses.
3
Confirm delivery
The message arrives on WhatsApp, and sent, delivered, and read appear in CleverTap’s campaign
stats.
4
Confirm replies
A reply from a test device appears in CleverTap in that profile’s event timeline.
5
Confirm fallback
The send to the non-WhatsApp number fails on WhatsApp, the RCS or SMS message arrives, and
the outcome appears on the same message in CleverTap.
6
Go live
Once each check passes, send the campaign to your full audience.
Fallback
A fallback has two halves, and you set them in different places:- The Fallback ID, created in the OneXtel portal, holds the channel order — RCS first, SMS first, or one channel only. See Configure fallback.
- The campaign’s key-value pairs carry the content for each fallback channel: which sender and template to use, and the SMS text.
fallback_id key is the switch. Without it, every other fallback key is ignored and the
campaign sends WhatsApp only.
Fallback keys
Set the RCS keys, the SMS keys, or both. With both, the Fallback ID’s channel order decides which
leg OneXtel tries first.
Example — WhatsApp with RCS fallback:
Example — WhatsApp with SMS fallback:
Name the RCS fallback template’s variables
WhatsApp variables are numbered by position; OneXtel RCS templates fill[placeholder] names. The
connector bridges the two with fixed names, so the RCS fallback template must use exactly these
placeholders:
A placeholder with any other name is left unfilled on the handset, and the send still succeeds —
so the fallback fires but the message reads wrong.
The SMS leg carries its own text
The SMS fallback does not reuse the WhatsApp template’s text. It sendsfallback_sms_body
exactly as you enter it, so every recipient of the campaign gets the same SMS.
Send fallback_sms_templateId and fallback_sms_entityId together, or leave both out when your
API key has DLT template auto-match enabled. A send with only one of the two is refused.
What a fallback campaign cannot contain
A fallback must be renderable on RCS or SMS, so some WhatsApp content is refused when afallback_id is present. The send is answered with code 2001 and a reason naming the
component:
- Carousel templates with an RCS fallback. RCS has no equivalent for the cards.
- Location headers or location parameters, and product headers.
- Catalog, multi-product, flow, order-details, voice-call, and OTP buttons.
- Order-status, product-list, and catalog components.
Messages you can send
Templates
Media must be a link WhatsApp can download. The connector refuses a media value that is not an
http or https URL, with code 2001. Upload references from a template’s sample media are not
URLs and cannot be used at send time.Freeform messages
Freeform messages are for an open conversation — a customer who messaged your business number in the last 24 hours.
A text message with no body, or a media message with no URL, is refused with code
2001.
Message validity
To limit how long OneXtel keeps trying to deliver, add attl key-value pair to the campaign,
for example 60s. The connector passes it to OneXtel unchanged.
Delivery statuses
WhatsApp reports reach CleverTap through CleverTap’s own WhatsApp callback, keyed on the message ID CleverTap sent. They do not use the event format of the RCS and SMS channels.
Fallback outcomes land on the same message:
A failed fallback always carries
1009, with OneXtel’s own reason as the failure title. CleverTap’s
WhatsApp codes describe WhatsApp failures, not RCS or SMS operator ones.
One message can report
failed and then delivered. When WhatsApp fails and the fallback
then succeeds, CleverTap first receives WhatsApp’s failure and then the fallback’s delivery, both
for the same message.Replies
Customer replies reach CleverTap asreplied events with channel WhatsApp, including messages
a customer sends without replying to a campaign.
Other reply types are not relayed.
Error codes
Send responses
The connector answers every send in the form CleverTap’s WhatsApp provider reads:status of
success or failure, and on failure an error with a code and a message.
Codes
2000 and 2001 for a missing header or a malformed body come back with HTTP 400; every
other outcome comes back with HTTP 200 and the verdict in the body.
An accepted send is not a delivered one. OneXtel checks the sender when you send, but a
template name that does not exist on the WABA is accepted and fails later as a delivery report.
Delivery failure codes
WhatsApp failures carry Meta’s error code. The connector maps it onto CleverTap’s WhatsApp callback codes and sends Meta’s own description as the failure title. For what each Meta code means, see WhatsApp error codes.Callback responses
When a OneXtel callback arrives without itscallback header, the connector answers 2004 and
does not relay the report.
Limitations
- India only. Recipients must be Indian mobile numbers — 10 digits in the 6–9 series, with or
without
91. - The SMS fallback text is the same for every recipient.
fallback_sms_bodyis sent as entered; campaign variables are not substituted into it. - Failed fallbacks report a single code. Every failed RCS or SMS fallback reaches CleverTap as
1009; the operator’s reason is in the failure title and in OneXtel reporting. - Carousels cannot fall back to RCS.
- Freeform messages need an open conversation. Outside the 24-hour window, WhatsApp fails them.
- Clicks come from OneXtel-tracked links only. WhatsApp itself reports no button clicks.