# Configuring Card Interactions
Message cards provide four types of interactive components (buttons, overflow buttons, select menus, date pickers), in which the interaction components can be categorized into two types: jump interactions and callback interactions. This article will explain how to configure different card interaction modes.warning
This document refers to legacy message cards and is no longer maintained. To view the corresponding updated documentation, refer to [Configuring card interactions](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configuring-card-interactions).
## Considerations
The validity period for card interactions is 30 days. After the expiration date, cards do not support interactions. Users will be prompted with **This card was sent over 30 days ago and cannot be interacted with** when clicked.
## Interaction modes
The interaction methods of interactive components are divided into jump interaction and postback interaction. described as follows:
- **Jump Interaction**: In buttons (buttons) and fold button groups (overflow), jump links can be configured. The user will jump to the specified link after clicking the button.
- **Callback Interaction**: Each interactive element or interaction option provides a return parameter `value` field. After the user clicks on the interactive element or option, the business party will receive the corresponding `value` field value to determine the subsequent business processing logic.
Different interactive components support different interaction methods. You can view detailed instructions through the documentation of each component:
- [button](https://open.feishu.cn/document/ukTMukTMukTM/uEzNwUjLxcDM14SM3ATN): Supports jump interaction or postback interaction.
- [overflow](https://open.feishu.cn/document/ukTMukTMukTM/uMzNwUjLzcDM14yM3ATN): Supports jump interaction or postback interaction.
- [selectMenu](https://open.feishu.cn/document/ukTMukTMukTM/uIzNwUjLycDM14iM3ATN): Support postback interaction.
- [datePicker](https://open.feishu.cn/document/ukTMukTMukTM/uQzNwUjL0cDM14CN3ATN): supports postback interaction.
## Jump interaction: Jumping to specified link
In button components or button options within an overflow button, you can configure jump interactions. Jump interactions can be set to a single fixed jump link or differentiated jump links for PC, Android, and iOS. When users click the button, they will be redirected to the specified link.
- Visual configuration example in the message card builder:
- JSON configuration example:
```json
// If you want to use this JSON example, please note that you need to manually clear the comments at the beginning of //
{
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "overflow",
"options": [
{
"text": {
"tag": "plain_text",
"content": "This is a link jump"
},
"value": "appStore",
"url": "https://app.feishu.cn" // jump link
},
{
"text": {
"tag": "plain_text",
"content": "This is another link jump"
},
"value": "document",
"url": "https://open.feishu.cn"
}
]
}
]
}
]
}
```
## Callback interaction: Submitting operation information to the server
Callback interaction refers to when a user interacts with the interactive components in the message card, the Feishu app sends an HTTP POST request to the specified server, which contains the user's operation data. You can handle further business logic based on the received user operation data on the server side (e.g., requesting to update card content) and respond to the user's interactive behavior in a timely manner. Follow the steps below to configure callback interactions.
**Note**:
Multiple interactive components can exist within a message card, but they are independent of each other. This means that any user action on any component completes an interaction immediately.
### Step 1: Configure the message card request URL in the Feishu app that sends the message
For detailed operations, refer to [Configuring Card Callback](https://open.feishu.cn/document/ukTMukTMukTM/uYzMxEjL2MTMx4iNzETM).
### Step 2: Configure the interaction information within the message card
1. Configure the callback parameter (`value`).
In each interaction component, you can configure the callback parameter (`value`). After users click on the interaction component, the `value` will be sent to the **Message Card Request URL**, and you can further process the received `value` on the server side.
Explanation of callback parameter configuration: The `value` only supports a JSON structure with key-value pairs, where the key is of type String. Here is an example JSON configuration:
```json
"value":{
"key-1":Object-1,
"key-2":Object-2,
"key-3":Object-3,
······
}
```
2. Configure card update method.
In the `config` attribute of the card, you can set the `update_multi` parameter, which determines the card update method. For detailed information about card attributes, refer to [Configuring Card Attributes](https://open.feishu.cn/document/ukTMukTMukTM/uAjNwUjLwYDM14CM2ATN).
- Shared Card (`"update_multi":true`): When responding to the message card callback and updating the card content, it applies to all recipients of the current card. An example request body when sending the card is as follows:
```json
{
"chat_id": "oc_5**********************1fa",
"msg_type": "interactive", // message card type
"card": { // card content
"config": {
"update_multi":true // shared card, declaring that this card update will take effect for all recipients
},
··· // other card content
}
}
```
- Exclusive Card (`"update_multi":false`): When responding to the message card callback and updating the card content, it only updates the card of the currently operating user or specifies which users' cards to update by specifying the `open_ids` field when sending the update card request.
The concepts of shared card and exclusive card only apply to cards that are updated after interaction. There is no distinction for cards initially sent, meaning all recipients receive the same card.
### Step 3: Receive the interaction data returned by user clicking the interactive component
After users operate on the interactive components within the message card, the application that sent the message will send an HTTP POST request to the configured **Message Card Request URL**, including the user interaction information. On your server side, you can further process the received interaction information for business logic. The example request body is as follows:
```json
{
"open_id": "ou_sdfimx9948345", // the open_id of the user who interacted with the card
"user_id": "eu_sd923r0sdf5", // the user_id of the user who interacted with the card
"open_message_id": "om_abcdefg1234567890", // unique ID of the card message
"tenant_key": "d32004232", // ID of the tenant that the card message belongs to
"token": "c-xxxxx", // token (credential) for updating the card
"action":
{
"value":{ // value of the callback parameter
"key":"value"
},
"tag": "button" // identification of the interactive component
}
}
```
The request body parameters are explained in the following table.
Parameter | Type | Description
---|---|---
open_id | String | User's open_id. For information about user open_id and user_id, refer to [User Identity Overview](https://open.feishu.cn/document/home/user-identity-introduction/introduction).
user_id | String | User's user_id.
tenant_key | String | Tenant identifier. For parameter information, refer to [Common Parameters](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/terminology).
open_message_id | String | Message ID.
token | String | Refresh token. The server can use this token to update the message card within 30 minutes (up to two updates).
action | JSON Object | Interaction information.
∟ value | JSON Object | Value of the interaction component's `value` field in key-value format.
∟ tag | String | Identification of the interaction component, corresponding to the `tag` field of the component. Possible values:
- date_picker
- picker_time
- picker_datetime
- overflow
- select_static: Custom option mode for list selector
- select_person: Person selection mode of list selector
- button
∟ option | String | Callback parameter value of the interaction component option (`option`).
datePicker, overflow, and selectMenu will return this parameter. The button component does not contain the `option` parameter and will not return the field value.
Difference between `open_id`, `user_id`, and `tenant_key`:
- `tenant_key`: Unique identifier for the tenant.
- `user_id`: Unique user identifier within the tenant for multiple apps. The user_id is unique for the same user in different apps.
- `open_id`: User identifier for one specific app within the tenant. The same user will have different `open_id`s in different apps.
### Step 4: Respond to the POST request
After receiving the POST request from the application to **Message Card Callback URL**, the server needs to respond to the request with `HTTP 200` status code within 3 seconds (if it does not respond in time, the user client will display a request error), you can choose When responding to the POST request, the user's card content is immediately updated based on the business processing results; you can also choose to only respond to the request and delay the update of the user's card content. The different update card methods and response configurations are described below.
- The method of updating cards is applicable to both shared cards and exclusive cards. Sharing or exclusive only affects the visible range of card update content.
- There is no limit on the total number of card updates, but card updates are only allowed within 30 days of the card being sent.
#### **Update card content immediately**
If you need to update card content directly in response to a POST request, you need to set the new card's content (i.e., JSON data) into the `HTTP Body` of the response. The code logic requirements for responding to requests are as follows:
- Respond to the request with an `HTTP 200` status code within 3 seconds.
- Set the content of the new card into `HTTP Body`. There is no need to include the outermost `card` level when setting.
- If your card's elements is built in pure JSON code, pass the JSON data directly into `HTTP Body`. An example structure is as follows:
```json
{
// It needs to be the real card content. If the returned card content is illegal, an error will be reported after the user clicks it.
"header":{......},
"elements":[
{......},
{......},
......
]
}
```
- If your card is built with the card builder, pass the card template data into `HTTP Body`. An example structure is as follows:
```json
{
"type": "template", // Fixed value
"data":{
"template_id":"xxxxxxxxxxxx", // Card ID, required parameter. Can be acquired in the card builder.
"template_version_name":"1.0.0", // Card version. Default as empty which means using the latest version.
"template_variable":
{
"key1":"value1", // If card variables are set in the card template, you can assign values (key) to the variables here.
"key2":"value2"
}
}
}
```
#### Delayed update of card content
If the method of immediately updating the card content is not suitable for the current business processing logic, you can call the [Delayed Update Message Card](https://open.feishu.cn/document/ukTMukTMukTM/uMDO1YjLzgTN24yM4UjN) interface to asynchronously update the card, but before calling the interface, you must first respond to POST ask. The correct processing logic is as follows:
1. After receiving the card's POST request for return interaction, the server needs to respond to the request with the `HTTP 200` status code within 3 seconds.
Since the card content does not need to be updated immediately, the `HTTP Body` needs to be set to the string `"{}"` when responding.
2. After completing the response, call the **Delayed Update Message Card** interface to update the card.
- This step must be executed after responding to the postback interactive POST request. If executed in parallel or in advance, the update will fail.
- The `token` for delayed update is valid for 30 minutes. After the validity period, the `token` becomes invalid and the card cannot be updated for this user interaction. The same `token` supports updating the card twice at most.
When calling the **Delayed Update Message Card** interface, you need to pass in the card update token and new card content. The card update token is obtained in the return interaction request. An example of the request structure for delayed updates is as follows:
```json
{
"token":"xxx", //Card update voucher returned in POST request
"card":{
"open_ids":["xxx","xxx"...], // Specify the list of users who need to update the message
// card content
}
}
```
## FAQ
### If the POST request fails or the immediate update operation times out, the client will prompt that the operation failed or the network timed out. What should I do if the card does not refresh in this scenario?
Troubleshooting plan:
- Whether the message card request URL is configured.
- Whether the card click event was responded to with an `HTTP 200` status code within 3 seconds.
### What to do if the update timing of the card is not triggered by the interactive component of the message card (for example, the approval operation is completed in the enterprise's self-built approval system, not in the message card, and the card is only used to synchronize the approval results)?
You can call the [Update message sent by application](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/patch) interface to request to update the card.