Tarjetas de cliente
Una tarjeta de cliente muestra datos de tus propios sistemas junto a cada conversación de Support, como el plan, el uso o los pedidos de un cliente. Una tarjeta es un único endpoint HTTPS en tu servidor: Ferndesk lo llama con el cliente, tu endpoint responde con la tarjeta como JSON, y Ferndesk la muestra. Tú eliges qué muestra la tarjeta, y Ferndesk decide cómo se ve. Lo que ve tu equipo está en Trabajar en la bandeja de entrada.
Requiere Support. Los propietarios y administradores añaden tarjetas.
Añadir una tarjeta
Un propietario o administrador añade la tarjeta en Ferndesk con una clave, la URL de tu endpoint y un secreto que tú eliges. Un espacio de trabajo puede tener hasta 25 tarjetas.
La URL debe usar HTTPS y resolver a una dirección pública.
La clave puede tener hasta 64 letras, números,
-y_. Ferndesk la envía encardKeys, y tu respuesta la usa para indicar qué tarjeta es cuál.Antes de que Ferndesk guarde una tarjeta nueva, una URL nueva o un secreto nuevo, llama a tu endpoint una vez. Si esa llamada falla (sin respuesta, un secreto rechazado, una clave que falta o un cuerpo que Ferndesk no puede leer), la tarjeta no se guarda. Cuando no hay un cliente real sobre el que preguntar, la llamada usa un cliente de ejemplo (
[email protected], idc_example). Respóndela como cualquier otra solicitud, por ejemplo con"components": null.
Cuando Ferndesk llama a tu endpoint
Ferndesk llama a tu endpoint cada vez que necesita la tarjeta, y no guarda nada entre llamadas:
cuando un compañero abre una conversación y se carga su panel del cliente,
cuando un compañero abre una tarjeta o hace clic en Refresh,
cuando tu agente de IA lee al cliente mientras ayuda a tu equipo con un borrador o una nota.
Ferndesk no lo llama para un visitante que no proporcionó correo electrónico, ni para las conversaciones de ejemplo con las que empieza una bandeja de entrada nueva. Tu agente de IA solo pregunta por un cliente verificado. Las tarjetas que comparten endpoint y secreto llegan en una sola llamada. Las llamadas a distintos endpoints se ejecutan en paralelo.
La solicitud
Ferndesk envía un POST a la URL de la tarjeta con tres encabezados: Authorization: Bearer <your secret>, Content-Type: application/json y Accept: application/json. Ferndesk no sigue redirecciones, y tu secreto guardado solo se envía al host para el que lo guardaste. El cuerpo:
{
"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
}
}Campo | Qué es |
|---|---|
| Siempre |
| Las claves de las tarjetas que Ferndesk solicita en esta llamada. |
| El id de Ferndesk para el cliente. |
| La dirección de correo electrónico del cliente. |
| El id de tu propio inicio de sesión cuando el cliente inició sesión en tu centro de ayuda o widget, o |
| El id de Ferndesk para la conversación. |
| Siempre |
| Una copia de |
Ferndesk establece el cliente. Tu agente de IA nunca lo elige. Actúa solo sobre el cliente en customer, y no leas un cliente desde ningún otro campo.
Verificar el secreto
Compara el token Bearer con el secreto que le diste a Ferndesk, y rechaza la solicitud si no coincide.
// 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
}))
});
});La respuesta
Responde con estado 200 y un cuerpo JSON en menos de 15 segundos. Incluye una tarjeta por cada clave en 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" }
]
}]
}Campo | Qué hace |
|---|---|
| Opcional. |
| Obligatorio. Una lista de hasta 25 tarjetas. Se ignora una tarjeta cuya clave Ferndesk no pidió. |
| Obligatorio. Una de las claves de |
| Obligatorio. La tarjeta, de arriba abajo, hasta 30 componentes, contando secciones y los componentes dentro de ellas. Envía |
| Opcional. Una línea breve de resumen: |
| Opcional. Hasta 40 caracteres. Se muestra en lugar del nombre de la tarjeta para este cliente. |
| Opcional. Durante cuánto tiempo la tarjeta cuenta como actual, de 0 a 31,536,000 segundos. El valor predeterminado es 300 (5 minutos). |
| Opcional. Las acciones de la tarjeta. Ferndesk todavía no ejecuta acciones, así que el panel no las muestra. |
Los colores para texto, filas, filas de tabla, elementos de la línea de tiempo y status son NORMAL, MUTED, SUCCESS, WARNING y ERROR. Los colores de las insignias son GREY, GREEN, YELLOW, RED y BLUE.
Componentes
Cada componente es { "type": ..., ...fields }. Hay doce tipos, en el formato de las tarjetas de cliente de Plain. Los límites están en caracteres salvo que indiquen lo contrario.
Tipo | Obligatorio | Opcional |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Por elemento: |
|
| Por columna: |
|
| Por elemento: |
|
|
|
|
|
|
|
| Ninguno |
|
| Ninguno |
| Ninguno. Termina la sección anterior. | Ninguno |
Cada url empieza con https:// o http:// y tiene hasta 2,000 caracteres. Una tarjeta tiene hasta 6 botones. Cualquier componente puede llevar safeForCustomer, y Ferndesk lo ignora: las tarjetas son para tu equipo. Tu agente de IA las lee solo para ayudar a tu equipo con borradores y notas, nunca para decírselas al cliente.
Ferndesk establece el diseño. Dibuja una línea entre secciones. Dentro de cada sección muestra primero las cifras destacadas (dos o tres filas stat seguidas comparten una sola franja), luego las insignias en una sola línea, después el resto en tu orden, y los botones en una sola fila al final. La fila de botones de cada sección muestra hasta 3 botones y coloca el resto bajo More. Una lista, tabla o línea de tiempo sin encabezado obtiene su propia sección, y una sección larga se pliega.
Errores y límites
Un solo elemento defectuoso nunca hace fallar toda la tarjeta. Cuando una llamada falla, la tarjeta muestra el problema a tu equipo. Si una actualización falla, la tarjeta conserva lo que mostraba antes.
Qué sucede | Resultado |
|---|---|
Sin conexión, o la dirección no es pública | La tarjeta indica que Ferndesk no pudo conectarse. |
Sin respuesta en 15 segundos | La tarjeta indica que se agotó el tiempo de espera. |
401 o 403 | La tarjeta indica que tu endpoint rechazó la solicitud. Revisa el secreto. |
Cualquier otro estado distinto de 200, incluida una redirección | La tarjeta falla. Ferndesk no lee el cuerpo. |
Un cuerpo de más de 64 KB, o que no sea JSON | Todas las tarjetas de la llamada fallan. |
Sin lista | Todas las tarjetas de la llamada fallan. |
Falta una clave que Ferndesk pidió | Esa tarjeta falla. Las demás se muestran. |
Un texto que supera su límite | Se recorta y termina en "…". |
Demasiados elementos, filas, componentes o botones | Se muestran los primeros hasta el límite. |
Un campo que Ferndesk no conoce | Se ignora. |
Cualquier otro elemento defectuoso | Se descarta el elemento más pequeño que contiene el problema (un elemento, un campo o el componente). El resto de la tarjeta se muestra. |
La página de la tarjeta en Ferndesk muestra una vista previa de la respuesta de tu endpoint, con cada problema y su ruta JSON, como cards[0].components[3].text.
Tiempo y timeToLiveSeconds
Tu endpoint tiene 15 segundos para responder a cada llamada. Ferndesk vuelve a preguntar cada vez que necesita la tarjeta, así que timeToLiveSeconds no reduce la frecuencia con la que te llaman. Define cuánto tiempo una tarjeta cuenta como actual. Cuando un compañero tiene una tarjeta abierta más allá de ese tiempo, o después de una actualización fallida, la tarjeta muestra cuándo se actualizó por última vez y un enlace Refresh.
Endpoints escritos para Plain
Un endpoint escrito para las tarjetas de cliente de Plain funciona tal cual. La solicitud lleva thread junto a conversation, y Ferndesk interpreta las formas de componente de Plain como propias:
Componente de Plain | Se lee como |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Se ignora. Ferndesk establece el espaciado. |