# 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

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documents.cxgenie.ai/integrations-and-connections/platform-integration/lark/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.