MeetStream Guide: Raise & Lower Hand

Make a bot raise or lower its hand in a live meeting. Use it when your agent wants to speak but should wait its turn instead of talking over people: raise the hand, wait for the host or the conversation to make room, then speak and lower the hand.

How it works

You send a raise_hand or lower_hand command to a bot that is in the meeting. The bot uses the meeting’s own raise-hand control, exactly as a person would, so everyone in the meeting sees the hand go up or down.

The bot then checks the meeting again and tells you the result. The hand_raised field in the response is the hand state the bot saw after acting, not just an echo of what you asked for.

The commands are safe to repeat. If the hand is already in the state you asked for, the bot does nothing and returns 200 with the current state.

Prerequisites

• A bot that is in the meeting (status InMeeting or Recording). A bot that is still joining or waiting in the lobby cannot raise its hand.
• Your MeetStream API key.
• The host has not turned off raise hand for the meeting.

Supported platforms

Endpoint

POST https://api.meetstream.ai/api/v1/bots/{bot_id}/send_command

Example: Raise hand

curl -X POST "https://api.meetstream.ai/api/v1/bots/{bot_id}/send_command" \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"command": "raise_hand"}'

Response (200)

{
  "status": "accepted",
  "bot_id": "83acdd72-3257-4b06-a2e9-0d879dc571ff",
  "command": "raise_hand",
  "hand_raised": true
}

Example: Lower hand

curl -X POST "https://api.meetstream.ai/api/v1/bots/{bot_id}/send_command" \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"command": "lower_hand"}'

Response (200)

{
  "status": "accepted",
  "bot_id": "83acdd72-3257-4b06-a2e9-0d879dc571ff",
  "command": "lower_hand",
  "hand_raised": false
}

Example: Raise, speak, lower (Python)

import requests
API = "https://api.meetstream.ai/api/v1/bots"
HEADERS = {"Authorization": "Token <YOUR_API_KEY>"}
def set_hand(bot_id: str, raised: bool) -> bool:
    command = "raise_hand" if raised else "lower_hand"
    resp = requests.post(
        f"{API}/{bot_id}/send_command",
        headers=HEADERS,
        json={"command": command},
        timeout=15,
    )
    resp.raise_for_status()
    return resp.json()["hand_raised"]
set_hand(bot_id, True)    # hand goes up
# ... wait for your turn, then have the bot speak ...
set_hand(bot_id, False)   # hand goes down

Behavior notes

• The response reflects the meeting. hand_raised is read back from the meeting after the bot acts.
• Repeats are no-ops. Raising a hand that is already up, or lowering one that is already down, returns 200 with the current state and changes nothing.
• Someone else may lower the hand. The host can lower the bot’s hand. On Google Meet, the meeting also lowers a raised hand on its own once that participant speaks. Send lower_hand before your next raise_hand if you are not sure of the current state. It returns the real state without acting when the hand is already down.
• Response time. A command usually completes in 1 to 2 seconds. Allow up to 10 seconds before treating a request as failed.
• One hand command at a time. If you send several hand commands to the same bot at once, the bot runs them in order. A command that waits too long behind another one returns 503 with hand_command_busy without acting, so it is never applied late. Retry it.
• Reactions are not supported. Emoji reactions (thumbs up, clap and so on) are not available through this command.

Conditions

• The bot must be in the meeting (InMeeting or Recording status). Requests sent while the bot is joining, waiting in the lobby, or after it has left return 409.
• Rate limit: 30 requests per minute per bot, shared with the other in-meeting commands you send to the same bot.
• Bots running in a region outside the US return 501 for now.

Error Responses