飞书消息发送技能

本技能提供通过手机号给飞书用户发送消息的功能。

使用场景

• 通过手机号发送飞书消息
• 发送飞书通知给用户
• 飞书消息推送
• 自动化消息发送

配置说明

在使用本技能前，你需要在配置文件中设置以下参数：

• APP_ID: 飞书应用的 App ID
• APP_SECRET: 飞书应用的 App Secret

获取方式：登录飞书开放平台 (https://open.feishu.cn/) -> 创建应用 -> 获取凭证

核心功能

1. 通过手机号获取用户ID

import lark_oapi as lark
from lark_oapi.api.contact.v3 import *

def get_user_id_by_mobile(client: lark.Client, mobile: str) -> str:
    """通过手机号获取飞书用户open_id"""
    request: BatchGetIdUserRequest = BatchGetIdUserRequest.builder() \
        .user_id_type("open_id") \
        .request_body(BatchGetIdUserRequestBody.builder()
            .mobiles([mobile])
            .build()) \
        .build()

    response = client.contact.v3.user.batch_get_id(request)

    if not response.success():
        raise Exception(f"获取用户ID失败: {response.msg}")

    user_list = response.data.user_list
    if not user_list or len(user_list) == 0:
        raise Exception(f"未找到手机号为 {mobile} 的用户")

    return user_list[0].user_id

2. 发送消息

from lark_oapi.api.im.v1 import *

def send_message(client: lark.Client, receive_id: str, content: str) -> str:
    """发送文本消息给用户"""
    import uuid

    request: CreateMessageRequest = CreateMessageRequest.builder() \
        .receive_id_type("open_id") \
        .request_body(CreateMessageRequestBody.builder()
            .receive_id(receive_id)
            .msg_type("text")
            .content(f'{{"text":"{content}"}}')
            .uuid(str(uuid.uuid4()))
            .build()) \
        .build()

    response = client.im.v1.message.create(request)

    if not response.success():
        raise Exception(f"发送消息失败: {response.msg}")

    return response.data.message_id

完整使用示例

import lark_oapi as lark
from lark_oapi.api.contact.v3 import *
from lark_oapi.api.im.v1 import *
import uuid

class FeishuMessageSender:
    def __init__(self, app_id: str, app_secret: str):
        self.client = lark.Client.builder() \
            .app_id(app_id) \
            .app_secret(app_secret) \
            .log_level(lark.LogLevel.WARNING) \
            .build()

    def send_message_by_mobile(self, mobile: str, content: str) -> str:
        """
        通过手机号发送飞书消息

        Args:
            mobile: 接收者手机号
            content: 消息内容

        Returns:
            message_id: 发送成功的消息ID
        """
        # Step 1: 通过手机号获取用户ID
        user_id = self.get_user_id_by_mobile(mobile)

        # Step 2: 发送消息
        message_id = self.send_message(user_id, content)

        return message_id

    def get_user_id_by_mobile(self, mobile: str) -> str:
        """通过手机号获取飞书用户open_id"""
        request = BatchGetIdUserRequest.builder() \
            .user_id_type("open_id") \
            .request_body(BatchGetIdUserRequestBody.builder()
                .mobiles([mobile])
                .build()) \
            .build()

        response = self.client.contact.v3.user.batch_get_id(request)

        if not response.success():
            raise Exception(f"获取用户ID失败: code={response.code}, msg={response.msg}")

        user_list = response.data.user_list
        if not user_list or len(user_list) == 0:
            raise Exception(f"未找到手机号为 {mobile} 的用户")

        return user_list[0].user_id

    def send_message(self, receive_id: str, content: str) -> str:
        """发送文本消息"""
        request = CreateMessageRequest.builder() \
            .receive_id_type("open_id") \
            .request_body(CreateMessageRequestBody.builder()
                .receive_id(receive_id)
                .msg_type("text")
                .content(f'{{"text":"{content}"}}')
                .uuid(str(uuid.uuid4()))
                .build()) \
            .build()

        response = self.client.im.v1.message.create(request)

        if not response.success():
            raise Exception(f"发送消息失败: code={response.code}, msg={response.msg}")

        return response.data.message_id


# 使用示例
if __name__ == "__main__":
    sender = FeishuMessageSender(
        app_id="YOUR_APP_ID",
        app_secret="YOUR_APP_SECRET"
    )

    try:
        message_id = sender.send_message_by_mobile(
            mobile="15011241234",
            content="这是一条测试消息"
        )
        print(f"消息发送成功，message_id: {message_id}")
    except Exception as e:
        print(f"发送失败: {e}")

错误处理

常见错误：

1. APP_ID 或 APP_SECRET 错误

• 错误信息：code: 99991663, msg: app_id not found
• 解决：检查配置文件中的 APP_ID 和 APP_SECRET 是否正确

1. 用户不存在

• 错误信息：未找到手机号为 xxx 的用户
• 解决：确认手机号是否正确，以及用户是否在组织内

1. 发送消息参数错误

• 错误信息：code: 99992402, msg: field validation failed
• 解决：确保添加 .receive_id_type("open_id") 参数

1. 应用没有权限

• 错误信息：Permission denied
• 解决：在飞书开放平台给应用添加im:message相关权限

1. 用户未激活

• 错误信息：user not found
• 解决：确认用户已在飞书开放平台激活

依赖安装

pip install lark-oapi

权限要求

在飞书开放平台需要配置以下权限：

• im:message:send_as_bot - 发送消息
• im:message:send_interactive - 发送消息卡片
• contact:user.id:get - 获取用户ID
• contact:user.mobile:get - 通过手机号获取用户