# CTA URL Button Messages

> Send a single call-to-action URL button via WhatsApp

CTA URL button messages map a destination URL to a labeled button. Users never see the raw link — they tap the button and the URL opens in their default browser.

Use this when you want to drive traffic from WhatsApp to a web experience (a booking page, a product page, a checkout flow) without exposing a long, opaque URL in the message body.

## Send a CTA URL Message

```typescript
const message = await zavu.messages.send({
  to: "+14155551234",
  channel: "whatsapp",
  messageType: "cta_url",
  text: "Tap the button below to see available dates.",
  content: {
    ctaDisplayText: "See Dates",
    ctaUrl: "https://example.com/schedule?ref=zavu",
    ctaHeaderType: "image",
    ctaHeaderMediaUrl: "https://example.com/banner.png",
    footerText: "Dates subject to change."
  }
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "channel": "whatsapp",
    "messageType": "cta_url",
    "text": "Tap the button below to see available dates.",
    "content": {
      "ctaDisplayText": "See Dates",
      "ctaUrl": "https://example.com/schedule?ref=zavu",
      "ctaHeaderType": "image",
      "ctaHeaderMediaUrl": "https://example.com/banner.png",
      "footerText": "Dates subject to change."
    }
  }'
```

## Specifications

| Property | Requirement |
|----------|-------------|
| Body text (`text`) | Required, max 1024 chars |
| `ctaDisplayText` | Required, max 20 chars |
| `ctaUrl` | Required, valid URL (HTTPS required by WhatsApp in production) |
| `ctaHeaderType` | Optional: `text`, `image`, `video`, `document` |
| `ctaHeaderText` | Required if `ctaHeaderType` is `text`, max 60 chars |
| `ctaHeaderMediaUrl` | Required if `ctaHeaderType` is `image`, `video` or `document`. HTTPS URL that returns valid media |
| `footerText` | Optional, max 60 chars |

> **Tip:**
> The sender must have a WhatsApp Business Account connected. Header media URLs are fetched by WhatsApp — they must be publicly reachable and return the declared content type (e.g. `image/png` for an `image` header).

## Header Variants

### Text header
```json
"content": {
  "ctaDisplayText": "Book now",
  "ctaUrl": "https://example.com/book",
  "ctaHeaderType": "text",
  "ctaHeaderText": "New workshop dates announced!"
}
```

### Image header
```json
"content": {
  "ctaDisplayText": "Shop now",
  "ctaUrl": "https://example.com/sale",
  "ctaHeaderType": "image",
  "ctaHeaderMediaUrl": "https://example.com/sale-banner.jpg"
}
```

### Video header
```json
"content": {
  "ctaDisplayText": "Watch more",
  "ctaUrl": "https://example.com/learn",
  "ctaHeaderType": "video",
  "ctaHeaderMediaUrl": "https://example.com/teaser.mp4"
}
```

### Document header
```json
"content": {
  "ctaDisplayText": "Open PDF",
  "ctaUrl": "https://example.com/brochure",
  "ctaHeaderType": "document",
  "ctaHeaderMediaUrl": "https://example.com/brochure.pdf"
}
```

## No Webhook on Tap

> **Note:**
> Unlike reply [Buttons](https://www.zavu.dev/docs/guides/whatsapp/messages/buttons) and [Lists](https://www.zavu.dev/docs/guides/whatsapp/messages/list), **tapping a CTA URL button does not generate an inbound webhook**. The user is redirected directly to the destination URL inside their browser.
>
> To track clicks, append tracking parameters to `ctaUrl` (for example `?utm_source=whatsapp&clickID=abc123`) and read them on your landing page.

## 24-Hour Window

CTA URL messages are free-form interactive messages. They can only be sent inside an open 24-hour conversation window — typically after the user has messaged you first.

To initiate a conversation outside the window, send a [template message](https://www.zavu.dev/docs/guides/whatsapp/templates/sending) first, then follow up with a CTA URL message once the user replies.

## Use Cases

- Drive traffic to a booking or scheduling page
- Link to a checkout or product page from a promotion
- Share long campaign URLs without cluttering the message
- Replace raw URLs in receipts or confirmations with a branded button
- Direct users to a web form, survey, or support portal