Lark (Feishu) OpenAPI Python SDK

Warnings

• breaking Lark API version changes can significantly affect import paths and request/response models. For example, `im.v1` might become `im.v2`, requiring updates to `from lark_oapi.api.im.v1 import ...` paths and potentially the structure of request builders or response parsing.
  Fix: Always check the official Lark Open Platform API documentation and the SDK's release notes for breaking API changes and update imports and model usage accordingly.
• gotcha Incorrect `app_id` or `app_secret`, or insufficient app permissions, are the most common causes of API call failures. The client will initialize, but API calls will return errors (e.g., `response.code != 0`, HTTP 4xx errors, or specific Lark error messages).
  Fix: Double-check `LARK_APP_ID` and `LARK_APP_SECRET` against your Lark Open Platform app settings. Verify that your app has all required permissions enabled for the APIs you are calling (e.g., read messages, access user info) in the Lark Developer Console.
• gotcha When setting up event subscriptions, `verification_token` and `encrypt_key` must be provided in `AppSettings` to properly verify and decrypt incoming webhook callbacks. Omitting them or providing incorrect values will lead to failures in processing events, despite successful client initialization.
  Fix: Retrieve the `Verification Token` and `Encryption Key` from your app's 'Event Subscriptions' settings in the Lark Developer Console and include them in `AppSettings` when processing events.
• gotcha Many API endpoints require a specific `id_type` (e.g., `open_id`, `user_id`, `union_id`) for parameters like `user_id` or `chat_id`. Using the wrong `id_type` or an ID that doesn't match the specified type will result in 'resource not found' or permission errors, even if the ID itself is valid for a different type.
  Fix: Carefully consult the API documentation for each endpoint to confirm the required `id_type` and ensure the provided ID matches that type. Use conversion APIs if necessary to get the correct `id` for the desired `id_type`.
• gotcha The SDK does not automatically implement retry logic or backoff strategies for API rate limits. Hitting rate limits will result in `response.code` indicating a rate limit error (e.g., `10005`, `10006`), potentially leading to data loss or application downtime if not handled gracefully.
  Fix: Implement custom retry logic with exponential backoff for API calls. Monitor API usage and consider optimizing calls or requesting higher rate limits from Lark if necessary.

Install

• pip install lark-oapi Install stable version

Imports

• Client

  from lark_oapi import Client

• AppSettings

  from lark_oapi import AppSettings

• ListMessageRequest

  from lark_oapi.api.im.v1 import ListMessageRequest

  API models are nested under `api.<module>.<version>`.

Quickstart

This quickstart initializes the Lark OpenAPI client using `LARK_APP_ID` and `LARK_APP_SECRET` from environment variables. It then attempts to list a single message from a placeholder chat ID using the `im.v1.message.list` API. For successful execution, you must replace `oc_xxxxxxxx` with a valid chat ID and ensure your Lark app has the necessary permissions (e.g., 'Read messages from group chats it joined').

import os
from lark_oapi import Client, AppSettings
from lark_oapi.api.im.v1 import ListMessageRequest

# Get credentials from environment variables
# Register your app on the Lark/Feishu Open Platform to get APP_ID and APP_SECRET.
app_settings = AppSettings(
    app_id=os.environ.get("LARK_APP_ID", ""),
    app_secret=os.environ.get("LARK_APP_SECRET", ""),
    # For event handling, also set:
    # verification_token=os.environ.get("LARK_VERIFICATION_TOKEN", ""),
    # encrypt_key=os.environ.get("LARK_ENCRYPT_KEY", ""),
)

# Build the client
client = Client.builder() \
    .app_settings(app_settings) \
    .log_level(Client.LOG_LEVEL_INFO) \
    .build()

# Example: List messages in a specific chat
# NOTE: Replace "oc_xxxxxxxx" with an actual chat ID your app has access to.
#       Ensure your Lark app has 'Read messages from group chats it joined' permission.
print("Attempting to list messages...")
try:
    # This request attempts to fetch the latest message from a specified chat.
    # For a real scenario, you'd need a valid chat_id (e.g., from an event subscription).
    request = ListMessageRequest.builder().chat_id("oc_xxxxxxxx").page_size(1).build()
    response = client.im.v1.message.list(request)

    if response.code == 0:
        print("Successfully listed messages:")
        if response.data and response.data.items:
            for message in response.data.items:
                print(f"  Message ID: {message.message_id}, Content: {message.body.content if message.body else 'N/A'}")
        else:
            print("  No messages found or data empty.")
    else:
        print(f"Failed to list messages: {response.code} - {response.msg}")
        # Detailed error info often in response.error
        if response.error:
            print(f"  Error details: {response.error}")

except Exception as e:
    print(f"An unexpected error occurred: {e}")

print("Quickstart finished.")