# 拉取链接预览数据

**拉取链接预览数据** 回调作用于应用的链接预览能力。当企业内发布了具备链接预览能力的应用后，企业成员在飞书客户端查看、发送链接时，如果链接命中了应用注册的 URL 规则，则应用会向指定的回调地址发送 **拉取链接预览数据** 回调。你需要在对应的业务服务器内接收回调请求，并在 3 秒内响应回调请求，飞书客户端会根据响应数据渲染链接预览效果。
需应用配置并生效链接预览能力后，回调才可以推送生效。

## 回调

基本信息 |  
---|---
回调类型 | url.preview.get
支持的应用类型 | Custom App、Store App
权限要求<br>**订阅该事件所需的权限，开启其中任意一项权限即可订阅**<br>开启任一权限即可 | 暂无
字段权限要求 | **注意事项**：事件结构体中存在 `user_id` 敏感字段，仅当应用开启以下权限后才会返回。如果无需获取该字段，则不建议申请。<br>获取用户 user ID(contact:user.employee_id:readonly)
推送方式 | [Webhook](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)

## 结构体

字段 | 数据类型 | 描述
---|---|---
schema | string | 回调的版本。
header | object | 回调的基本信息。
event_id | string | 回调的唯一标识。
token | string | 应用的 Verification Token。
create_time | string | 回调发送的时间。
event_type | string | 回调类型。拉取链接预览场景中，固定为 `"url.preview.get"`。
tenant_key | string | 应用归属的 tenant key，即租户唯一标识。
app_id | string | 应用的App ID。
event | object | 回调的详细信息。
operator | object | 回调触发者信息。
tenant_key | string | 回调触发者的 tenant key，即租户唯一标识。
user_id | string | 回调触发者的 user_id。了解不同的用户 ID，参见[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。
open_id | string | 回调触发者的 open_id。
host | string | 链接预览展示的场景。可能值:<br>- im_message：会话消息<br>- im_top_notice：群置顶
context | object | 场景上下文。
url | string | 预览链接。
preview_token | string | 预览 Token。该 Token 用于调用[更新 URL 预览](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/group/im-v2/url_preview/batch_update)接口，主动更新 URL 预览。<br>**注意**：<br>- 同一条消息的同一个链接可能会触发多次拉取链接预览数据回调（例如多端登录飞书查看消息、群聊内多个用户查看消息等），这些回调包含的 preview_token 值相同。<br>- 消息发送后才会产生 preview_token，因此，临时预览场景（即在会话输入框输入链接，但消息还未发送时），不会产生 preview_token。
open_message_id | string | 链接所在的消息 ID。<br>**注意**：临时预览场景（即在会话输入框输入链接，但消息还未发送时）open_message_id 为空值。
open_chat_id | string | 链接所在的会话 ID。<br>**注意**：临时预览场景（即在会话输入框输入链接，但消息还未发送时）open_chat_id 为空值。

## 回调结构体示例

```json
{
    "schema": "2.0",
    "header": {
        "event_id": "f7984f25108f8137722bb63cee92xxxx",
        "token": "066zT6pS4QCbgj5Do145GfDbbagCxxxx",
        "create_time": "1603977298000000",
        "event_type": "url.preview.get",
        "tenant_key": "xxxxxxx",
        "app_id": "cli_xxxxxxxx"
    },
    "event": {
        "operator": {
            "tenant_key": "xxxxxxx",
            "user_id": "xxxxxxx",
            "open_id": "ou_xxx"
        },
        "host": "im_message",
        "context": {
            // url相关参数
            "url": "xxx",
            "preview_token": "xxx",
            "open_message_id": "om_xxx",
            "open_chat_id": "oc_xxx"
        }
    }
}
```

## 响应回调的结构体

当你在自建的业务服务器中接收 **拉取链接预览数据** 回调请求时，需要在 3 秒内响应该请求，飞书客户端会根据响应数据渲染链接预览效果。相应回调的结构体如下表所示。

字段 | 是否必选 | 数据类型 | 描述
---|---|---|---
inline | 否 | object | 链接预览数据。
title | 否 | string | 链接预览的标题。<br>**注意事项**：**说明**：该参数与 `i18n_title` 同时设置时，优先生效 `i18n_title`。
i18n_title | 否 | Map | 链接预览的多语言标题。<br>**注意事项**：**说明**：该参数与 `title` 同时设置时，优先生效 `i18n_title`。
key | 否 | string | 语言。可选值：<br>- zh_cn：简体中文<br>- zh_tw：繁体中文（中国台湾）<br>- zh_hk：繁体中文（中国香港）<br>- en_us：英语<br>- ja_jp：日语<br>- fr_fr：法语<br>- hi_in：印地语<br>- id_id：印度尼西亚语<br>- it_it：意大利语<br>- ko_kr：韩语<br>- pt_br：葡萄牙语（巴西）<br>- ru_ru：俄语<br>- th_th：泰语<br>- vi_vn：越南语<br>- de_de：德语<br>- es_es：西班牙语
value | 否 | string | 语言对应的标题。
image_key | 否 | string | 链接的前缀图标对应的 image_key。你可以通过[上传图片](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口，上传一张用于发送消息的图片，并在返回结果中获取 image_key。
url | 否 | object | 链接预览地址。
copy_url | 否 | string | 在消息中复制链接所获取到的 URL。
ios | 否 | string | iOS 跳转 URL。
android | 否 | string | Android 跳转 URL。
pc | 否 | string | PC 端跳转 URL。
web | 否 | string | Web 跳转 URL。
card | 否 | object | 卡片数据。
type | card 内必填 | string | 卡片类型。可选值：<br>- template：卡片模板类型，即通过卡片 ID、版本号定位卡片。<br>- raw：卡片 JSON，通过完整的卡片 JSON 构建卡片。<br>了解如何构建卡片，参见[构建卡片内容](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/build-card-content)。
data | card 内必填 | object | 卡片内容。
template_id | template 类型必填 | string | 卡片模板 ID。模板类型卡片使用的字段。
template_variable | 否 | Map | 卡片模板变量。模板类型卡片使用的字段。
template_version_name | 否 | string | 卡片模版版本。模板类型卡片使用的字段。
config | 否 | object | 卡片配置。raw 类型卡片使用的字段。
elements | raw 类型必填 | object | 卡片组件。raw 类型卡片使用的字段。
header | 否 | string | 卡片标题。raw 类型卡片使用的字段。

## 响应回调结构体示例

```json
{
    "inline": {
        "i18n_title": {
            "zh_cn": "smart card test click jump & rich text"
        },
        "image_key": "img_v3_025m_5xxxxxf9-ed30-4980-afff-827e13d8xxxx"
    },
    "card": {
        "type": "template",
        "data": {
            "template_id": "AAqVG2xxxxxBS",
            "template_version_name": "1.0.0",
            "template_variable": {}
        }
    }
}
```