Documentation

Quick Start

AwaitHuman lets your AI agents ask you for help via Telegram. Three steps to get started:

1. Create an account

Sign in at app.awaithuman.com/login with your Google account.

2. Connect Telegram

You'll need two things:

A bot token — message @BotFather on Telegram and create a new bot
Your Telegram ID — message @userinfobot to get your numeric ID

3. Create an API key

Generate a key from the dashboard. Then use it to send your first task:

curl -X POST https://api.awaithuman.com/api/v1/tasks \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"yes_no","title":"Deploy?","description":"All tests pass."}'

API Reference

POST /api/v1/tasks

Create a new task. The human will be notified on Telegram.

Request body

{
  "type": "pick_one",         // pick_one | yes_no | review | do_for_me
  "title": "Which logo?",     // shown in Telegram notification
  "description": "Details...",// full context for the human
  "options": ["A", "B", "C"], // required for pick_one
  "image_urls": [],           // optional public image URLs
  "max_reminders": 3,         // default 3
  "reminder_interval_minutes": 30 // default 30
}

Response (201)

{ "task_id": "abc123", "status": "sent" }

GET /api/v1/tasks/{task_id}

Get task status and result. Poll this until status is completed or timed_out.

Response (200)

{
  "task_id": "abc123",
  "status": "completed",
  "result": {
    "choice": "A",       // for pick_one, yes_no, review
    "text": "feedback",  // for review (feedback) or do_for_me
    "image_urls": []     // for do_for_me with images
  }
}

GET /api/v1/tasks

List all tasks. Optional query param: ?status=pending

POST /api/v1/tasks/{task_id}/cancel

Cancel a pending task.

MCP Integration

For AI coding tools like Claude Code or Cursor, use the AwaitHuman MCP server. Your agent gets three tools: create_task, get_task_result, and wait_for_task.

MCP config (claude_desktop_config.json or .claude.json)

{
  "mcpServers": {
    "awaithuman": {
      "command": "uvx",
      "args": ["awaithuman-mcp"],
      "env": {
        "AWAITHUMAN_API_KEY": "sk_live_YOUR_KEY",
        "AWAITHUMAN_API_URL": "https://api.awaithuman.com/api/v1"
      }
    }
  }
}

Task Types

pick_one

Present options as Telegram inline buttons. Requires options array.

Result: {"choice": "Option A"}

yes_no

Two buttons: Yes and No.

Result: {"choice": "yes"} or {"choice": "no"}

review

Three buttons: Approve, Reject, Feedback. Feedback prompts a text reply.

Result: {"choice": "feedback", "text": "Make it bolder"}

do_for_me

Free-form. Human replies with text, images, or taps "Can't do this".

Result: {"text": "Done, the email is hello@example.com"}