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

# Migrate from Cue Cards to insight cards

> Move a Cue Cards API integration to Send an insight card: what changed on the old endpoint, how each cue card field maps to an insight card, and what the v1 endpoint does differently.

The Cue Cards API (`POST https://platform-api.cloudtalk.io/api/cuecards`) is legacy. To show data from your own systems to the agent on a call, send an insight card with [Send an insight card](https://help.cloudtalk.io/api-reference/insight-cards/send-an-insight-card.md) (`POST https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards`).

This guide explains what changed on the old endpoint, maps every cue card field to an insight card, and lists what the v1 endpoint does differently.

> [!NOTE]
>
> Both endpoints take the same API key with HTTP Basic: your API Access Key ID as the username and your API Access Key Secret as the password, as on the rest of the [CloudTalk API](https://help.cloudtalk.io/guides/authentication.md).

## Why move

With [Send an insight card](https://help.cloudtalk.io/api-reference/insight-cards/send-an-insight-card.md):

* Your card shows in the agent's insight cards panel, where agents also see the [call insight cards](https://help.cloudtalk.io/en/articles/call-insight-cards.md) you build in the Dashboard.
* A delivered card is kept for 1 hour, so the agent's Phone shows it again after it reconnects.
* You can send a card before anyone answers the call. It waits up to 1 hour and shows to the agent who answers.
* The answer gives you the card's `id`, the agent it went to (`recipient`) and whether it was delivered or is waiting for an answer (`delivery`).
* An `Idempotency-Key` header makes retries safe: a request you send again does not show the card twice.

The old endpoint also shows each cue card in the insight cards panel now, and keeps a card for a call nobody has answered yet. It does not tell you which agent got the card or whether it is still waiting, and it takes no `Idempotency-Key`.

## What stays the same

* The old URL, your API key, the request body and the answers (`{ "success": true }`, or `{ "success": false, "errors": [...] }`) keep working for at least 365 days from the deprecation date, 2026-11-12.

* Every cue card now shows as an insight card in the insight cards panel.

* Every answer of the old endpoint, except a `401` for wrong API credentials and a `429` from the gateway's rate limit, carries a `Deprecation` header, a date in the RFC 9745 form such as `@1794441600`, and a `Link` header that points to this guide:

  ```http theme={"system"}
  Deprecation: @1794441600
  Link: <https://help.cloudtalk.io/guides/insight-cards/migrate-from-cue-cards>; rel="deprecation"; type="text/html"
  ```

* The answers carry no `Sunset` header.

## What changes on the old endpoint

The old endpoint now turns each cue card into an insight card. Some answers change:

* **A call nobody has answered yet** answers `200`, where it answered `424`. The card shows when the agent answers.
* **A well-formed `call_uuid` that matches no call of yours**, such as a typo, also answers `200`, where it answered `424`. The card is never shown.
* **`424 no such active call - call_uuid: ...`** now means only that the call has ended, or that `call_uuid` is not a call uuid.
* **A live call with no agent** no longer answers `400`.
* **A body over 32 KiB** answers `400` with the error `request body must be at most 32768 bytes`.
* **Too many cards waiting for an agent to answer:** `429` with the error `too many pending cue cards for this company` and a `Retry-After` header. Retry after that many seconds.
* **The rate limit:** the gateway in front of the endpoint can answer `429` with no body and the `X-CloudTalkAPI-Limit`, `X-CloudTalkAPI-Remaining` and `X-CloudTalkAPI-ResetTime` headers. See [Rate limiting](https://help.cloudtalk.io/guides/rate-limiting.md).
* **`401`** keeps its `WWW-Authenticate: Basic` challenge.
* **HTTP Basic only.** Send your API key with HTTP Basic. A `Bearer` token never worked on this endpoint.

And the card can look different:

* **A `link` block now shows** if its `url` is an `https` URL. Before, the Phone did not show it. A `link` or `file` block whose URL is not `https` is dropped.
* **Images and `icon_url` are dropped.** The card shows the default icon.
* **Formatting is dropped.** Text shows without bold, italics or other styles. A link in rich text whose URL is not an `https` URL keeps only its text, not the URL.
* **Long content is trimmed.** Within the 32 KiB body limit, the title is cut to 120 characters, long text is split, and a card keeps at most 20 blocks.

## Field mapping

Use this table to build the v1 request from the cue card you send today. The last column shows what the old endpoint now does with each field.

| Cue card | Insight card (v1) | What the old endpoint does with it |
| - | - | - |
| `call_uuid` | `{callUuid}` in the path | Names the call. |
| `type` (`html` or `blocks`) | Not sent: a v1 card is always blocks. | Reads `content` as HTML or as blocks. |
| `title` | `title`, up to 120 characters. | Cuts it to 120 characters. |
| `subtitle` | A first `text` block. | Shows it as a first text block. |
| `icon_url` | `icon`, one of CloudTalk's icons: `user`, `briefcase`, `file-text`, `tag` or `zap`. Leave it out for the default icon. | Drops it and shows the default icon. |
| `textfield` block (`name`, `value`) | A row of a `fieldList` block: `name` to `label`, `value` to `value`. | Shows it as a field list row. Consecutive textfields become one field list. |
| `richtext` block (`name`, `value`) | A `text` block: `name` to `title`, `value` to `text`. | Shows it as text. Markdown markers are dropped, `https` links become link blocks, and any other link keeps only its text. |
| `file` block (`name`, `file_url`) | A `link` block: `name` to `title`, `file_url` to `url`. | Shows it as a link block if `file_url` is an `https` URL; drops it otherwise. |
| `link` block (`name`, `url`) | A `link` block: `name` to `title`, `url` to `url`. | Shows it as a link block if `url` is an `https` URL; drops it otherwise. Before, the Phone did not show it. |
| `image` block | Not available: v1 has no image block. | Drops it. |
| HTML `content` | Blocks you build from it. | Paragraphs and line breaks become text, https links become link blocks, two-column tables become field lists, lists become lines of text, and headings become block titles. Scripts, images and formatting are dropped. |

Every v1 block needs a `title`. v1 also has block kinds that cue cards do not: `chipGroup` (status chips), `metric` (a value with a unit) and `ticketRef` (a ticket in your helpdesk). The [reference](https://help.cloudtalk.io/api-reference/insight-cards/send-an-insight-card.md) describes each kind.

## Before and after

A cue card with two textfields and a rich text block, sent to the old endpoint:

```bash Before: Cue Cards API theme={"system"}
curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET \
  -X POST https://platform-api.cloudtalk.io/api/cuecards \
  -H "Content-Type: application/json" \
  -d '{
    "call_uuid": "9f1c2e7a-4b3d-4c8e-a1f0-2d6b8e5c7a90",
    "type": "blocks",
    "title": "Jane Smith",
    "subtitle": "Customer since 2021",
    "content": [
      {"type": "textfield", "name": "Plan", "value": "Premium"},
      {"type": "textfield", "name": "Open tickets", "value": "2"},
      {"type": "richtext", "name": "Script", "value": "Thank Jane for **calling** and ask about her [last order](https://shop.example.com/orders/123)."}
    ]
  }'
```

The same card, sent to the v1 endpoint:

```bash After: Send an insight card theme={"system"}
curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET \
  -X POST https://api.cloudtalk.io/v1/calls/9f1c2e7a-4b3d-4c8e-a1f0-2d6b8e5c7a90/insight-cards \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-9f1c2e7a-profile" \
  -d '{
    "title": "Jane Smith",
    "icon": "user",
    "blocks": [
      {"kind": "text", "title": "About", "text": "Customer since 2021"},
      {"kind": "fieldList", "title": "Account", "rows": [
        {"label": "Plan", "value": "Premium"},
        {"label": "Open tickets", "value": "2"}
      ]},
      {"kind": "text", "title": "Script", "text": "Thank Jane for calling and ask about her last order."},
      {"kind": "link", "title": "Last order", "url": "https://shop.example.com/orders/123", "text": "Open the order"}
    ]
  }'
```

The answer is `201`:

```json 201: delivered theme={"system"}
{
  "data": {
    "id": "0b6f1e9c-3a2d-4f5e-9c8b-7a6d5e4f3c2b",
    "recipient": { "type": "user", "userId": "42" },
    "delivery": "delivered",
    "createdAt": "2026-11-16T09:30:12.345Z"
  },
  "requestId": "c9856b94-db55-402b-a6ba-adb130351158"
}
```

## Differences on v1

### The answer

A `201` answer holds none of the card's content. It gives you:

* `data.id`: the card's id.
* `data.recipient`: `{ "type": "user", "userId": "42" }`, the agent the card went to, or `null` while the card waits for an answer.
* `data.delivery`: `delivered`, or `pending` while the card waits for an answer.
* `data.createdAt`: when the card was made.
* `requestId`: quote it when you contact support.

### Cards that wait for an answer

* The answer is `201` with `"delivery": "pending"` for a call nobody has answered yet. A call uuid CloudTalk does not know, and another company's call, answer the same way: `pending` does not prove that the call exists.
* A pending card is kept for 1 hour and shows to the agent who answers. Older Phone versions do not show it.
* When too many of your company's cards wait for an answer, the endpoint answers `429 INSIGHT_CARDS.PENDING_LIMIT_REACHED` and stores nothing. Retry after the seconds in `Retry-After`, when your oldest waiting card expires.
* A call that has ended answers `409 INSIGHT_CARDS.CALL_ENDED`. Do not retry it.

### Safe retries

Send an `Idempotency-Key` header, 1 to 255 visible ASCII characters with no spaces, and retry with the same key, the same call and the same body, byte for byte:

* A `201` is kept for 24 hours. A retry gets that answer again with the header `Idempotent-Replay: true`, and the card is not sent again.
* The first request is still running: `409 INSIGHT_CARDS.IDEMPOTENCY_KEY_IN_USE`. Retry it shortly.
* The same key with another body or another call: `422 IDEMPOTENCY_KEY_REUSED`. A key names one card.
* The `409` and the `422` leave the key with the request that holds it. Any other refusal leaves the key unused, so a retry with the same key runs the request again.

### Limits

v1 refuses what the old endpoint trims:

| Limit | Value |
| - | - |
| `title` | 1 to 120 characters, not blank |
| Blocks per card | At most 20 |
| Rows of a `fieldList`, chips of a `chipGroup` | 1 to 50 |
| Each text value | At most 2,000 characters |
| URLs | Absolute, `https` only |
| Fields | Unknown fields are refused, at every level |
| Body | At most 32 KiB, `Content-Type: application/json` |

Characters are counted as Unicode code points. A body of the wrong shape (not JSON, a missing or unknown field, a wrong type, over 32 KiB) answers `400 VALIDATION.INVALID_BODY`. A value out of range answers `422 VALIDATION.INVALID_FIELD`. Both name the JSON path at fault in `target`, such as `blocks[1].url`. A `callUuid` that is not a uuid answers `400 VALIDATION.INVALID_PARAMETER`, where the old endpoint answered `424`.

### Errors

Errors come as `{ "error": { "code", "message", "target" }, "requestId" }`. Branch on `error.code`:

| Status | Code | What to do |
| - | - | - |
| `409` | `INSIGHT_CARDS.CALL_ENDED` | The call has ended. Do not retry. |
| `409` | `INSIGHT_CARDS.IDEMPOTENCY_KEY_IN_USE` | The first request with this key is still running. Retry shortly. |
| `422` | `VALIDATION.INVALID_FIELD` | Fix the value `target` names. |
| `422` | `IDEMPOTENCY_KEY_REUSED` | Use a new key for a different card or call. |
| `429` | `INSIGHT_CARDS.PENDING_LIMIT_REACHED` | Retry after the seconds in `Retry-After`. |
| `503` | `INSIGHT_CARDS.DELIVERY_UNAVAILABLE` | The card could not be delivered right now. Retry the request. |

The reference page lists every status and code. [Error codes](https://help.cloudtalk.io/guides/error-codes.md) covers the shape.

### Authentication and rate limit

* **Send credentials with the first request.** The gateway's `401` carries no `WWW-Authenticate` challenge, unlike the old endpoint's. `curl -u` sends them up front. A client that waits for a challenge before it sends credentials never authenticates.
* **The rate limit is shared with Call tags.** The gateway limits requests per company, and this endpoint counts against the same limit as [List a call's tags](https://help.cloudtalk.io/api-reference/call-tags/list-a-calls-tags.md), [Add tags to a call](https://help.cloudtalk.io/api-reference/call-tags/add-tags-to-a-call.md) and [Remove tags from a call](https://help.cloudtalk.io/api-reference/call-tags/remove-tags-from-a-call.md). Over it, the gateway answers `429` with no body and the `X-CloudTalkAPI-*` headers, before your request reaches the endpoint. Tell it apart from `429 INSIGHT_CARDS.PENDING_LIMIT_REACHED`, which has an error body. See [Rate limiting](https://help.cloudtalk.io/guides/rate-limiting.md).


## Related topics

- [Cue Cards](https://help.cloudtalk.io/en/articles/11154936-cue-cards.md)
- [Create CueCard](https://help.cloudtalk.io/api-reference/cuecard/create-cuecard.md)
- [Call insight cards](https://help.cloudtalk.io/en/articles/call-insight-cards.md)


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