Skip to main content

Lark Integration Guide

This guide will help you quickly configure and use FormAgent.ai's Lark integration to automatically sync visitor conversations to Lark, allowing your customer service team to view and respond to visitor inquiries within Lark.

✨ Features​

  • 🚀 One-Click Authorization - Quickly connect your Lark tenant via OAuth
  • 🎯 Visual Selection - Select message receiving groups directly from the interface after authorization
  • 📊 Auto-Sync Conversations - All visitor conversations automatically sync to Lark
  • 👤 Visitor Profile Display - Message cards include detailed visitor information (location, device, source, etc.)
  • 💬 Bidirectional Message Sync - Visitor messages and agent replies sync in real-time
  • 🔄 Human Takeover - Support one-click enable/disable human service in Lark
  • 🏷️ Real Name Display - Automatically display operator's real name

Prerequisites​

  • Lark account
  • FormAgent.ai account with created Agent
  • Administrator has completed Lark app configuration (if not configured, contact your system administrator)

Quick Start​

Step 1: Navigate to Integration Settings​

  1. Log in to FormAgent.ai admin dashboard
  2. Select your Agent
  3. Navigate to "Settings" → "Integrations" → "Lark"

Step 2: Connect to Lark​

  1. Click the "Connect to Lark" button on the page
  2. Your browser will redirect to the Lark authorization page
  3. Select the tenant you want to authorize
  4. Review the permissions list and click "Agree"

After successful authorization, the page will automatically return to FormAgent.ai.

Step 3: Add Bot to Group in Lark​

⚠️ Important: Only groups with the FormAgent.ai Bot added will appear in the next step's group list.

Create or open a group in Lark:

  1. Click the "···" menu in the upper right corner of the group
  2. Select "Group Settings" → "Group Bots"
  3. Click "Add Bot"
  4. Search for and add FormAgent.ai

Once the bot successfully joins the group, you can select that group in FormAgent.ai.

Step 4: Select Message Receiving Group​

Return to the FormAgent.ai integration settings page:

  1. Select the message receiving group from the dropdown (the group where you just added the bot)
  2. Click "Save" to save the configuration
  3. Enable the "Enable Integration" toggle

💡 Tips:

  • The dropdown list only shows groups with FormAgent.ai Bot added
  • If you don't see a group, first add the bot to that group in Lark
  • You can change groups at any time without re-authorizing

Using the Features​

View Visitor Conversations​

When a visitor sends a message on your website:

  1. A rich text message card will be automatically created in the Lark group
  2. The card contains visitor profile information
  3. Message replies display visitor messages and AI auto-replies
  4. The card footer has a "🚀 Start Human Service" button

Human Takeover​

When you need human intervention:

  1. In the Lark message card, click the "🚀 Start Human Service" button
  2. The system will display a prompt: "Human service enabled"
  3. AI auto-replies will pause
  4. Enter your customer service message in the message reply, and the visitor will receive your message in real-time
  5. The visitor's subsequent replies will also sync to the Lark group in real-time
  6. The system will display the operator's real name (not user ID)

End Human Service​

When the conversation ends or you want AI to resume auto-replies:

  1. Click the "End Human Service" button in the Lark message card
  2. The button status will revert to "🚀 Start Human Service"
  3. AI will resume auto-replying to the visitor's new messages

FAQ​

How to change groups?​

  1. In Lark, add the FormAgent.ai bot to the new group
  2. Navigate to the FormAgent.ai integration settings page
  3. Select the new group from the dropdown
  4. Click "Save"

💡 After changing groups, new conversations will be pushed to the new group, while old conversations remain in the original group

How to revoke authorization?​

Method 1: Revoke in FormAgent.ai

  1. Navigate to the integration settings page
  2. Click the "Disconnect" button
  3. Confirm revocation

Method 2: Revoke in Lark

  1. Go to Lark Workspace
  2. Select "App Management" → "My Apps"
  3. Find FormAgent.ai and click "Revoke Authorization"

Can multiple Agents share one authorization?​

Yes, but not recommended.

  • ✅ Recommended: Each Agent authorizes separately and can select different groups
  • ⚠️ Shared authorization: All Agents' messages will be sent to the same group, which may cause confusion

What if the group list is empty?​

Possible causes:

  1. You haven't added the FormAgent.ai bot to any groups yet
  2. You haven't joined any groups in Lark
  3. OAuth permissions missing required permissions (contact administrator)

Solutions:

  1. First, create or join a group in Lark
  2. Then, add the FormAgent.ai bot to that group (see Step 3)
  3. Finally, refresh the FormAgent.ai page, and the group will appear in the dropdown

💡 Tip: The dropdown only shows groups with FormAgent.ai bot added, not all groups you've joined

Why do message card buttons not respond when clicked?​

Possible causes:

  1. Card callback event not subscribed (contact administrator)
  2. Message card request URL configuration error (contact administrator)

Solution: Contact your system administrator to check the configuration

Why does it display user ID instead of real name?​

Symptom: Seeing "ou_xxx" or short ID instead of real name

Possible cause: Lark app missing permissions to read user information (contact administrator)

Solution: Contact your system administrator to add the relevant permissions

What if authorization redirect fails?​

Possible causes:

  1. Redirect URL configuration error
  2. Environment variables not properly configured

Solution: Contact your system administrator to check the configuration

Support​

For questions, please contact:

Document Version: v1.1 Last Updated: 2025-11-26 Update Notes: Adjusted step order, clarified that bot must be added before group appears in dropdown