curl --request POST \
--url https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "Acme Corp",
"icon": "briefcase",
"blocks": [
{
"kind": "fieldList",
"title": "Account",
"externalUrl": "https://crm.example.com/accounts/4821",
"rows": [
{
"label": "Plan",
"value": "Enterprise"
},
{
"label": "Renewal",
"value": "2026-12-01",
"tone": "warning"
},
{
"label": "Account owner",
"value": "Dana Kim"
}
]
},
{
"kind": "text",
"title": "Last note",
"text": "Asked for a quote for 20 more seats before the renewal."
},
{
"kind": "link",
"title": "Open deal",
"url": "https://crm.example.com/deals/9917",
"text": "Seat expansion, 20 seats"
}
]
}
'import requests
url = "https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards"
payload = {
"title": "Acme Corp",
"icon": "briefcase",
"blocks": [
{
"kind": "fieldList",
"title": "Account",
"externalUrl": "https://crm.example.com/accounts/4821",
"rows": [
{
"label": "Plan",
"value": "Enterprise"
},
{
"label": "Renewal",
"value": "2026-12-01",
"tone": "warning"
},
{
"label": "Account owner",
"value": "Dana Kim"
}
]
},
{
"kind": "text",
"title": "Last note",
"text": "Asked for a quote for 20 more seats before the renewal."
},
{
"kind": "link",
"title": "Open deal",
"url": "https://crm.example.com/deals/9917",
"text": "Seat expansion, 20 seats"
}
]
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: 'Acme Corp',
icon: 'briefcase',
blocks: [
{
kind: 'fieldList',
title: 'Account',
externalUrl: 'https://crm.example.com/accounts/4821',
rows: [
{label: 'Plan', value: 'Enterprise'},
{label: 'Renewal', value: '2026-12-01', tone: 'warning'},
{label: 'Account owner', value: 'Dana Kim'}
]
},
{
kind: 'text',
title: 'Last note',
text: 'Asked for a quote for 20 more seats before the renewal.'
},
{
kind: 'link',
title: 'Open deal',
url: 'https://crm.example.com/deals/9917',
text: 'Seat expansion, 20 seats'
}
]
})
};
fetch('https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Acme Corp',
'icon' => 'briefcase',
'blocks' => [
[
'kind' => 'fieldList',
'title' => 'Account',
'externalUrl' => 'https://crm.example.com/accounts/4821',
'rows' => [
[
'label' => 'Plan',
'value' => 'Enterprise'
],
[
'label' => 'Renewal',
'value' => '2026-12-01',
'tone' => 'warning'
],
[
'label' => 'Account owner',
'value' => 'Dana Kim'
]
]
],
[
'kind' => 'text',
'title' => 'Last note',
'text' => 'Asked for a quote for 20 more seats before the renewal.'
],
[
'kind' => 'link',
'title' => 'Open deal',
'url' => 'https://crm.example.com/deals/9917',
'text' => 'Seat expansion, 20 seats'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards"
payload := strings.NewReader("{\n \"title\": \"Acme Corp\",\n \"icon\": \"briefcase\",\n \"blocks\": [\n {\n \"kind\": \"fieldList\",\n \"title\": \"Account\",\n \"externalUrl\": \"https://crm.example.com/accounts/4821\",\n \"rows\": [\n {\n \"label\": \"Plan\",\n \"value\": \"Enterprise\"\n },\n {\n \"label\": \"Renewal\",\n \"value\": \"2026-12-01\",\n \"tone\": \"warning\"\n },\n {\n \"label\": \"Account owner\",\n \"value\": \"Dana Kim\"\n }\n ]\n },\n {\n \"kind\": \"text\",\n \"title\": \"Last note\",\n \"text\": \"Asked for a quote for 20 more seats before the renewal.\"\n },\n {\n \"kind\": \"link\",\n \"title\": \"Open deal\",\n \"url\": \"https://crm.example.com/deals/9917\",\n \"text\": \"Seat expansion, 20 seats\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"Acme Corp\",\n \"icon\": \"briefcase\",\n \"blocks\": [\n {\n \"kind\": \"fieldList\",\n \"title\": \"Account\",\n \"externalUrl\": \"https://crm.example.com/accounts/4821\",\n \"rows\": [\n {\n \"label\": \"Plan\",\n \"value\": \"Enterprise\"\n },\n {\n \"label\": \"Renewal\",\n \"value\": \"2026-12-01\",\n \"tone\": \"warning\"\n },\n {\n \"label\": \"Account owner\",\n \"value\": \"Dana Kim\"\n }\n ]\n },\n {\n \"kind\": \"text\",\n \"title\": \"Last note\",\n \"text\": \"Asked for a quote for 20 more seats before the renewal.\"\n },\n {\n \"kind\": \"link\",\n \"title\": \"Open deal\",\n \"url\": \"https://crm.example.com/deals/9917\",\n \"text\": \"Seat expansion, 20 seats\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"title\": \"Acme Corp\",\n \"icon\": \"briefcase\",\n \"blocks\": [\n {\n \"kind\": \"fieldList\",\n \"title\": \"Account\",\n \"externalUrl\": \"https://crm.example.com/accounts/4821\",\n \"rows\": [\n {\n \"label\": \"Plan\",\n \"value\": \"Enterprise\"\n },\n {\n \"label\": \"Renewal\",\n \"value\": \"2026-12-01\",\n \"tone\": \"warning\"\n },\n {\n \"label\": \"Account owner\",\n \"value\": \"Dana Kim\"\n }\n ]\n },\n {\n \"kind\": \"text\",\n \"title\": \"Last note\",\n \"text\": \"Asked for a quote for 20 more seats before the renewal.\"\n },\n {\n \"kind\": \"link\",\n \"title\": \"Open deal\",\n \"url\": \"https://crm.example.com/deals/9917\",\n \"text\": \"Seat expansion, 20 seats\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "7f1c2a9e-3b4d-4e5f-8a6b-9c0d1e2f3a4b",
"recipient": {
"type": "user",
"userId": "42"
},
"delivery": "delivered",
"createdAt": "2026-11-16T10:15:30.123Z"
},
"requestId": "c9856b94-db55-402b-a6ba-adb130351158"
}Send an insight card
Shows a card with your own context, such as a record from your CRM, to the agent on a call in progress. A card has a title, an optional icon and up to 20 blocks: field lists, text, links, chips, metrics and ticket references. The answer says who got the card and how, but holds none of its content.
Delivered or pending. When an agent has answered the call, the card is shown to that agent at once: delivery is delivered and recipient names the agent. When nobody has answered yet, the card is kept for 1 hour and shown to the agent who answers: delivery is pending and recipient is null. A pending card shows only on Phone versions that fetch cards when a call is answered; older Phone versions do not show it. A call uuid that matches no call, and a call of another company, get the same pending answer, so the answer never tells whether a call exists. A call that has ended returns 409 INSIGHT_CARDS.CALL_ENDED.
Which call. callUuid is the call uuid that call webhooks such as call.started carry as call_uuid, in any letter case. The numeric call id is not accepted here.
The body. The body is at most 32 KiB. The card’s title is at most 120 characters and every other text value at most 2,000, counted in Unicode code points. Every URL must be an absolute https: URL. Unknown fields are refused at every level. A wrong shape (not JSON, an unknown or missing field, a wrong type) is 400 VALIDATION.INVALID_BODY and a value out of range (too long, too many, not in its list, not https:) is 422 VALIDATION.INVALID_FIELD, both with the JSON path in target, for example blocks[1].url.
Retries. Send an Idempotency-Key to retry safely. A 201 is stored for 24 hours: the same key with the same call and the same body, byte for byte, returns it again with Idempotent-Replay: true and sends no second card. The same key with another body, or for another call, is 422 IDEMPOTENCY_KEY_REUSED. While the first request with a key is still running, a retry gets 409 INSIGHT_CARDS.IDEMPOTENCY_KEY_IN_USE: retry it shortly. The 422 and the 409 leave the key with the request that holds it. Any other refusal does not use up the key, so a retry with the same key runs again.
Limits. Your company can hold a limited number of pending cards at a time. Over that limit you get 429 INSIGHT_CARDS.PENDING_LIMIT_REACHED with Retry-After. Requests also count against the gateway’s per-company rate limit, one budget shared with the Call tags operations under /v1/calls/.
Authentication. Send your API credentials with the first request. The 401 comes from the gateway without a WWW-Authenticate challenge, so an HTTP client that waits for a challenge before it sends credentials never sends them.
Moving from the Cue Cards API? Migrate from Cue Cards maps every field.
curl --request POST \
--url https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "Acme Corp",
"icon": "briefcase",
"blocks": [
{
"kind": "fieldList",
"title": "Account",
"externalUrl": "https://crm.example.com/accounts/4821",
"rows": [
{
"label": "Plan",
"value": "Enterprise"
},
{
"label": "Renewal",
"value": "2026-12-01",
"tone": "warning"
},
{
"label": "Account owner",
"value": "Dana Kim"
}
]
},
{
"kind": "text",
"title": "Last note",
"text": "Asked for a quote for 20 more seats before the renewal."
},
{
"kind": "link",
"title": "Open deal",
"url": "https://crm.example.com/deals/9917",
"text": "Seat expansion, 20 seats"
}
]
}
'import requests
url = "https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards"
payload = {
"title": "Acme Corp",
"icon": "briefcase",
"blocks": [
{
"kind": "fieldList",
"title": "Account",
"externalUrl": "https://crm.example.com/accounts/4821",
"rows": [
{
"label": "Plan",
"value": "Enterprise"
},
{
"label": "Renewal",
"value": "2026-12-01",
"tone": "warning"
},
{
"label": "Account owner",
"value": "Dana Kim"
}
]
},
{
"kind": "text",
"title": "Last note",
"text": "Asked for a quote for 20 more seats before the renewal."
},
{
"kind": "link",
"title": "Open deal",
"url": "https://crm.example.com/deals/9917",
"text": "Seat expansion, 20 seats"
}
]
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: 'Acme Corp',
icon: 'briefcase',
blocks: [
{
kind: 'fieldList',
title: 'Account',
externalUrl: 'https://crm.example.com/accounts/4821',
rows: [
{label: 'Plan', value: 'Enterprise'},
{label: 'Renewal', value: '2026-12-01', tone: 'warning'},
{label: 'Account owner', value: 'Dana Kim'}
]
},
{
kind: 'text',
title: 'Last note',
text: 'Asked for a quote for 20 more seats before the renewal.'
},
{
kind: 'link',
title: 'Open deal',
url: 'https://crm.example.com/deals/9917',
text: 'Seat expansion, 20 seats'
}
]
})
};
fetch('https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Acme Corp',
'icon' => 'briefcase',
'blocks' => [
[
'kind' => 'fieldList',
'title' => 'Account',
'externalUrl' => 'https://crm.example.com/accounts/4821',
'rows' => [
[
'label' => 'Plan',
'value' => 'Enterprise'
],
[
'label' => 'Renewal',
'value' => '2026-12-01',
'tone' => 'warning'
],
[
'label' => 'Account owner',
'value' => 'Dana Kim'
]
]
],
[
'kind' => 'text',
'title' => 'Last note',
'text' => 'Asked for a quote for 20 more seats before the renewal.'
],
[
'kind' => 'link',
'title' => 'Open deal',
'url' => 'https://crm.example.com/deals/9917',
'text' => 'Seat expansion, 20 seats'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards"
payload := strings.NewReader("{\n \"title\": \"Acme Corp\",\n \"icon\": \"briefcase\",\n \"blocks\": [\n {\n \"kind\": \"fieldList\",\n \"title\": \"Account\",\n \"externalUrl\": \"https://crm.example.com/accounts/4821\",\n \"rows\": [\n {\n \"label\": \"Plan\",\n \"value\": \"Enterprise\"\n },\n {\n \"label\": \"Renewal\",\n \"value\": \"2026-12-01\",\n \"tone\": \"warning\"\n },\n {\n \"label\": \"Account owner\",\n \"value\": \"Dana Kim\"\n }\n ]\n },\n {\n \"kind\": \"text\",\n \"title\": \"Last note\",\n \"text\": \"Asked for a quote for 20 more seats before the renewal.\"\n },\n {\n \"kind\": \"link\",\n \"title\": \"Open deal\",\n \"url\": \"https://crm.example.com/deals/9917\",\n \"text\": \"Seat expansion, 20 seats\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"Acme Corp\",\n \"icon\": \"briefcase\",\n \"blocks\": [\n {\n \"kind\": \"fieldList\",\n \"title\": \"Account\",\n \"externalUrl\": \"https://crm.example.com/accounts/4821\",\n \"rows\": [\n {\n \"label\": \"Plan\",\n \"value\": \"Enterprise\"\n },\n {\n \"label\": \"Renewal\",\n \"value\": \"2026-12-01\",\n \"tone\": \"warning\"\n },\n {\n \"label\": \"Account owner\",\n \"value\": \"Dana Kim\"\n }\n ]\n },\n {\n \"kind\": \"text\",\n \"title\": \"Last note\",\n \"text\": \"Asked for a quote for 20 more seats before the renewal.\"\n },\n {\n \"kind\": \"link\",\n \"title\": \"Open deal\",\n \"url\": \"https://crm.example.com/deals/9917\",\n \"text\": \"Seat expansion, 20 seats\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudtalk.io/v1/calls/{callUuid}/insight-cards")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"title\": \"Acme Corp\",\n \"icon\": \"briefcase\",\n \"blocks\": [\n {\n \"kind\": \"fieldList\",\n \"title\": \"Account\",\n \"externalUrl\": \"https://crm.example.com/accounts/4821\",\n \"rows\": [\n {\n \"label\": \"Plan\",\n \"value\": \"Enterprise\"\n },\n {\n \"label\": \"Renewal\",\n \"value\": \"2026-12-01\",\n \"tone\": \"warning\"\n },\n {\n \"label\": \"Account owner\",\n \"value\": \"Dana Kim\"\n }\n ]\n },\n {\n \"kind\": \"text\",\n \"title\": \"Last note\",\n \"text\": \"Asked for a quote for 20 more seats before the renewal.\"\n },\n {\n \"kind\": \"link\",\n \"title\": \"Open deal\",\n \"url\": \"https://crm.example.com/deals/9917\",\n \"text\": \"Seat expansion, 20 seats\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "7f1c2a9e-3b4d-4e5f-8a6b-9c0d1e2f3a4b",
"recipient": {
"type": "user",
"userId": "42"
},
"delivery": "delivered",
"createdAt": "2026-11-16T10:15:30.123Z"
},
"requestId": "c9856b94-db55-402b-a6ba-adb130351158"
}Authorizations
HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).
Headers
1 to 255 visible ASCII characters (no spaces) naming this send, given once. A 201 is stored for 24 hours, and a replay returns it with Idempotent-Replay: true. The stored request covers the call and the body, so the same key for another call or with another body is 422 IDEMPOTENCY_KEY_REUSED. That 422, and a 409 INSIGHT_CARDS.IDEMPOTENCY_KEY_IN_USE while the first request is still running, leave the key with the request that holds it. Any other refusal leaves the key unused, so a retry with the same key runs again. Keys are per company. See Retries in the operation description.
1 - 255^[\x21-\x7E]{1,255}$"crm-sync-4821-7c1d"
Path Parameters
Body
An insight card. Unknown fields are refused here and in every block.
Up to 20 blocks. Left out or empty, the card shows its title alone. Every block has a kind, which sets its other fields, a required title, and optional externalUrl and empty.
20Label and value rows, such as the fields of a record.
- Field list
- Text
- Link
- Chip group
- Metric
- Ticket reference
Show child attributes
Show child attributes
{
"kind": "fieldList",
"title": "Account",
"rows": [{ "label": "Plan", "value": "Enterprise" }]
}
Response
The card was shown to the agent on the call (delivery: delivered) or kept for the agent who answers (delivery: pending). The answer holds none of the card's content.