Anima

Appearance

Feishu runbook for agents ​

Read this when you are handling Feishu work and the normal anima command help is not enough. The command reference has exact commands and API snippets. This page is the operating model: what the Feishu identifiers mean, which settings humans must configure, and how to avoid blind retries.

The mental model ​

Your Feishu identity is a Feishu app with a bot account. Anima delivers Feishu messages to you and sends your replies back through that app. For ordinary visible output, use audited Anima commands: anima message send, anima message read, anima message update, anima file fetch, and anima message react.

Some Feishu actions do not have first-class Anima commands yet, such as creating a group or adding members to a group. For those, you may call Feishu OpenAPI directly with FEISHU_TENANT_ACCESS_TOKEN. Do not print or log that token. Anything a human should see still goes through anima message, so the action is visible in Anima's audit trail.

Do not start with web search. First inspect the delivery envelope and this runbook, then use the command reference for the exact call.

Feishu identifiers ​

  • chat_id starts with oc_. It names a Feishu conversation. It can be a DM, a group, or a topic container. Use it with anima message send --chat-id <chat_id>.
  • message_id usually starts with om_. It names a message. For a topic reply, pass the topic thread_id when present, otherwise the root message_id, as --thread-ts.
  • open_id usually starts with ou_. It is the stable user identifier you normally want for mentions and human invites.
  • user_id is the tenant user identifier. Use it only when the envelope or user gave it explicitly.
  • app_id starts with cli_. It identifies a Feishu app. Use an Anima-created agent's Feishu App ID when inviting another bot into a chat.

Display names are not identifiers. If you only have a name, ask the user to mention that person in Feishu and send the request again. The mention metadata gives Anima stable IDs.

Permissions are not visibility ​

Feishu has two separate gates:

  • API permissions, also called scopes. These let the app perform actions like send messages, read group messages from users and bots, add group members, look up users by email or phone, or work with Feishu Drive and cloud documents. Users authorize these in Anima's Feishu setup flow and publish a new app version.
  • App visibility or availability range. This controls which users can see or use the app. It is configured in the Feishu developer console or admin console. The app cannot grant itself wider visibility through OpenAPI.

If an API call says a scope is missing, ask the user to add the recommended permission and publish a new app version. If a member invite fails with 232024 and says users do not have app visibility, ask the user to add the target person, department, or all members to the app's visibility or availability range, save or publish that change, then retry.

Replying, reading, and editing ​

Use the envelope. In a Feishu chat:

anima message send --chat-id <chat_id> <<'ANIMA_MESSAGE'
<reply>
ANIMA_MESSAGE

For a topic, include the topic id:

anima message send --chat-id <chat_id> --thread-ts <thread_id_or_root_message_id> <<'ANIMA_MESSAGE'
<reply>
ANIMA_MESSAGE

Use anima message read --chat-id <chat_id> when you need recent chat history. Add --thread-ts when you need a topic's thread history. Use anima message update --chat-id <chat_id> --message-ts <message_id> only for messages you sent.

Mentioning people ​

When you know a user's open_id, mention them in message text like this:

<mention open_id="ou_...">Name</mention>

Anima sends that as a Feishu rich-text mention. Do not write raw @Name when the user needs a real mention. Do not invent an open_id from a name.

Creating a group ​

There is no first-class anima command for Feishu group creation yet. Use the direct Feishu API path in the command reference. The practical sequence is:

  1. Get at least one user open_id from the envelope, usually the person who asked you.
  2. Call the chat-create API once.
  3. Read the JSON response. If it contains chat_id, the group exists.
  4. Send the visible confirmation or test message with anima message send --chat-id <chat_id>.

Do not create another group just because you are unsure whether the first call worked. Check the response first.

Inviting people or bots ​

For a human teammate, prefer open_id. If the user mentions the teammate in Feishu, use the mention metadata. If you only have a tenant user_id, you may call the member API with member_id_type=user_id. If you only have a display name, ask for a mention, email, phone number, open_id, or user_id.

For another Anima-created Feishu bot, invite by that agent's Feishu App ID, not by bot open_id. Ask the user to copy it from the target agent's Profile page if you cannot see it.

When invite calls fail:

  • 232024 or "visibility of the app" means app visibility is missing for the target user. Ask the user to update the app availability range, then retry.
  • A permission error means the current app probably lacks the group-member scope or the new app version has not been published.
  • A group management error means this bot may not be allowed to manage members in that specific group.

Report the specific error and the next human action. Do not keep trying the same identifiers after the platform has returned a configuration error.

Safe direct API use ​

Use FEISHU_TENANT_ACCESS_TOKEN only as an HTTP bearer token. Do not echo it, write it into a file, paste it into chat, or include it in command output. It is acceptable to check whether it exists without printing the value.

Keep visible communication separate from direct API work. A curl call may create a group or invite a member, but the human-facing explanation should still be sent with anima message send.