> ## Documentation Index
> Fetch the complete documentation index at: https://onextel-09023014.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CleverTap WhatsApp

> Send WhatsApp from CleverTap campaigns through OneXtel, with RCS or SMS fallback — provider setup, template import, fallback keys, callbacks, and how each status and error code reaches CleverTap.

The CleverTap connector also adds WhatsApp as a sendable channel inside CleverTap. You add a
**Generic WhatsApp** provider in CleverTap and point it at the connector, which translates each
send into a OneXtel WhatsApp message and relays delivery reports, replies, and clicks back.

The recipient gets a native WhatsApp message from your registered business number. If you add a
fallback, OneXtel sends the same message over **RCS**, **SMS**, or both when the WhatsApp message
fails or is not delivered in time.

This page covers WhatsApp only. For RCS and standalone SMS from CleverTap, see
[CleverTap](https://onextel-09023014.mintlify.site/plugins/clevertap.md).

## What it handles

> [card] Template messages
>
> Approved WhatsApp templates with text and media headers, body variables, buttons,
> limited-time offers, and carousels.

> [card] Freeform messages
>
> Text, image, video, document, and audio messages inside an open 24-hour conversation.

> [card] 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.

> [card] Template import
>
> CleverTap imports your approved OneXtel WhatsApp templates straight from the connector.

> [card] 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](https://onextel-09023014.mintlify.site/guides/platform/api-keys.md). 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](https://onextel-09023014.mintlify.site/guides/platform/callback-configuration.md).
* **For fallback:** a Fallback ID from the OneXtel portal — see
  [Configure fallback](https://onextel-09023014.mintlify.site/guides/omnichannel/configure-fallback.md) — 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](https://onextel-09023014.mintlify.site/guides/sms/dlt.md).

### Connector endpoints

| Purpose | Method | URL |
| - | - | - |
| WhatsApp send | `POST` | `https://ct.onex-aura.com/whatsapp/send` |
| Template import | `GET` | `https://ct.onex-aura.com/whatsapp/templates` |
| WhatsApp delivery reports | `POST` | `https://ct.onex-aura.com/whatsapp/dlr` |
| WhatsApp inbound replies | `POST` | `https://ct.onex-aura.com/whatsapp/inbound` |
| WhatsApp URL clicks | `POST` | `https://ct.onex-aura.com/whatsapp/click` |
| RCS fallback delivery reports | `POST` | `https://ct.onex-aura.com/dlr` |
| SMS fallback delivery reports | `POST` | `https://ct.onex-aura.com/delivery` |

> [!WARNING]
>
> **The host is `onex-aura.com`, with a hyphen.** `ct.onexaura.com` resolves to a real server that
> does not run the connector, so the mistake shows up as a timeout or a silent failure rather than
> a DNS error.

## Set up

| Part | What you do | Where |
| - | - | - |
| [A](#part-a-—-create-the-generic-whatsapp-provider) | Create the Generic WhatsApp provider | CleverTap |
| [B](#part-b-—-import-your-templates) | Import your approved templates | CleverTap |
| [C](#part-c-—-configure-the-callbacks) | Configure the callbacks | OneXtel |
| [D](#part-d-—-build-the-campaign) | Build the campaign, with or without fallback | CleverTap |
| [E](#part-e-—-send-and-validate) | Send to a test audience, validate, then go live | Both |

### 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**

| Field | Value |
| - | - |
| Request Type | `POST` |
| HTTPS Endpoint | `https://ct.onex-aura.com/whatsapp/send` |
| Authentication | No Authentication |
| Headers | Key `apikey` → your OneXtel API key |
| WABA number | Your WhatsApp business **phone number** with country code |

> [!WARNING]
>
> **Enter the business phone number, not the WABA ID.** OneXtel identifies the WhatsApp
> account from the number. A WABA ID in this field is refused on every send as an invalid
> sender.

**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-c-—-configure-the-callbacks).

| URL | Used for |
| - | - |
| Delivery Report Callback URL | Delivery reports, clicks, and fallback outcomes |
| Inbound Message Callback URL | Customer replies |

### 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:

| Field | Value |
| - | - |
| Method | `GET` |
| URL | `https://ct.onex-aura.com/whatsapp/templates` |
| Header | Key `apikey` → your OneXtel API key |
| Header | Key `wabaid` → your WABA ID |

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 named `callback`, set to one of the CleverTap URLs you copied in Part A. All use **HTTP
Method `POST`**.

| Webhook | Channel | Type | Callback URL | `callback` header |
| - | - | - | - | - |
| WhatsApp DLR | WhatsApp | Delivery Notification | `https://ct.onex-aura.com/whatsapp/dlr` | Delivery Report URL |
| WhatsApp inbound | WhatsApp | Incoming | `https://ct.onex-aura.com/whatsapp/inbound` | **Inbound Message URL** |
| WhatsApp URL click | WhatsApp | URL Click | `https://ct.onex-aura.com/whatsapp/click` | Delivery Report URL |

**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:

| Webhook | Channel | Type | Callback URL | `callback` header |
| - | - | - | - | - |
| RCS fallback DLR | RCS | Delivery Notification | `https://ct.onex-aura.com/dlr` | Delivery Report URL |
| SMS fallback DLR | SMS | Delivery Notification | `https://ct.onex-aura.com/delivery` | Delivery Report URL |

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.

> [!WARNING]
>
> **A missing callback fails silently.** A report that arrives without the `callback` header is
> rejected with code `2004` and never reaches CleverTap. A fallback whose RCS or SMS delivery
> callback sits on a different API key never reports its outcome at all. Never save a callback with
> an empty header row either — OneXtel then sends a header with no name, which the connector's web
> server refuses.

See [Callback configuration](https://onextel-09023014.mintlify.site/guides/platform/callback-configuration.md) 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](#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](#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](https://onextel-09023014.mintlify.site/guides/omnichannel/configure-fallback.md).
* **The campaign's key-value pairs** carry the **content** for each fallback channel: which sender
  and template to use, and the SMS text.

OneXtel sends the fallback when the WhatsApp message fails, or when no delivered or failed status
arrives within the wait time. A WhatsApp message that is delivered does not fall back. See
[Fallback overview](https://onextel-09023014.mintlify.site/guides/omnichannel/fallback-overview.md).

The `fallback_id` key is the switch. Without it, every other fallback key is ignored and the
campaign sends WhatsApp only.

### Fallback keys

| Key | Required | Notes |
| - | - | - |
| `fallback_id` | For any fallback | The Fallback ID from the OneXtel portal |
| `fallback_waittime` | No | Seconds to wait for a WhatsApp status before falling back. Default `30` |
| `fallback_rcs_sender` | For an RCS leg | Your OneXtel RCS sender profile — a name, not a phone number |
| `fallback_rcs_template` | For an RCS leg | The OneXtel RCS template code to send |
| `fallback_rcs_message_type` | No | `Promotional` or `Transactional`. Default `Promotional` |
| `fallback_sms_sender` | For an SMS leg | Your DLT sender ID, for example `ONEXTL` |
| `fallback_sms_body` | For an SMS leg | The SMS text. Must match the DLT template word for word |
| `fallback_sms_templateId` | With `fallback_sms_entityId` | The DLT template ID |
| `fallback_sms_entityId` | With `fallback_sms_templateId` | Your DLT entity ID |
| `fallback_sms_type` | No | The DLT category. Default `SI` |

Set the RCS keys, the SMS keys, or both. With both, the Fallback ID's channel order decides which
leg OneXtel tries first.

> [!WARNING]
>
> **Check the Fallback ID character for character.** OneXtel accepts an unknown Fallback ID without
> an error, and the campaign then goes out as WhatsApp only. Nothing in CleverTap shows that the
> fallback is missing — confirm it with a test send to a number that is not on WhatsApp.

**Example — WhatsApp with RCS fallback:**

| Key | Value |
| - | - |
| `fallback_id` | `4f2005fa-…` |
| `fallback_rcs_sender` | `Acme_1` |
| `fallback_rcs_template` | `order_update_rcs` |
| `fallback_rcs_message_type` | `Transactional` |
| `fallback_waittime` | `60` |

**Example — WhatsApp with SMS fallback:**

| Key | Value |
| - | - |
| `fallback_id` | `4f2005fa-…` |
| `fallback_sms_sender` | `ONEXTL` |
| `fallback_sms_body` | Your DLT-approved text |
| `fallback_sms_templateId` | Your DLT template ID |
| `fallback_sms_entityId` | Your DLT entity ID |
| `fallback_sms_type` | `SI` |

### 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**:

| RCS placeholder | Filled from |
| - | - |
| `[var1]`, `[var2]`, … | WhatsApp body variables `{{1}}`, `{{2}}`, …, in order |
| `[header_var1]` | The WhatsApp text header's variable |
| `[media_url]` | The WhatsApp media header's URL |
| `[button0_url]`, `[button1_url]`, … | A dynamic URL button's value, by the button's zero-based position in the template |

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 sends `fallback_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 a
`fallback_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.**

Without a fallback, the same content is sent to WhatsApp as it is.

## Messages you can send

### Templates

| Component | Supported |
| - | - |
| Body variables | Yes, in template order |
| Text header | Yes, with its variable |
| Image, video, or document header | Yes. The media URL must be a public `http` or `https` link |
| Dynamic URL button | Yes |
| Quick reply button | Yes, with its payload |
| Copy-code button | Yes, with the coupon code |
| Limited-time offer | Yes, with its expiry time |
| Carousel | Yes, up to 10 cards |
| Static URL and phone-number buttons | Fixed by the approved template, so nothing is sent for them |

> [!NOTE]
>
> **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.

| Type | Content |
| - | - |
| Text | The message body |
| Image | Media URL, optional caption |
| Video | Media URL, optional caption |
| Document | Media URL, optional caption and file name |
| Audio | Media URL |

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 a `ttl` 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.

| WhatsApp status | CleverTap status |
| - | - |
| `sent` | `sent` |
| `delivered` | `delivered` |
| `read` | `read` |
| `failed` | `failed`, with a code from [Delivery failure codes](#delivery-failure-codes) |
| URL click | `clicked`, with the long and short URL |

**Fallback outcomes** land on the same message:

| Fallback report | CleverTap status |
| - | - |
| RCS `MESSAGE_DELIVERED` | `delivered` |
| RCS `MESSAGE_READ` | `read` |
| RCS `SEND_MESSAGE_FAILURE` | `failed`, code `1009` |
| RCS `SEND_MESSAGE_SUCCESS` | Not forwarded — CleverTap already has `sent` for the message |
| SMS delivered (OneXtel code `000`) | `delivered` |
| SMS failed (any other code) | `failed`, code `1009` |

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.

> [!NOTE]
>
> **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 as `replied` events with channel `WhatsApp`, including messages
a customer sends without replying to a campaign.

| Reply | What CleverTap receives |
| - | - |
| Text | The text |
| Quick reply or list selection | The button's title as the text, and its payload as `postback` |
| Location | Latitude and longitude, and the address as text when present |
| Image, video, audio, document, sticker | The media URL |

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

| Code | Meaning |
| - | - |
| `2000` | The `apikey` header is missing |
| `2001` | The request cannot be sent as it stands — a missing message ID or template name, a recipient that is not a valid Indian mobile number, an incomplete fallback, content refused under [What a fallback campaign cannot contain](#what-a-fallback-campaign-cannot-contain), a media value that is not a URL, or a OneXtel rejection that names the template |
| `2004` | OneXtel refused the message — for example an invalid sender number — or could not be reached, or the connector is at capacity. The `message` carries the reason |

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.

> [!NOTE]
>
> **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](https://onextel-09023014.mintlify.site/api-reference/whatsapp/error-codes.md).

| CleverTap code | Covers | Meta codes |
| - | - | - |
| `1002` | Recipient cannot be reached on WhatsApp | `131026`, `131005`, `133010` |
| `1003` | Number no longer valid | `131021` |
| `1004` | Rate, spam, or marketing-frequency limits, or a paused template | `130429`, `131048`, `131049`, `132015` |
| `1005` | Temporary or media upload failure | `131000`, `131016`, `131053` |
| `1006` | Blocked by the user or by policy | `131047`, `368` |
| `1007` | Message type the device cannot show | `131051` |
| `1008` | Outside the 24-hour window, or a media download failure | `470`, `131052` |
| `1010` | Template refused by Meta | `132000`, `132001`, `132005`, `132007`, `132012` |
| `1009` | Any other failure, and every failed fallback | — |

### Callback responses

When a OneXtel callback arrives without its `callback` 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_body` is 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.

## Get support

If a campaign does not behave as this page describes, email
[omni.tech@onextel.com](mailto:omni.tech@onextel.com) with the plugin name (CleverTap WhatsApp),
the provider nickname, the CleverTap campaign ID, and what you saw.

## Related

* [CleverTap — RCS and SMS](https://onextel-09023014.mintlify.site/plugins/clevertap.md)
* [WhatsApp API overview](https://onextel-09023014.mintlify.site/api-reference/whatsapp/overview.md)
* [WhatsApp error codes](https://onextel-09023014.mintlify.site/api-reference/whatsapp/error-codes.md)
* [Fallback overview](https://onextel-09023014.mintlify.site/guides/omnichannel/fallback-overview.md)
* [Configure fallback](https://onextel-09023014.mintlify.site/guides/omnichannel/configure-fallback.md)
* [DLT registration](https://onextel-09023014.mintlify.site/guides/sms/dlt.md)
* [All plugins](https://onextel-09023014.mintlify.site/plugins/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.