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-Keyheader makes retries safe: a request you send again does not show the card twice.
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
401for wrong API credentials and a429from the gateway’s rate limit, carries aDeprecationheader, a date in the RFC 9745 form such as@1794441600, and aLinkheader that points to this guide: -
The answers carry no
Sunsetheader.
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 answered424. The card shows when the agent answers. - A well-formed
call_uuidthat matches no call of yours, such as a typo, also answers200, where it answered424. The card is never shown. 424 no such active call - call_uuid: ...now means only that the call has ended, or thatcall_uuidis not a call uuid.- A live call with no agent no longer answers
400. - A body over 32 KiB answers
400with the errorrequest body must be at most 32768 bytes. - Too many cards waiting for an agent to answer:
429with the errortoo many pending cue cards for this companyand aRetry-Afterheader. Retry after that many seconds. - The rate limit: the gateway in front of the endpoint can answer
429with no body and theX-CloudTalkAPI-Limit,X-CloudTalkAPI-RemainingandX-CloudTalkAPI-ResetTimeheaders. See Rate limiting. 401keeps itsWWW-Authenticate: Basicchallenge.- HTTP Basic only. Send your API key with HTTP Basic. A
Bearertoken never worked on this endpoint.
- A
linkblock now shows if itsurlis anhttpsURL. Before, the Phone did not show it. Alinkorfileblock whose URL is nothttpsis dropped. - Images and
icon_urlare 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
httpsURL 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
After: Send an insight card
201:
201: delivered
Differences on v1
The answer
A201 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, ornullwhile the card waits for an answer.data.delivery:delivered, orpendingwhile 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
201with"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:pendingdoes 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_REACHEDand stores nothing. Retry after the seconds inRetry-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 anIdempotency-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
201is kept for 24 hours. A retry gets that answer again with the headerIdempotent-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
409and the422leave 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
401carries noWWW-Authenticatechallenge, unlike the old endpoint’s.curl -usends 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
429with no body and theX-CloudTalkAPI-*headers, before your request reaches the endpoint. Tell it apart from429 INSIGHT_CARDS.PENDING_LIMIT_REACHED, which has an error body. See Rate limiting.