{"id":4075,"library":"lark-oapi","title":"Lark (Feishu) OpenAPI Python SDK","description":"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.","status":"active","version":"1.5.3","language":"en","source_language":"en","source_url":"https://github.com/larksuite/oapi-sdk-python","tags":["API Client","Lark","Feishu","OpenAPI","Messaging","Collaboration"],"install":[{"cmd":"pip install lark-oapi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"HTTP client for making API requests.","package":"requests","optional":false},{"reason":"JSON Web Token (JWT) handling for authentication.","package":"PyJWT","optional":false},{"reason":"Cryptographic operations, often used for event decryption.","package":"cryptography","optional":false}],"imports":[{"symbol":"Client","correct":"from lark_oapi import Client"},{"symbol":"AppSettings","correct":"from lark_oapi import AppSettings"},{"note":"API models are nested under `api.<module>.<version>`.","symbol":"ListMessageRequest","correct":"from lark_oapi.api.im.v1 import ListMessageRequest"}],"quickstart":{"code":"import os\nfrom lark_oapi import Client, AppSettings\nfrom lark_oapi.api.im.v1 import ListMessageRequest\n\n# Get credentials from environment variables\n# Register your app on the Lark/Feishu Open Platform to get APP_ID and APP_SECRET.\napp_settings = AppSettings(\n    app_id=os.environ.get(\"LARK_APP_ID\", \"\"),\n    app_secret=os.environ.get(\"LARK_APP_SECRET\", \"\"),\n    # For event handling, also set:\n    # verification_token=os.environ.get(\"LARK_VERIFICATION_TOKEN\", \"\"),\n    # encrypt_key=os.environ.get(\"LARK_ENCRYPT_KEY\", \"\"),\n)\n\n# Build the client\nclient = Client.builder() \\\n    .app_settings(app_settings) \\\n    .log_level(Client.LOG_LEVEL_INFO) \\\n    .build()\n\n# Example: List messages in a specific chat\n# NOTE: Replace \"oc_xxxxxxxx\" with an actual chat ID your app has access to.\n#       Ensure your Lark app has 'Read messages from group chats it joined' permission.\nprint(\"Attempting to list messages...\")\ntry:\n    # This request attempts to fetch the latest message from a specified chat.\n    # For a real scenario, you'd need a valid chat_id (e.g., from an event subscription).\n    request = ListMessageRequest.builder().chat_id(\"oc_xxxxxxxx\").page_size(1).build()\n    response = client.im.v1.message.list(request)\n\n    if response.code == 0:\n        print(\"Successfully listed messages:\")\n        if response.data and response.data.items:\n            for message in response.data.items:\n                print(f\"  Message ID: {message.message_id}, Content: {message.body.content if message.body else 'N/A'}\")\n        else:\n            print(\"  No messages found or data empty.\")\n    else:\n        print(f\"Failed to list messages: {response.code} - {response.msg}\")\n        # Detailed error info often in response.error\n        if response.error:\n            print(f\"  Error details: {response.error}\")\n\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\nprint(\"Quickstart finished.\")","lang":"python","description":"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')."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (API changes are external to SDK versioning)"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}