Get or refresh token. The cache is keyed by app ID so different apps do not reuse tokens. Skill

Troubleshooting

If requests fail, first check the required credentials:

zero doctor check-connector --env-name LARK_APP_ID
zero doctor check-connector --env-name LARK_TOKEN

Then call the token endpoint with both values in the request body. The tenant access token endpoint requires app_id and app_secret; this skill stores the Lark app secret in LARK_TOKEN.

Token Management

Lark uses tenant access tokens that expire after 2 hours. Use this helper to get or refresh the token:

# Get or refresh token. The cache is keyed by app ID so different apps do not reuse tokens.
get_lark_token() {
  local token_file="/tmp/lark_token_${LARK_APP_ID}.json"
  local current_time=$(date +%s)

  # Check if cached token is still valid
  if [ -f "$token_file" ]; then
    local expire_time=$(jq -r '.expire_time // 0' "$token_file" 2>/dev/null || echo "0")
    if [ "$current_time" -lt "$expire_time" ]; then
      jq -r '.tenant_access_token' "$token_file"
      return 0
    fi
  fi

  # Get new token
  local response=$(curl -s -X POST "https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal" \
    -H "Content-Type: application/json" \
    -d "{\"app_id\": \"${LARK_APP_ID}\", \"app_secret\": \"${LARK_TOKEN}\"}")

  local code=$(echo "$response" | jq -r '.code // -1')
  if [ "$code" != "0" ]; then
    echo "Error: $(echo "$response" | jq -r '.msg')" >&2
    return 1
  fi

  local expire=$(echo "$response" | jq -r '.expire')
  local expire_time=$((current_time + expire - 300))
  echo "$response" | jq ". + {expire_time: $expire_time}" > "$token_file"
  jq -r '.tenant_access_token' "$token_file"
}

# Usage in commands
TOKEN=$(get_lark_token)

Or get token directly without caching:

TOKEN=$(curl -s -X POST "https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\": \"$LARK_APP_ID\", \"app_secret\": \"$LARK_TOKEN\"}" | jq -r '.tenant_access_token')

Examples

1. Authentication - Get Access Token

Get and display tenant access token:

Write to /tmp/lark_request.json:

cat > /tmp/lark_request.json <<EOF
{
  "app_id": "${LARK_APP_ID}",
  "app_secret": "${LARK_TOKEN}"
}
EOF

curl -X POST "https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

2. Messaging - Send Messages

Send Text Message to User

Write to /tmp/lark_request.json:

