feishu-card (schema 2.0)
Reglas Clave
- Todas las tarjetas usan schema 2.0, los elementos se colocan en
body.elements[], no en el nivel superiorelements[] - Para enviar tarjetas, debes usar
--as bot,--msg-type interactive, y pasar una cadena JSON en--content - Para mencionar a alguien dentro de una tarjeta, usa
<at id="ou_xxx">Nombre</at>(no<at user_id>) - JSON 2.0: los botones ya no tienen un contenedor
action, los botones se colocan directamente enbody.elements, la interacción usa el arraybehaviors - Primero envía una tarjeta "pensando..." para obtener el
message_id, después de que Claude responda, actualízala en el mismo lugar con PATCH para evitar inundar la pantalla - La etiqueta
noteya no es compatible en schema 2.0 (error 200861), para notas usadiv + lark_md(<font color=grey>texto de nota</font>) - Para construir el JSON de la tarjeta, debes usar un heredoc de Python o escribir un archivo, está prohibido usar
$(python3 -c "...")—bash reportará errores de sintaxis cuando el contenido contenga acentos graves o caracteres especiales
Estructura de nivel superior con campos completos
{
"schema": "2.0",
"config": {
"streaming_mode": false,
"enable_forward": true,
"update_multi": true,
"width_mode": "default"
},
"card_link": {
"url": "https://...",
"pc_url": "https://...",
"ios_url": "https://...",
"android_url": "https://..."
},
"header": { "...": "..." },
"body": {
"direction": "vertical",
"padding": "0px",
"elements": []
}
}
Campos de config
| Campo | Tipo | Predeterminado | Descripción |
|---|---|---|---|
streaming_mode | bool | false | Estado de actualización en streaming (para marcador de posición "pensando") |
enable_forward | bool | true | Permitir reenviar la tarjeta |
update_multi | bool | false | Modo de tarjeta compartida JSON 2.0 (establecer en true para actualización sincronizada multiusuario) |
width_mode | string | default (600px) | compact (400px) / fill (ancho completo responsivo) / default |
Campos del Header
{
"header": {
"title": {"tag": "plain_text", "content": "Título"},
"subtitle": {"tag": "plain_text", "content": "Subtítulo (opcional)"},
"template": "blue",
"icon": {
"tag": "standard_icon",
"token": "robot-outlined",
"color": "blue"
},
"text_tag_list": [
{"tag": "text_tag", "text": {"tag": "plain_text", "content": "Nuevo"}, "color": "blue"}
]
}
}
Colores de template: blue / wathet / turquoise / green / yellow / orange / red / carmine / violet / purple / indigo / grey
Referencia rápida de colores de Feishu
Todos los campos que admiten una enumeración de colores (background_color, text_color, color de icono, etc.) usan el siguiente formato. No se puede usar solo el nombre del color base (por ejemplo, usar "blue" solo en algunos componentes causará errores), se debe agregar el sufijo de nivel:
| Tono | Claro (recomendado para fondos) | Medio | Oscuro (recomendado para texto) |
|---|---|---|---|
| Azul blue | blue-50 blue-100 blue-200 | blue-300~blue-500 | blue-600~blue-900 |
| Azul agua wathet | wathet-50 wathet-100 wathet-200 | wathet-300~wathet-500 | wathet-600~wathet-900 |
| Verde azulado turquoise | turquoise-50 turquoise-100 | turquoise-300~turquoise-500 | turquoise-600~turquoise-900 |
| Verde green | green-50 green-100 green-200 | green-300~green-500 | green-600~green-900 |
| Verde lima lime | lime-50 lime-100 | lime-300~lime-500 | lime-600~lime-900 |
| Amarillo yellow | yellow-50 yellow-100 | yellow-300~yellow-500 | yellow-600~yellow-900 |
| Naranja orange | orange-50 orange-100 | orange-300~orange-500 | orange-600~orange-900 |
| Rojo red | red-50 red-100 | red-300~red-500 | red-600~red-900 |
| Rosa carmine | carmine-50 carmine-100 | carmine-300~carmine-500 | carmine-600~carmine-900 |
| Púrpura purple | purple-50 purple-100 | purple-300~purple-500 | purple-600~purple-900 |
| Azul violeta violet | violet-50 violet-100 | violet-300~violet-500 | violet-600~violet-900 |
| Añil indigo | indigo-50 indigo-100 | indigo-300~indigo-500 | indigo-600~indigo-900 |
| Gris grey | grey-00 grey-50 grey-100 | grey-300~grey-500 | grey-600~grey-1000 |
| Blanco | white bg-white | — | — |
Fondos claros comunes recomendados (para collapsible_panel, fondo de column, etc.):
blue-100 wathet-100 green-100 yellow-100
orange-100 red-100 purple-100 carmine-100
turquoise-100 violet-100 indigo-100 lime-100
Tabla de referencia rápida de componentes
| tag | Tipo | Descripción |
|---|---|---|
div | Contenido | Bloque de texto (plain_text / lark_md), admite icono de prefijo |
markdown | Contenido | Texto Markdown puro (no admite @, para @ usa div+lark_md) |
img | Contenido | Imagen |
table | Contenido | Tabla de datos (máximo 5 por tarjeta, no anidables) |
hr | Diseño | Línea divisoria |
note | Diseño | ❌ Obsoleto en schema 2.0, usa div + lark_md + <font color=grey> |
column_set | Contenedor | Diseño multicolumna |
collapsible_panel | Contenedor | Panel plegable |
button | Interacción | Botón (JSON 2.0 se coloca directamente en elements, sin contenedor action) |
input | Interacción | Cuadro de entrada de texto (debe usarse dentro de un form) |
select_static | Interacción | Selector desplegable estático |
div (Bloque de texto)
{
"tag": "div",
"text": {
"tag": "lark_md",
"content": "**Negrita** _Cursiva_ `Código`",
"text_size": "normal",
"text_color": "default",
"text_align": "left",
"lines": 3
},
"icon": {"tag": "standard_icon", "token": "robot-outlined", "color": "blue"}
}
text.tag: plain_text (texto plano) o lark_md (Markdown + @)
text_size: heading-0 / heading / normal (predeterminado) / notation / x-small
text_align: left / center / right
img (Imagen)
{
"tag": "img",
"img_key": "img_xxx",
"alt": {"tag": "plain_text", "content": "Descripción al pasar el ratón"},
"title": {"tag": "plain_text", "content": "Título de la imagen"},
"scale_type": "crop_center",
"size": "medium",
"corner_radius": "4px",
"preview": true
}
scale_type: crop_center / crop_top / fit_horizontal
size: stretch (ancho completo) / large / medium / small / tiny / "300px 200px" (personalizado)
JSON 2.0 no admite
stretch_without_padding, para efecto de ancho completo usa margen negativo
column_set (Diseño multicolumna)
{
"tag": "column_set",
"flex_mode": "bisect",
"horizontal_spacing": "medium",
"background_style": "default",
"columns": [
{
"tag": "column",
"width": "weighted",
"weight": 1,
"vertical_align": "top",
"elements": [{"tag": "div", "text": {"tag": "plain_text", "content": "Columna izquierda"}}]
},
{
"tag": "column",
"width": "weighted",
"weight": 1,
"elements": [{"tag": "div", "text": {"tag": "plain_text", "content": "Columna derecha"}}]
}
]
}
flex_mode: none (comprimir proporcionalmente) / stretch (apilar verticalmente en pantallas estrechas) / flow (ajuste automático) / bisect (dos columnas de igual ancho) / trisect (tres columnas de igual ancho)
horizontal_spacing: small(4px) / medium(8px) / large(12px) / extra_large(16px)
column.width: auto / weighted (con weight 1-5) / "200px"
Máximo 5 niveles de anidamiento, no se pueden colocar contenedores de formulario ni tablas dentro de las columnas
collapsible_panel (Panel plegable)
{
"tag": "collapsible_panel",
"expanded": false,
"background_color": "default",
"header": {
"title": {"tag": "plain_text", "content": "Haz clic para expandir"},
"background_color": "grey",
"icon": {"tag": "standard_icon", "token": "arrow-down-outlined"},
"icon_expanded_angle": -180
},
"elements": [
{"tag": "div", "text": {"tag": "plain_text", "content": "Contenido plegable"}}
]
}
table (Tabla de datos)
{
"tag": "table",
"page_size": 5,
"row_height": "low",
"freeze_first_column": false,
"header_style": {
"text_align": "left",
"text_size": "normal",
"background_style": "grey",
"bold": true
},
"columns": [
{"name": "name", "display_name": "Nombre", "data_type": "text", "width": "auto"},
{"name": "status", "display_name": "Estado", "data_type": "options", "width": "120px"},
{"name": "count", "display_name": "Cantidad", "data_type": "number",
"format": {"precision": 0, "separator": true}},
{"name": "ts", "display_name": "Hora", "data_type": "date",
"format": "YYYY/MM/DD HH:mm"}
],
"rows": [
{"name": "Zhang San", "status": [{"name": "En progreso", "color": "blue"}], "count": 42, "ts": 1700000000000}
]
}
data_type: text / lark_md / markdown / options / number / persons / date
row_height: low / middle / high / auto / "48px" (32-124px)
Máximo 5 tablas por tarjeta, no anidables
button (JSON 2.0)
{
"tag": "button",
"text": {"tag": "plain_text", "content": "Confirmar"},
"type": "primary",
"size": "medium",
"width": "default",
"disabled": false,
"behaviors": [
{
"type": "callback",
"value": {"action": "confirm", "data": "payload"}
}
],
"confirm": {
"title": {"tag": "plain_text", "content": "Confirmación secundaria"},
"text": {"tag": "plain_text", "content": "¿Confirmas realizar esta operación?"}
}
}
type: default (gris) / primary (azul) / danger (rojo) / text / primary_text / danger_text / primary_filled / danger_filled / laser
size: tiny / small / medium / large
behaviors[].type: callback (disparar evento) / open_url (enlace de salto)
Cambio en JSON 2.0: Ya no hay contenedor
action, el botón se coloca directamente enbody.elementsocolumn.elements; la interacción usabehaviorsen lugar del antiguovalue
input (Entrada de texto)
{
"tag": "input",
"name": "field_name",
"placeholder": {"tag": "plain_text", "content": "Por favor, introduce..."},
"default_value": "",
"input_type": "text",
"max_length": 200,
"required": false,
"disabled": false,
"label": {"tag": "plain_text", "content": "Etiqueta"},
"label_position": "top",
"width": "fill"
}
input_type: text / multiline_text / password
El envío del usuario dispara el evento card.action.trigger, el evento contiene input_value
Sintaxis de @Menciones
| Tipo de mensaje | Sintaxis para @persona | @todos |
|---|---|---|
Tarjeta interactive lark_md | <at id="ou_xxx">Nombre</at> | <at id="all">Todos</at> |
Texto text / post | <at user_id="ou_xxx">Nombre</at> | <at user_id="all"></at> |
Estructura de elemento verificada para @mention dentro de tarjetas (div + lark_md, no uses la etiqueta markdown desnuda):
{
"tag": "div",
"text": {
"tag": "lark_md",
"content": "<at id=\"ou_xxx\">Nombre</at> contenido del mensaje"
}
}
Referencia rápida de sintaxis Markdown (dentro de lark_md / etiqueta markdown)
Estilos de texto
**Negrita** *Cursiva* ~~Tachado~~ `Código en línea`
Texto con color
<font color=red>Rojo</font>
<font color=green>Verde</font>
<font color=grey>Gris</font>
<font color=blue>Azul</font>
<font color=orange>Naranja</font>
<font color=wathet>Azul agua</font>
<font color=purple>Púrpura</font>
Colores completos: red / green / grey / blue / orange / wathet / purple / yellow / turquoise / indigo / violet / lime
Etiquetas / Insignias numéricas
<text_tag color='red'>Etiqueta</text_tag>
<number_tag>99</number_tag>
Hora localizada
<local_datetime millisecond='1700000000000' format_type='date_num'></local_datetime>
format_type: date_num (2023/11/15) / date_full (15 de noviembre de 2023) / datetime (con hora, minutos y segundos)
Títulos / Listas / Citas
# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6
- Desordenada 1. Ordenada > Cita
Bloques de código
```python
print("hola")
```
Imágenes (dentro de Markdown)

