---
title: Send Message (Async)
description: "Sends a new message to an existing chat and processes it in the background. Include designMode to apply element-scoped design edits; message may be omitted when edits are provided. Returns immediately with the assistant message ID. Poll GET /chats/:chatId/messages/:messageId and check `finishReason` to detect completion."
docs_index: /docs/llms.txt
lastUpdated: 2026-10-23
badge: "POST"
---

> For an index of all documentation, see [/docs/llms.txt](/docs/llms.txt).

Sends a new message to an existing chat and processes it in the background. Include designMode to apply element-scoped design edits; message may be omitted when edits are provided. Returns immediately with the assistant message ID. Poll GET /chats/:chatId/messages/:messageId and check `finishReason` to detect completion.

#### `POST /v2/chats/{chatId}/messages/async`

Include `designMode` to apply element-scoped edits. A nonempty `message` is required unless at least one edit is supplied. Without edits, Design Mode instructions require an element selector or screenshot. Use `createDesignModeBridge` from `v0/browser` to connect an embedded preview editor. See [Design Mode](/docs/api/v2/guides/design-mode) for browser SDK integration, headless operations, screenshots, and authentication restrictions.

## Usage

```typescript
import { v0 } from 'v0'

const result = await v0.messages.sendAsync({
  chatId: 'chat_abc123',
  message: 'Hello, world!',
})

console.log(result)
```

```bash
curl -X POST "https://api.v0.dev/v2/chats/chat_abc123/messages/async"   -H "Authorization: Bearer $V0_API_KEY"   -H "Content-Type: application/json"   -d '{"message":"Hello, world!"}'
```

## API Signature

### Request

#### Path Parameters

- `chatId: string` The unique identifier of the chat.
  - **Minimum length:** 1

#### Request Body

- `message?: string` The prompt or instruction to send to the model. May be omitted when designMode contains edits.
  - **Minimum length:** 1
- `designMode?: object` Apply element-scoped design edits using Design Mode. Source changes are model-generated, not deterministic DOM patches. The Design Mode model is selected automatically, regardless of modelConfiguration.modelId.
  - `edits?: ('style' | 'deleteElement' | 'move' | 'fontInjection')[]` Element edits to apply to the source code. Maximum 100.
    - **Maximum items:** 100
    - **style**
      - `type: 'style'`
      - `element: object`
        - `selectorPath: string` CSS selector identifying the rendered element.
          - **Minimum length:** 1
        - `tagName: string` HTML tag name, such as h1 or button.
          - **Minimum length:** 1
        - `id?: string` Element ID, if present.
        - `classNames?: string[]` Element CSS classes.
        - `textContent?: string` Current text of the element, to help locate its source.
        - `reactComponentName?: string` React component name, if known.
      - `changes: Record<string, object>` CSS property names in camelCase mapped to old and new values. Use textContent for text replacement.
    - **deleteElement**
      - `type: 'deleteElement'`
      - `element: object`
        - `selectorPath: string` CSS selector identifying the rendered element.
          - **Minimum length:** 1
        - `tagName: string` HTML tag name, such as h1 or button.
          - **Minimum length:** 1
        - `id?: string` Element ID, if present.
        - `classNames?: string[]` Element CSS classes.
        - `textContent?: string` Current text of the element, to help locate its source.
        - `reactComponentName?: string` React component name, if known.
    - **move**
      - `type: 'move'`
      - `element: object`
        - `selectorPath: string` CSS selector identifying the rendered element.
          - **Minimum length:** 1
        - `tagName: string` HTML tag name, such as h1 or button.
          - **Minimum length:** 1
        - `id?: string` Element ID, if present.
        - `classNames?: string[]` Element CSS classes.
        - `textContent?: string` Current text of the element, to help locate its source.
        - `reactComponentName?: string` React component name, if known.
      - `toParentSelector?: string` Destination parent selector. Required when position is inside.
        - **Minimum length:** 1
      - `targetSelector?: string` Destination sibling selector. Required when position is before or after.
        - **Minimum length:** 1
      - `position: 'before' | 'after' | 'inside'` Placement relative to the destination.
    - **fontInjection**
      - `type: 'fontInjection'`
      - `fontName: string` Font to add to the project, such as Inter.
        - **Minimum length:** 1
  - `element?: string` CSS selector limiting the scope of the message instructions.
    - **Minimum length:** 1
  - `screenshot?: object` Screenshot providing visual context for the requested edits.
    - `url: string` HTTPS image URL or base64 image data URI. Counts toward the attachment limits. Not supported for Vercel OIDC principals.
      - **Minimum length:** 1
    - `anchorElement?: string` CSS selector anchoring the screenshot to a rendered element.
      - **Minimum length:** 1
- `systemPrompt?: string` System-level context for the chat, such as frameworks or development environment details.
- `modelConfiguration?: object` Overrides for the model behavior.
  - `modelId: 'v0-mini' | 'v0-pro' | 'v0-max' | 'v0-max-fast' | string` Model to use for the generation. Use a v0 model ID, or an [AI Gateway](https://vercel.com/ai-gateway/models) model ID in `creator/model` format. Gateway models must support tool calling and Zero Data Retention, and are subject to team model policy; unsupported IDs are rejected.
  - `imageGenerations: boolean` Enables image generations to generate up to 5 images per version.
- `mcpServerIds?: string[]` MCP server IDs to enable. When omitted, uses default enabled servers.
- `attachments?: (object | object)[]` Files or assets to include with the message. Provide either a URL or data URI, or inline UTF-8 text content.
- `skills?: ('remote' | 'memory' | 'project')[]` Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.
  - **Maximum items:** 3
  - **remote**
    - `type: 'remote'` Discriminator: a skills.sh skill.
    - `id: string` Skill ID from skills.sh.
  - **memory**
    - `type: 'memory'` Discriminator: a user- or team-scoped memory skill.
    - `scope: 'user' | 'team'` Whether the skill lives in user or team memory.
    - `skillName: string` Name of the memory skill to attach.
  - **project**
    - `type: 'project'` Discriminator: a skill defined in the project repo.
    - `skillName: string` Name of the project skill to attach.

### Response

- `messageId: string` ID of the assistant message that will receive the response. Poll GET /chats/:chatId/messages/:messageId and check `finishReason` for completion.

---

For a semantic overview of all documentation, see [/docs/sitemap.md](/docs/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/docs/agents.md](/docs/agents.md)