{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Hello World\"}"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Send Text Message to Group Chat

Write to /tmp/lark_request.json:

{
  "receive_id": "oc_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Group message\"}"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Send Rich Text (Post) Message

Write to /tmp/lark_request.json:

{
  "receive_id": "ou_xxx",
  "msg_type": "post",
  "content": "{\"zh_cn\": {\"title\": \"Title\", \"content\": [[{\"tag\": \"text\", \"text\": \"Content\"}]]}}"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Send Interactive Card Message

Write to /tmp/lark_request.json:

{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"Alert\"}}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"plain_text\", \"content\": \"Message\"}}]}"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Reply to Message

Write to /tmp/lark_request.json:

{
  "msg_type": "text",
  "content": "{\"text\": \"Reply content\"}"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages/om_xxx/reply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Get Chat History

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/im/v1/messages?container_id_type=chat&container_id=oc_xxx&page_size=20" \
  -H "Authorization: Bearer ${TOKEN}"

3. Chat Management - Group Operations

Create Group Chat

Write to /tmp/lark_request.json:

{
  "name": "Project Team",
  "description": "Project discussion group",
  "user_id_list": ["ou_xxx", "ou_yyy"]
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

List All Chats

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/im/v1/chats" \
  -H "Authorization: Bearer ${TOKEN}"

Get Chat Info

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/im/v1/chats/oc_xxx" \
  -H "Authorization: Bearer ${TOKEN}"

Add Members to Chat

Write to /tmp/lark_request.json:

{
  "id_list": ["ou_xxx", "ou_yyy"]
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Remove Members from Chat

Write to /tmp/lark_request.json:

{
  "id_list": ["ou_xxx"]
}

TOKEN=$(get_lark_token)
curl -X DELETE "https://open.larksuite.com/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

4. Contacts - Directory Queries

Get User Info

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/users/ou_xxx?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"

Look Up User IDs by Email or Mobile

Write to /tmp/lark_request.json:

{
  "emails": ["user@example.com"],
  "mobiles": ["+15551234567"],
  "include_resigned": false
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/contact/v3/users/batch_get_id?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

List Departments

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/departments?parent_department_id=0" \
  -H "Authorization: Bearer ${TOKEN}"

Get Department Members

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"

5. Calendar - Schedule Management

List Calendars

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}"

Create Calendar

Write to /tmp/lark_request.json:

{
  "summary": "Project Calendar",
  "description": "Calendar for project events"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Create Calendar Event

Note: Replace <calendar_id> with an actual calendar ID from List Calendars API.

TOKEN=$(get_lark_token)

# Convert ISO 8601 to Unix timestamp
START_TS=$(date -d "2025-01-15T10:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-15T11:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T11:00:00+08:00" +%s)

# Write request with timestamps
cat > /tmp/lark_request.json <<EOF
{
  "summary": "Team Meeting",
  "description": "Weekly sync",
  "start_time": {"timestamp": "${START_TS}"},
  "end_time": {"timestamp": "${END_TS}"}
}
EOF

curl -X POST "https://open.larksuite.com/open-apis/calendar/v4/calendars/<calendar_id>/events" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

List Calendar Events

TOKEN=$(get_lark_token)

# Convert date range
START_TS=$(date -d "2025-01-01T00:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-01T00:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-31T23:59:59+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-31T23:59:59+08:00" +%s)

curl -X GET "https://open.larksuite.com/open-apis/calendar/v4/calendars/<calendar_id>/events?start_time=${START_TS}&end_time=${END_TS}" \
  -H "Authorization: Bearer ${TOKEN}"

6. Bot Information

Get Bot Info

TOKEN=$(get_lark_token)
curl -X GET "https://open.larksuite.com/open-apis/bot/v3/info" \
  -H "Authorization: Bearer ${TOKEN}"

Workflows

Send System Alert to Group

Write to /tmp/lark_request.json:

{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"System Alert\"}, \"template\": \"red\"}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"lark_md\", \"content\": \"**Error:** Service down\"}}]}"
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Create Team Group with Members

Write to /tmp/lark_request.json:

{
  "name": "Q1 Project",
  "description": "Q1 project discussion",
  "user_id_list": ["ou_abc", "ou_def", "ou_ghi"]
}

TOKEN=$(get_lark_token)
curl -X POST "https://open.larksuite.com/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Query Organization Structure

TOKEN=$(get_lark_token)

# Get root departments
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/departments?parent_department_id=0" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.data.items[] | {id: .department_id, name: .name}'

# Get members in a department
curl -X GET "https://open.larksuite.com/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.data.items[] | {id: .user_id, name: .name}'

Schedule a Meeting

TOKEN=$(get_lark_token)

START_TS=$(date -d "2025-01-20T09:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-20T09:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-20T10:30:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-20T10:30:00+08:00" +%s)

# Write request with timestamps
cat > /tmp/lark_request.json <<EOF
{
  "summary": "Sprint Planning",
  "description": "Sprint 5 planning session",
  "start_time": {"timestamp": "${START_TS}"},
  "end_time": {"timestamp": "${END_TS}"}
}
EOF

curl -X POST "https://open.larksuite.com/open-apis/calendar/v4/calendars/<calendar_id>/events" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Message Types Reference

| Type | msg_type | content Format | |------|----------|----------------| | Text | text | {"text": "message"} | | Rich Text | post | {"zh_cn": {"title": "...", "content": [...]}} | | Image | image | {"image_key": "img_xxx"} | | Card | interactive | {"header": {...}, "elements": [...]} |

ID Types Reference

| ID Type | Description | Example | |---------|-------------|---------| | open_id | User open ID (default) | ou_xxx | | user_id | User ID | abc123 | | union_id | Union ID across apps | on_xxx | | email | User email address | user@example.com | | chat_id | Group chat ID | oc_xxx |

Guidelines

Token Management: Tokens expire after 2 hours. Use the get_lark_token helper function for automatic caching and refresh.
Rate Limits: Lark has rate limits per app. Add delays for bulk operations to avoid hitting limits.
ID Types: Use open_id for most user operations. Use chat_id when targeting group chats.
Card Builder: Design complex interactive cards using Lark Card Builder: https://open.larksuite.com/tool/cardbuilder
Error Handling: Check the code field in responses. 0 means success, non-zero indicates an error.

Content Escaping: Message content must be JSON-escaped when passed as string. Use jq to build complex payloads:

CONTENT=$(jq -cn --arg text "Hello" '{text: $text}')
jq -n \
  --arg receive_id "ou_xxx" \
  --arg content "$CONTENT" \
  '{receive_id: $receive_id, msg_type: "text", content: $content}' \
  > /tmp/lark_request.json

Date Conversion: Calendar events require Unix timestamps. Use date command with appropriate flags for your OS:
- Linux: date -d "2025-01-15T10:00:00+08:00" +%s
- macOS: date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s

API Reference

API Documentation: https://open.larksuite.com/document/home/index
API Explorer: https://open.larksuite.com/api-explorer
Card Builder: https://open.larksuite.com/tool/cardbuilder
Permissions: https://open.larksuite.com/document/home/introduction-to-scope-and-authorization/overview

Agent Skills: Get or refresh token. The cache is keyed by app ID so different apps do not reuse tokens.

Install this agent skill to your local

Skill Files

Troubleshooting

Token Management

Examples

1. Authentication - Get Access Token

2. Messaging - Send Messages

Send Text Message to User

Send Text Message to Group Chat

Send Rich Text (Post) Message

Send Interactive Card Message

Reply to Message

Get Chat History

3. Chat Management - Group Operations

Create Group Chat

List All Chats

Get Chat Info

Add Members to Chat

Remove Members from Chat

4. Contacts - Directory Queries

Get User Info

Look Up User IDs by Email or Mobile

List Departments

Get Department Members

5. Calendar - Schedule Management

List Calendars

Create Calendar

Create Calendar Event

List Calendar Events

6. Bot Information

Get Bot Info

Workflows

Send System Alert to Group

Create Team Group with Members

Query Organization Structure

Schedule a Meeting

Message Types Reference

ID Types Reference

Guidelines

API Reference