Troubleshooting

This guide provides solutions for common issues that may occur when integrating Lark with CX Genie. Use this checklist when the connection fails, throws errors, or messages do not sync correctly.

1. Error 20029 – Invalid redirect_uri

Error Message:

Error Code: 20029 – The requested redirect_uri is invalid.

Cause: The Redirect URL configured in the Lark Developer Console does not match the URL required by CX Genie.

Solution:

1. Go to Lark Developer Console → Security Settings → Redirect URLs

2. Add the following URL exactly:

https://app.cxgenie.ai/integrations/lark

1. Click Add

2. Publish your changes

3. Retry the integration from CX Genie

---

2. Error 20027 – Missing offline_access Permission

Error Message:

Error Code: 20027 – This application does not request the offline_access permission. Authorization cannot proceed.

Cause: The app does not include the offline_access scope, which is required during OAuth authorization.

Solution:

1. Go to Permissions & Scopes

2. Add the following permission:

• offline_access

1. Publish your changes

2. Try the integration again

---

3. App is “Pending Release” or Not Published

Symptoms:

• Integration constantly fails

• Lark shows permission-related errors

• Changes in the Developer Console do not take effect

Cause: Your app configuration was saved but not published, so the latest settings are not active.

Solution:

1. Go to Version Management & Release

2. Click Create Version

3. Submit the version

4. Ask your organization admin to approve and publish

5. Retry the integration

---

4. Callback or Webhook Not Working

Symptoms

• Messages do not appear in CX Genie

• Bots do not respond

• “Test Callback” fails inside Lark Developer Console

Causes & Solutions

a. Incorrect Callback URL

Make sure the webhook URL is correct under both of these sections:

• Event Configuration

• Callback Configuration

Correct URL:

https://api.cxgenie.ai/api/v1/lark/webhook

b. Required events are not subscribed

Go to Events & Callbacks → Event Configuration, then add:

• im.message.receive_v1

• im.message.updated_v1

• card.action.trigger

c. Missing permissions for messages

Under Permissions & Scopes, ensure these permissions are added:

• Obtain private messages sent to the bot

• Obtain group messages mentioning the bot

• Obtain all messages in the associated group chats

Publish after updating.

---

5. Authorization Page Errors or Blank Screen

Possible Causes:

• Logged-in user does not have admin permissions

• Browser caching outdated tokens

• Redirect URL mismatch

• Missing required permissions

Solutions:

• Switch to a Lark admin account

• Logout and login again

• Clear browser cache

• Re-open integration flow from CX Genie

• Re-check Redirect URL under Security Settings

---

6. Integration “Connected,” but No Messages Sync to CX Genie

Checklist:

✔ Webhook URL is correct ✔ Events are correctly added ✔ Required permissions and scopes are active ✔ App is published ✔ Bot is added to the Lark group

Group Message Handling

To receive group messages in CX Genie:

1. Open the target Lark group

2. Add the custom app’s bot into the group

3. Ensure these scopes are enabled:

• Read group messages

• Detect @mentions

• Access full group chat messages (if needed)

---

7. “Invalid App ID / Secret” Error

Cause: Incorrect values copied, missing characters, or App Secret was regenerated.

Solution:

1. Go to Credentials & Basic Info

2. Copy the App ID and App Secret again

3. Paste them into CX Genie

4. If the App Secret was regenerated, click Reconnect in CX Genie

---

8. Bot Cannot Join a Lark Group

Symptoms:

• Group messages never sync

• “No permission” errors in logs

• Bot cannot be invited to a group

Solution:

1. Go to the group chat in Lark

2. Add the bot manually

3. Ensure message-related permissions are enabled

---