Tablas (máximo 5 filas de datos)
| Col1 | Col2 |
|-----|-----|
| A | B |
Enlaces
[Texto](https://url) [Teléfono](tel://13800138000)
Línea divisoria / Salto de línea
--- o <hr>
<br/> o dos retornos de carro (salto de párrafo)
Emoji
⚠️ Reglas estrictas
- Solo se pueden usar las claves de la lista oficial. Las claves no incluidas (como
:WAITING:,:PROCESSING:) se mostrarán como texto plano, está prohibido usarlas. - Las mayúsculas y minúsculas de las claves deben coincidir exactamente con las oficiales (por ejemplo,
Fireno esFIRE,Trophyno esTROPHY,Shrugno esSHRUG). - Dentro de
<text_tag>,:KEY:no se renderiza, se debe usar el emoji Unicode (por ejemplo,✅). :KEY:solo funciona en el área de texto normal delark_md.
Comúnmente usados en notificaciones de lanzamiento
:DONE: :OK: :THUMBSUP: :APPLAUSE:
:PARTY: :FIREWORKS: :MUSCLE: :THANKS:
:Trophy: :Fire: :Hundred: :CheckMark:
Trabajo y estado
:LGTM: :OnIt: :OneSecond: :Get:
:ERROR: :CrossMark: :Pin: :Alarm:
:Loudspeaker: :OKR: :Yes: :No:
:HEADSET: :Typing: :MeMeMe: :Sigh:
:Lemon: :AWESOMEN: :VRHeadset: :YouAreTheBest:
:SALUTE: :HIGHFIVE: :FISTBUMP: :FINGERHEART:
:WAVE: :ThumbsDown:
Emojis - Positivos
:SMILE: :LAUGH: :LOL: :LOVE:
:WINK: :PROUD: :WITTY: :JOYFUL:
:WOW: :BLUSH: :HUG: :BeamingFace:
:Delighted: :ThanksFace: :SaluteFace: :PRAISE:
:CLAP: :JIAYI: :FACEPALM: :YEAH:
Emojis - Negativos / Divertidos
:CRY: :SOB: :ANGRY: :SHOCKED:
:Shrug: :THINKING: :DIZZY: :SLEEP:
:YAWN: :SICK: :SWEAT: :EMBARRASSED:
:SKULL: :RAINBOWPUKE: :PUKE: :ClownFace:
:ColdSweat: :SMUG: :SILENT: :TERROR:
:PETRIFIED: :BETRAYED: :WRONGED:
Celebración y festivos
:PARTY: :FIREWORKS: :REDPACKET: :FORTUNE:
:FIRECRACKER: :XmasTree: :XmasHat: :Snowman:
:Pumpkin: :Mooncake: :MoonRabbit: :Partying:
:StickyRiceBalls: :JubilantRabbit: :LUCK:
:FullMoonFace: :GoGoGo: :HappyDragon:
Objetos y comida
:ROSE: :HEART: :BEER: :CAKE:
:GIFT: :BOMB: :Fire: :Trophy:
:Coffee: :BubbleTea: :Drumstick: :Pepper:
:CUCUMBER: :CANDIEDHAWS: :Soccer: :Basketball:
:Music: :CLEAVER: :EatingFood: :LIPS:
Indicadores de estado (no usar con frecuencia, solo en contextos de estado)
:GeneralDoNotDisturb: :GeneralInMeetingBusy:
:StatusReading: :GeneralWorkFromHome:
:GeneralBusinessTrip: :StatusInFlight:
:GeneralSun: :GeneralMoonRest:
:StatusFlashOfInspiration: :Status_PrivateMessage:
:GeneralTravellingCar: :StatusBus:
Emoji Unicode (usar en títulos, dentro de text_tag, en subtítulos del header)
🎉 ✅ ❌ ⚠️ 🚀 📦 💬 ⏳ 🔔 📝 🛠️ 🔍 👋 🎯 💡 🌟
👥 📅 🤖 🏆 🔥 💯 📣 🎁 ☕ 🍺
Estilo recomendado: Usa emoji Unicode en los títulos para mejorar el impacto visual, usa la sintaxis específica de Feishu como
:DONE::LGTM:para estado/retroalimentación
Enviar / Responder / Actualizar
Enviar a un grupo (nuevo mensaje)
CARD=$(python3 -c "
import json
card = {
'schema': '2.0',
'header': {'title': {'tag': 'plain_text', 'content': 'Título'}, 'template': 'blue'},
'body': {'elements': [{'tag': 'markdown', 'content': 'Contenido'}]}
}
print(json.dumps(card))
")
lark-cli im +messages-send \
--chat-id oc_xxx \
--msg-type interactive \
--content "$CARD" \
--as bot
Responder a un mensaje específico (obtener message_id para futuras actualizaciones)
MSG_ID=$(lark-cli im +messages-reply \
--message-id om_xxx \
--msg-type interactive \
--content "$CARD" \
--as bot \
--jq '.data.message_id')
Responder a un hilo (no aparece en el flujo principal del chat)
lark-cli im +messages-reply \
--message-id om_xxx \
--msg-type interactive \
--content "$CARD" \
--reply-in-thread \
--as bot
Prevenir envíos duplicados (misma clave solo se envía una vez en 1 hora)
lark-cli im +messages-send \
--chat-id oc_xxx \
--msg-type interactive \
--content "$CARD" \
--idempotency-key "deploy-654.0-notify" \
--as bot
Actualizar tarjeta en el mismo lugar (PATCH)
PAYLOAD=$(jq -n --argjson card "$CARD" '{"msg_type":"interactive","content":($card|tojson)}')
lark-cli api PATCH "/open-apis/im/v1/messages/${MSG_ID}" \
--data "$PAYLOAD" \
--as bot
Plantillas de tarjetas
Pensando... (estado de streaming, primero enviar marcador de posición)
make_thinking_card() {
local name="$1" question="$2"
jq -n --arg name "$name" --arg q "$question"
…
[truncado para traducción]