Customer cards
A customer card shows data from your own systems beside each Support conversation, such as a customer's plan, usage or orders. A card is one HTTPS endpoint on your server: Ferndesk calls it with the customer, your endpoint answers with the card as JSON, and Ferndesk draws it. You choose what the card shows, and Ferndesk decides how it looks. What your team sees is in Work in the inbox.
Needs Support. Owners and admins add cards.
Add a card
An owner or admin adds the card in Ferndesk with a key, your endpoint's URL and a secret you choose. A workspace can have up to 25 cards.
The URL must use HTTPS and resolve to a public address.
The key is up to 64 letters, numbers,
-and_. Ferndesk sends it incardKeys, and your response uses it to say which card is which.Before Ferndesk saves a new card, a new URL or a new secret, it calls your endpoint once. If that call fails (no answer, a refused secret, a missing key or a body Ferndesk can't read), the card is not saved. When there is no real customer to ask about, the call uses an example customer (
[email protected], idc_example). Answer it like any other request, for example with"components": null.
When Ferndesk calls your endpoint
Ferndesk calls your endpoint each time it needs the card, and keeps nothing between calls:
when a teammate opens a conversation and its customer panel loads,
when a teammate opens a card or clicks Refresh,
when your AI agent reads the customer while it helps your team with a draft or a note.
Ferndesk doesn't call it for a visitor who gave no email, or for the sample conversations a new inbox starts with. Your AI agent only asks about a verified customer. Cards that share an endpoint and a secret come in one call. Calls to different endpoints run side by side.
The request
Ferndesk sends a POST to the card's URL with three headers: Authorization: Bearer <your secret>, Content-Type: application/json and Accept: application/json. Ferndesk doesn't follow redirects, and your saved secret only goes to the host you saved it for. The body:
{
"version": 1,
"cardKeys": ["plan"],
"customer": {
"id": "cust_01J9ZK4M2Q8T",
"email": "[email protected]",
"externalId": "usr_8842"
},
"conversation": {
"id": "conv_01J9ZK7R5W",
"externalId": null
},
"thread": {
"id": "conv_01J9ZK7R5W",
"externalId": null
}
}Field | What it is |
|---|---|
| Always |
| The keys of the cards Ferndesk asks for in this call. |
| Ferndesk's id for the customer. |
| The customer's email address. |
| The id from your own sign-in when the customer signed in to your help center or widget, otherwise |
| Ferndesk's id for the conversation. |
| Always |
| A copy of |
Ferndesk sets the customer. Your AI agent never chooses it. Act only on the customer in customer, and don't read a customer from any other field.
Verify the secret
Compare the Bearer token with the secret you gave Ferndesk, and refuse the request if it doesn't match.
// Express
app.post('/ferndesk/cards', express.json(), async (req, res) => {
const token = (req.get('authorization') || '').replace(/^Bearer /, '');
if (token !== process.env.FERNDESK_CARD_SECRET) {
return res.status(401).end();
}
const { cardKeys, customer } = req.body;
// findAccount is your own lookup, by your id or by email.
const account = await findAccount(customer.externalId ?? customer.email);
res.json({
version: 1,
cards: cardKeys.map((key) => ({
key,
components: account
? [{ type: 'row', label: 'Plan', value: account.plan }]
: null
}))
});
});The response
Answer with status 200 and a JSON body within 15 seconds. Include one card for each key in cardKeys.
{
"version": 1,
"cards": [{
"key": "plan",
"status": { "text": "Pro, renews 3 Dec", "color": "SUCCESS" },
"timeToLiveSeconds": 600,
"components": [
{ "type": "row", "label": "Plan", "value": "Pro" },
{ "type": "progress", "label": "Seats", "value": 12, "max": 15 },
{ "type": "linkButton", "label": "Open in admin", "url": "https://admin.example.com/u/usr_8842" }
]
}]
}Field | What it does |
|---|---|
| Optional. |
| Required. A list of up to 25 cards. A card whose key Ferndesk didn't ask for is ignored. |
| Required. One of the keys in |
| Required. The card, top to bottom, up to 30 components, counting sections and the components inside them. Send |
| Optional. A short summary line: |
| Optional. Up to 40 characters. Shown instead of the card's name for this customer. |
| Optional. How long the card counts as current, from 0 to 31,536,000 seconds. The default is 300 (5 minutes). |
| Optional. The card's actions. Ferndesk doesn't run actions yet, so the panel doesn't show them. |
Colors for text, rows, table rows, timeline items and status are NORMAL, MUTED, SUCCESS, WARNING and ERROR. Badge colors are GREY, GREEN, YELLOW, RED and BLUE.
Components
Each component is { "type": ..., ...fields }. There are twelve types, in the format of Plain's customer cards. Limits are in characters unless they say otherwise.
Type | Required | Optional |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Per item: |
|
| Per column: |
|
| Per item: |
|
|
|
|
|
|
|
| None |
|
| None |
| None. It ends the section above it. | None |
Every url starts with https:// or http:// and is up to 2,000 characters. A card has up to 6 buttons. Any component may carry safeForCustomer, and Ferndesk ignores it: cards are for your team. Your AI agent reads them only to help your team with drafts and notes, never to tell the customer.
Ferndesk sets the layout. It draws a line between sections. Inside each section it shows headline figures first (two or three stat rows in a row share one strip), then badges on one line, then the rest in your order, and buttons in one row at the end. Each section's button row shows up to 3 buttons and puts the rest under More. A list, table or timeline without a heading gets a section of its own, and a long section folds.
Errors and limits
One bad part never fails the whole card. When a call fails, the card shows the problem to your team. If a refresh fails, the card keeps what it showed before.
What happens | Result |
|---|---|
No connection, or the address isn't public | The card says Ferndesk couldn't connect. |
No answer in 15 seconds | The card says it timed out. |
401 or 403 | The card says your endpoint refused the request. Check the secret. |
Any other status than 200, including a redirect | The card fails. Ferndesk doesn't read the body. |
A body over 64 KB, or not JSON | Every card in the call fails. |
No | Every card in the call fails. |
A key Ferndesk asked for is missing | That card fails. The others show. |
A text over its limit | It's cut, ending in "…". |
Too many items, rows, components or buttons | The first ones up to the limit show. |
A field Ferndesk doesn't know | It's ignored. |
Any other broken part | The smallest part that holds the problem is dropped (an item, a field, or the component). The rest of the card shows. |
The card's page in Ferndesk shows a preview of your endpoint's answer, with each problem and its JSON path, such as cards[0].components[3].text.
Timing and timeToLiveSeconds
Your endpoint has 15 seconds to answer every call. Ferndesk asks again each time it needs the card, so timeToLiveSeconds doesn't reduce how often you're called. It sets how long a card counts as current. When a teammate has a card open past that time, or after a refresh that failed, the card shows when it was last updated and a Refresh link.
Endpoints written for Plain
An endpoint written for Plain's customer cards works as it is. The request carries thread next to conversation, and Ferndesk reads Plain's component shapes as its own:
Plain component | Read as |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Ignored. Ferndesk sets the spacing. |