> ## Documentation Index
> Fetch the complete documentation index at: https://docs.demomatic.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# CTA Setup

> Add call-to-action overlays to your demo videos to capture leads or drive traffic to a booking link.

A CTA (call-to-action) is an overlay that appears with your demo video. Use it to collect lead information from viewers or send them to an external link — such as a Calendly booking page.

CTAs are configured per domain and apply to any video with `cta_enabled` set to `true`.

## CTA types

Demomatic supports two CTA types:

<CardGroup cols={2}>
  <Card title="Form" icon="file-text">
    Displays a modal form that collects information from the viewer. Submissions are stored as leads and accessible from your dashboard.
  </Card>

  <Card title="External link" icon="arrow-up-right">
    Displays a button that opens a URL in a new tab — for example, a Calendly scheduling link or a product page.
  </Card>
</CardGroup>

## Configure a CTA on your domain

Update your domain's CTA settings with `PUT /domains/:id`:

```bash theme={null}
curl -X PUT https://api.demomatic.tech/domains/123 \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cta_type": "form",
    "cta_action_text": "Book a Demo",
    "cta_modal_title": "Let'\''s connect",
    "cta_modal_description": "Fill out the form and we'\''ll be in touch.",
    "cta_modal_auto_open": true,
    "cta_use_organization_name": true,
    "cta_fields": [
      { "key": "name", "label": "Full name", "type": "text", "required": true },
      { "key": "email", "label": "Work email", "type": "email", "required": true },
      { "key": "company", "label": "Company", "type": "text", "required": false }
    ]
  }'
```

### Domain CTA fields

| Field                       | Type                        | Description                                                                                              |
| --------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------- |
| `cta_type`                  | `"form" \| "external_link"` | Controls which CTA experience is shown.                                                                  |
| `cta_action_text`           | `string`                    | Button label (e.g. `"Book a Demo"`, `"Get in Touch"`).                                                   |
| `cta_modal_title`           | `string \| null`            | Title displayed in the CTA modal.                                                                        |
| `cta_modal_description`     | `string \| null`            | Body text displayed in the CTA modal.                                                                    |
| `cta_modal_auto_open`       | `boolean`                   | When `true`, the CTA modal opens automatically when the video ends.                                      |
| `cta_use_organization_name` | `boolean`                   | When `true`, the CTA displays your organization name; when `false`, it uses the domain application name. |
| `cta_external_link`         | `string \| null`            | The URL to open when `cta_type` is `"external_link"` (e.g. a Calendly link).                             |
| `cta_fields`                | `CtaFieldConfig[]`          | Form fields to display when `cta_type` is `"form"`.                                                      |

### Form field configuration

Each entry in `cta_fields` follows the `CtaFieldConfig` shape:

| Field      | Type                                       | Description                                                   |
| ---------- | ------------------------------------------ | ------------------------------------------------------------- |
| `key`      | `string`                                   | Field identifier used as the key in the submitted data.       |
| `label`    | `string`                                   | Label shown to the viewer.                                    |
| `type`     | `"text" \| "email" \| "tel" \| "textarea"` | Input type.                                                   |
| `required` | `boolean`                                  | Whether the viewer must fill in this field before submitting. |

Fields are displayed in the order they appear in the array.

## Configure an external link CTA

To use an external link instead of a form:

```bash theme={null}
curl -X PUT https://api.demomatic.tech/domains/123 \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cta_type": "external_link",
    "cta_action_text": "Schedule a call",
    "cta_external_link": "https://calendly.com/your-link",
    "cta_modal_auto_open": true
  }'
```

<Warning>
  When `cta_type` is `"external_link"`, submitting a form via `POST /videos/:id/cta-submit` returns a `400` error. Use link-click tracking instead.
</Warning>

## Embedding CTA in your own player

If you embed videos using your own player rather than the Demomatic embed, you can integrate CTA behaviour manually.

### Handling form submission

When `cta_type === "form"`, render the fields from `cta_fields` and submit the data to:

```
POST /videos/:video_id/cta-submit
```

```javascript theme={null}
async function submitCtaForm(videoId, fields) {
  const res = await fetch(`https://api.demomatic.tech/videos/${videoId}/cta-submit`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fields }),
  });
  const { data } = await res.json();
  return data; // { ok: true }
}

// Example call
await submitCtaForm(456, {
  name: 'Alice Johnson',
  email: 'alice@example.com',
  company: 'Acme Corp',
});
```

No authentication is required for this endpoint.

### Tracking external link clicks

When `cta_type === "external_link"`, record a click before opening the external URL:

```javascript theme={null}
async function trackLinkClick(videoId) {
  await fetch(`https://api.demomatic.tech/videos/${videoId}/link-click`, {
    method: 'POST',
  });
}

async function handleCtaClick(videoId, externalLink) {
  await trackLinkClick(videoId);
  window.open(externalLink, '_blank');
}
```

Clicks are deduplicated per viewer — calling this endpoint multiple times for the same viewer is safe.

### Auto-opening the modal

When `cta_modal_auto_open` is `true`, open the CTA modal when the video's `ended` event fires:

```javascript theme={null}
videoElement.addEventListener('ended', () => {
  if (video.cta_modal_auto_open) {
    openCtaModal();
  }
});
```

### Choosing the display name

Use `cta_use_organization_name` to determine which name to show in the CTA:

```javascript theme={null}
const displayName = cta_use_organization_name
  ? organization_name
  : domain_application_name;
// e.g. "Contact Acme Corp" or "Contact MyApp"
```