> ## Documentation Index
> Fetch the complete documentation index at: https://bilt.me/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# bilt_send_message

> Send build instructions or answer agent questions for a project

## Overview

Send natural language instructions to build features, deploy apps, or modify existing code. The MCP server calls the synchronous messages endpoint and waits for the agent to finish, pause for input, error, or accept the work into the queue.

<Info>
  Use [bilt\_get\_session](/docs/api-reference/bilt_get_session) to check queued/running workflow status and preview URLs between requests.
</Info>

## Parameters

<ParamField path="projectId" type="string" required>
  The project to send the message to

  * **Format**: UUID
  * **Example**: `"660e8400-e29b-41d4-a716-446655440001"`
</ParamField>

<ParamField path="message" type="string">
  Natural language instruction for the AI agent.

  * **Required** for fresh requests unless `answers` is provided
  * **Examples**:
    * `"Add a login screen with email and password fields"`
    * `"Deploy to production"`
    * `"Fix the undefined variable error in UserComponent"`
</ParamField>

<ParamField path="workflowId" type="string">
  Workflow ID from a paused `questions` response.

  * **Format**: UUID
  * **Required** when `answers` is provided
  * Copy this from the `workflowId` field in the paused response
</ParamField>

<ParamField path="answers" type="string">
  JSON array of structured answers when the agent paused for clarification questions.

  * **Format**: `[{"questionIndex": 0, "selectedOptions": ["Option A"]}]`
  * **Required** when continuing a paused question workflow (along with `projectId` and `workflowId`)
  * You may include an optional `message` alongside the answers
</ParamField>

<Warning>
  At least one of `message` or `answers` must be provided.
</Warning>

## Response

Responses vary by status. All successful responses include `previewUrl` and `projectUrl`.

<ResponseField name="status" type="string" required>
  `"completed"`, `"queued"`, `"paused"`, `"error"`, or `"timeout"`
</ResponseField>

<ResponseField name="sessionId" type="string">
  Session identifier for the project
</ResponseField>

<ResponseField name="workflowId" type="string">
  Workflow identifier for the current run
</ResponseField>

<ResponseField name="previewUrl" type="string">
  URL to preview the app in the browser
</ResponseField>

<ResponseField name="projectUrl" type="string">
  URL to open the project in the Bilt web app
</ResponseField>

<ResponseField name="response" type="string">
  Agent response text when `status` is `"completed"`. Omitted when `status` is `"queued"` because the agent has accepted the work but has not started generating a response yet.
</ResponseField>

<ResponseField name="pauseType" type="string">
  When `status` is `"paused"`: `"questions"`, `"secrets"`, or `"supabase"`
</ResponseField>

<ResponseField name="questions" type="array">
  Clarification questions when `status` is `"paused"` and `pauseType` is `"questions"`
</ResponseField>

<ResponseField name="secrets" type="object">
  Secret request details when `status` is `"paused"` and `pauseType` is `"secrets"`
</ResponseField>

<ResponseField name="supabase" type="object">
  Supabase connection request details when `status` is `"paused"` and `pauseType` is `"supabase"`
</ResponseField>

<ResponseField name="error" type="string">
  Error details when `status` is `"error"` or `"timeout"`
</ResponseField>

## Example Usage

### Basic Feature Addition

<CodeGroup>
  ```json Request theme={null}
  {
    "projectId": "660e8400-e29b-41d4-a716-446655440001",
    "message": "Add a dark mode toggle in the navigation bar"
  }
  ```

  ```json Response theme={null}
  {
    "status": "completed",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "workflowId": "770e8400-e29b-41d4-a716-446655440002",
    "response": "Added a dark mode toggle to the navigation bar.",
    "previewUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001/preview",
    "projectUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001"
  }
  ```
</CodeGroup>

### Queued Response

When another workflow is already running, Bilt can accept the message into the queue and return immediately. Keep the `workflowId` and call [bilt\_get\_session](/docs/api-reference/bilt_get_session) for the same `projectId` until `hasActiveWorkflows` is false before sending unrelated follow-up work.

<CodeGroup>
  ```json Response theme={null}
  {
    "status": "queued",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "workflowId": "770e8400-e29b-41d4-a716-446655440002",
    "previewUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001/preview",
    "projectUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001"
  }
  ```
</CodeGroup>

### Paused for Questions

When the agent pauses for clarification, respond with structured `answers`:

<CodeGroup>
  ```json Request theme={null}
  {
    "projectId": "660e8400-e29b-41d4-a716-446655440001",
    "workflowId": "770e8400-e29b-41d4-a716-446655440002",
    "answers": "[{\"questionIndex\": 0, \"selectedOptions\": [\"Native stack navigation\"]}]"
  }
  ```

  ```json Response theme={null}
  {
    "status": "completed",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "workflowId": "770e8400-e29b-41d4-a716-446655440002",
    "response": "Using native stack navigation for the app.",
    "previewUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001/preview",
    "projectUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001"
  }
  ```
</CodeGroup>

### Paused for Secrets or Supabase

When `pauseType` is `"secrets"` or `"supabase"`, share the `projectUrl` with the user so they can complete the step in the Bilt web app. Do not try to supply secrets through this tool.

## Agent Workflow Example

<Steps>
  <Step title="Create project">
    ```text theme={null}
    Agent: bilt_create_project({ name: "todo-app" })
    Response: { id: "660e8400-e29b-41d4-a716-446655440001" }
    ```
  </Step>

  <Step title="Build features">
    ```text theme={null}
    Agent: bilt_send_message({
      projectId: "660e8400-e29b-41d4-a716-446655440001",
      message: "Create a todo list with add, delete, and complete actions"
    })
    Response: { status: "completed", previewUrl: "..." }
    ```
  </Step>

  <Step title="Deploy when ready">
    ```text theme={null}
    Agent: bilt_send_message({
      projectId: "660e8400-e29b-41d4-a716-446655440001",
      message: "Deploy to production"
    })
    ```
  </Step>
</Steps>

## Related Tools

<CardGroup cols={3}>
  <Card title="bilt_get_session" icon="clock" href="/docs/api-reference/bilt_get_session">
    Check workflow status
  </Card>

  <Card title="bilt_get_messages" icon="message" href="/docs/api-reference/bilt_get_messages">
    View conversation history
  </Card>

  <Card title="bilt_cancel_workflow" icon="xmark" href="/docs/api-reference/bilt_cancel_workflow">
    Stop running workflows
  </Card>
</CardGroup>