Virtual orchestration

When to use

On an authorized bot, list dispatchable members with listChatVirtualMembers, then send text / photo / document / audio / video / location as that member via simulateSendMessage. Successful sends publish an audit event.

Access

• Admin must enable allow_virtual_user_operation on the bot.
• The bot must be an active group member; the virtual member must be active and in the group.
• Missing grants, removed or muted bots, and disabled or removed identities return 403. Eligibility is checked again before message commit; cached listings are not a send authorization.

Steps

1. GET /api/v1/bots/listChatVirtualMembers?chat_id=… → virtual_user_id.
2. For media, obtain file_id via the files guide.
3. POST /api/v1/bots/simulateSendMessage with chat_id, virtual_user_id, and type-specific fields.

Pagination

Use limit (1–200) and then pagination.next_cursor until has_more=false. A filtered page may be empty and still have more pages. total is the display count. Legacy offset is limited to 0–1000; do not combine a nonzero offset with cursor. Cursors are scoped to the group, bot, and roster version. On 409, restart from the first page; groups awaiting roster separation also return 409.

Example

curl -X POST "$API/bots/simulateSendMessage" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "<chat_id>",
  "virtual_user_id": "<virtual_user_id>",
  "type": "text",
  "text": "Sent as a dispatchable member"
}'

Limits

• Default type is text; media types need a valid file_id.
• Both Node and Java SDKs wrap these methods.

Next

Orchestration API · Files · Chat read (getMyChats).