Registry / communication / lark-oapi

lark-oapi

JSON →
library1.7.3pypypi✓ verified 23d ago

The `lark-oapi` library is the official Python SDK for interacting with the Lark (Feishu) Open Platform APIs. It provides a programmatic interface for accessing Lark's various services, including messaging, contacts, calendar, and more. Currently at version 1.5.3, it follows a regular release cadence with updates reflecting API changes and new features from the Lark Open Platform.

pip install lark-oapi
INSTALL
IMPORT
SIG · LARK-OAPI
L
lark-oapi
communicationpythonv1.7.3
Install
10.4s avg
Import
7361ms
Disk
134MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.7.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 7.620s · 132.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 10.4s · import 7.102s · 133MB
134MB installed
● package 134MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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>`.

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.")
Debug
Known issues
breakingLark 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.
affects: All versions (API changes are external to SDK versioning)
gotchaIncorrect `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.
affects: All
gotchaWhen 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.
affects: All
gotchaMany 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`.
affects: All
gotchaThe 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.
affects: All
Errors
Common errors & fixes
ImportError: cannot import name 'lark_oapi' from 'lark_oapi'
This error typically occurs due to an incorrect package installation, a naming conflict where a local file or directory is also named 'lark_oapi', or an issue with the Python virtual environment.
fix
Ensure the official SDK is installed using `pip install lark-oapi`. Check your project directory for any files or folders named `lark_oapi.py` or `lark_oapi` that might be conflicting. Verify your Python virtual environment is correctly configured.
{"code":99991663,"msg":"tenant token invalid"}
The Tenant Access Token used in the API request is either expired, invalid, or incorrect, preventing the Lark Open Platform from authenticating the request.
fix
The `lark-oapi` SDK is designed to automatically manage the lifecycle of `Tenant Access Tokens`. Ensure you are using the SDK's client correctly for token handling. If you are manually managing tokens, re-obtain a fresh Tenant Access Token using the appropriate API before making further requests.
API Error Code 4001: "Invalid token, please refresh" or "The current request does not apply for relevant permissions."
This indicates issues with the application's credentials (App ID, App Secret), an expired `App Access Token`, or that the application lacks the necessary permissions (API scopes) to call the specific Lark Open API.
fix
Verify that your `App ID` and `App Secret` are correctly configured when initializing the `lark-oapi` client. In the Lark Developer Console, check that your application has applied for and been granted all required API permissions (scopes) for the API you are calling, and that these permissions have been successfully published and are active.
Client initialization missing mandatory parameters (e.g., app_id, app_secret) leading to subsequent API call failures.
The `lark-oapi` client was built without providing the essential `app_id` and `app_secret`, which are mandatory for authentication with the Lark Open Platform.
fix
When initializing the client using `lark.Client.builder()`, ensure you provide valid `app_id` and `app_secret` obtained from your application's credentials in the Lark Developer Console. Example: `client = lark.Client.builder().app_id("YOUR_APP_ID").app_secret("YOUR_APP_SECRET").build()`.
Upgrade
Version history
1.7.3latest on PyPI · released Aug 19, 2026
Audit
Dependencies
requestsrequiredHTTP client for making API requests.
PyJWTrequiredJSON Web Token (JWT) handling for authentication.
cryptographyrequiredCryptographic operations, often used for event decryption.
Agent activity
76 hits · last 30 days
node
72
OpenAI (training)
1
Resources
lark-oapi — pip install lark-oapi · libregistry