Skip to main content
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 (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.
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.

Why move

With Send an insight card:
  • Your card shows in the agent’s insight cards panel, where agents also see the call insight cards 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:
  • 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.
  • 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. 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 describes each kind.

Before and after

A cue card with two textfields and a rich text block, sent to the old endpoint:
Before: Cue Cards API
The same card, sent to the v1 endpoint:
After: Send an insight card
The answer is 201:
201: delivered

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: 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: The reference page lists every status and code. Error codes 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, Add tags to a call and Remove tags from a call. 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.