> For the complete documentation index, see [llms.txt](https://documents.cxgenie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documents.cxgenie.ai/integrations-and-connections/platform-integration/lark/troubleshooting.md).

# Troubleshooting

### **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
```

3. Click **Add**
4. Publish your changes
5. 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**

3. Publish your changes
4. 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

***