# Send message cards that are only visible to certain people
Sends a message card that is visible only to a specified user in a group chat.The "Only visible to you" sign will be displayed on the card.
## Usage scenario
For example, in a group chat, the administrator needs to set the reminder date and reminder content through the to-do form card pushed by the robot. After the setting is completed, the card will be pushed to all group members. In this process, the robot can first push the form card visible only to the group administrator through this interface. After the administrator completes the interaction with the card, the robot will call the [Delete message card visible only to specific people](https://open.feishu.cn/document/ukTMukTMukTM/uITOyYjLykjM24iM5IjN) interface to delete the card message and send the completed to-do card to all group members for viewing.
After setting the card as a card visible only to specific people, the interaction process is only visible to the user, and other members in the group will only see the reminder card that is finally set, which can reduce the disturbance of messages to irrelevant users in the group chat and effectively reduce the noise of group messages.
## Prerequisites
Before calling this API, please make sure that your application has enabled [bot capability](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability) and the robot is in the conversation group.
## Frequency limit
When sending message cards visible only to specific people in the same group, the upper limit of the call frequency of this API is 40 QPS.
## Usage restrictions
- This API does not support topic groups (topic), only regular chat groups (group). For related concepts, refer to the [Basic Concepts of Groups](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/chat/chat-info/intro).
- This interface does not support [configuring multilingual content for specific parts of a card](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content#559f0561); it only supports [configuring multilingual content globally for the entire card](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content#ae4b3cb1).
- Cards sent through this API:
- Forwarding is not supported.
- Can only be sent to specific people in the group chat.
- Visible only on the Lark client of online users.
- If the @mention syntax is used in the card, the mentioned members will not receive a mention notification.
## Request
Facts |
---|---
HTTP URL | https://open.feishu.cn/open-apis/ephemeral/v1/send
HTTP Method | POST
Rate Limit | [1000 per minute、50 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes
**To use this API, you must have at least 1 of the listed scopes.**
Enable any scope from the list | Read and send messages in private and group chats(im:message)
Send messages as an app(im:message:send_as_bot)
Update message(im:message:update)
### Request header
Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`
Call the API on behalf of the app. The range of readable and writable data is determined by the app's own [data permission range](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/configure-app-data-permissions). Refer to [Get custom app tenant_access_token](https://open.feishu.cn/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/tenant_access_token_internal) or [Get store app tenant_access_token](https://open.feishu.cn/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/tenant_access_token).
Value format："Bearer access_token"
Example value："Bearer t-g1044qeGEDXTB6NDJOGV4JQCYDGHRBARFTGT1234"
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"
### Request body
Name | Type | Required | Description
---|---|---|---
chat_id | string | Yes | Target group ID. For how to obtain the group ID, see [Group ID Description](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-id-description). This API only supports regular groups in chat mode and does not support topic groups.
Example value: oc_5ad573a6411d72b8305fda3a9c1abcef
open_id | string | No | The user open_id of the visible card. For how to obtain the ID, see [How to obtain Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid).
**Note**: You only need to fill in one of `open_id`, `email`, or `user_id`, and all three fields cannot be empty at the same time. If you fill in more than one, the order of fields is `open_id` > `user_id` > `email`. It is recommended to use the `open_id` field.
Example value: ou_449b53ad6aee526f7ed311b216aabcef
user_id | string | No | The user_id of the user who can see the card. For more information on how to obtain the ID, please refer to [How to obtain the User ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id).
**Note**: You only need to fill in one of `open_id`, `email`, or `user_id`, and the three fields cannot be empty at the same time. If you fill in more than one, the order of the fields is `open_id` > `user_id` > `email`. It is recommended to use the `open_id` field.
**Example value**: gg895344
email | string | No | The email address of the user who can see the card.
**Note**: You only need to fill in one of `open_id`, `email`, or `user_id`, and all three fields cannot be empty at the same time. If you fill in more than one, the order of the fields is `open_id` > `user_id` > `email`. It is recommended to use the `open_id` field.
**Example value**: zhangmin@feishu.com
msg_type | string | Yes | The type of message, fixed value is `interactive`.
**Example value**: interactive
card | object | Yes | The description of the message card. For details, refer to [Card JSON Structure](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-structure). For example values, refer to the request body example below.
Message card content. Cards constructed with Card JSON or the [Card building tool](https://open.feishu.cn/cardkit?from=open_docs) are supported.
- To use card JSON, refer to [card JSON structure](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-structure). Example values can be found in the request body example below.
- To use the card template built by the [Card building tool](https://open.feishu.cn/cardkit?from=open_docs), you need to pass in the `type` and `data` parameters. Refer to the field descriptions at the end of the [Send card](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/send-feishu-card#461aa643-1) document for instructions on passing values.
### Request body example
- **Example of sending a card using JSON (using JSON 2.0 structure as an example)**
```json
{
"open_id": "ou_b9600a00cda86b8fad2378eafe3abcef",
"chat_id": "oc_20aa1ed9b18ba49f73f5773453aabcef",
"msg_type": "interactive",
"card": { // Pass the complete card JSON here, supports both 1.0 and 2.0 structures
"schema": "2.0",
"config": {
"update_multi": true,
"style": {
"text_size": {
"normal_v2": {
"default": "normal",
"pc": "normal",
"mobile": "heading"
}
}
}
},
"body": {
"direction": "vertical",
"padding": "12px 12px 12px 12px",
"elements": [
{
"tag": "markdown",
"content": "West Lake, located at No. 1 Longjing Road, Xihu District, Hangzhou City, Zhejiang Province, China, covers a catchment area of 21.22 square kilometers and a lake surface area of 6.38 square kilometers.",
"text_align": "left",
"text_size": "normal_v2",
"margin": "0px 0px 0px 0px"
},
{
"tag": "button",
"text": {
"tag": "plain_text",
"content": "🌞 More attractions"
},
"type": "default",
"width": "default",
"size": "medium",
"behaviors": [
{
"type": "open_url",
"default_url": "https://baike.baidu.com/item/%E8%A5%BF%E6%B9%96/4668821",
"pc_url": "",
"ios_url": "",
"android_url": ""
}
],
"margin": "0px 0px 0px 0px"
}
]
},
"header": {
"title": {
"tag": "plain_text",
"content": "Today's Travel Recommendation"
},
"subtitle": {
"tag": "plain_text",
"content": ""
},
"template": "blue",
"padding": "12px 12px 12px 12px"
}
}
}
```
- **Example of sending a card using a card template from the builder tool**
```json
{
"open_id": "ou_b9600a00cda86b8fad2378eafe3abcef",
"chat_id": "oc_20aa1ed9b18ba49f73f5773453aabcef",
"msg_type": "interactive",
"card": {
"type": "template",
"data": {
"template_id": "AAqigYkzabcef" // Fill in the actual card template ID here
}
}
}
```
The `type` and `data` parameters in `card` are described in the following table:
Parameter | Required | Description
---|---|---
type | Yes | The type of the card. To send a card built by the builder tool (also known as a card template), the fixed value is `template`.
data | Yes | The data of the card template. To send a card built by the builder tool, you need to pass the card template ID, card version number, etc. here.
└ template_id | Yes | The ID of the card (also known as acard template) created in the builder tool, such as `AAqigYkzabcef`. You can obtain it by copying the card template ID in the builder tool.
└ template_version_name | No | The version number of the card created in the builder tool, such as `1.0.0`. After the card is published, a version number will be generated. You can obtain it from the **Version Management** section in the builder tool.
**Note**: If this field is not filled, the latest version of the card will be used by default. This means that after a new version of the card is published in the builder tool, the new version will immediately take effect for API calls.
└└ template_variable | No | If the card is bound to variables, you need to pass the actual variable values in this field. For details, refer to [Configuring Card Variables](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/configure-card-variables).
## Response
### Response body
|Parameter|Type|Description|
|-|-|-|
|code|int|Return code. A value other than 0 indicates failure.|
|msg|string|Return code description|
data | - | -
∟message_id |string|Message ID
### Response body example
```json
{
"code": 0,
"data": {
"message_id": "om_fd2057276f16243756ff8eb6fcdabcef"
},
"msg": "ok"
}
```
## Error code
For details, refer to [Server-side error codes](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN).