---
title: Queue
description: Low-level queue interface for dispatching workflow invocations.
docs_index: /llms.txt
lastUpdated: 2026-10-21
type: reference
summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). The SDK normally handles internal queue dispatch."
keywords:
  - world.queue
  - getDeploymentId
  - queue
  - createQueueHandler
  - ValidQueueName
  - queue dispatch
prerequisites:
  - /docs/api-reference/workflow-runtime/get-world
related:
  - /docs/api-reference/workflow-api/start
  - /docs/foundations/starting-workflows
---

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

Queue methods live directly on the `world` object (not nested). They dispatch internal workflow invocations, including queued step work, to the queue backend.

> The Workflow SDK uses these methods internally to dispatch execution. In normal operations, use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. You only need direct queue access to start the initial execution of a run you programmatically created via `world.events.create()` with a `run_created` event, or to debug flow resumption.

## Import

```typescript lineNumbers
import { getWorld } from "workflow/runtime";

const world = await getWorld(); // [!code highlight]
// Call queue methods directly on world, for example, world.queue()
```

## Methods

### getDeploymentId()

Get the current deployment ID. The SDK uses it internally to route queue messages to the correct deployment.

```typescript lineNumbers
const deploymentId = await world.getDeploymentId(); // [!code highlight]
```

**Returns:** `string`. The current deployment ID.

### queue()

Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload` or `HealthCheckPayload`). Queued steps use `WorkflowInvokePayload` with `stepId` and `stepName`.

```typescript lineNumbers
const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
```

**Parameters:**

| Parameter   | Type             | Description                                                                                                            |
| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `queueName` | `ValidQueueName` | The queue name (branded string)                                                                                        |
| `message`   | `QueuePayload`   | Internal SDK payload                                                                                                   |
| `opts`      | `QueueOptions`   | Optional: `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers`, `region` (regional routing hint), `specVersion` |

**Returns:** `{ messageId: MessageId | null }`

### createQueueHandler()

Create an HTTP handler that processes messages from a queue. Use it to set up the queue consumer endpoint.

```typescript lineNumbers
const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
```

**Parameters:**

| Parameter  | Type                                                             | Description                                                                                        |
| ---------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `prefix`   | `QueuePrefix`                                                    | Queue name prefix to match                                                                         |
| `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |

**Returns:** `(req: Request) => Promise<Response>`

`meta.messageId` should be stable across redeliveries of the same message (one ID per enqueued message, reused on every delivery attempt). The runtime records it on inline `step_started` events as a liveness lease so that only a redelivery of the owning message re-executes a crashed inline step before the lease expires (see [Inline step message ownership](/docs/changelog/step-message-ownership)). A World whose queue mints a fresh ID per delivery degrades gracefully. Crashed inline steps recover via the delayed backstop instead of immediately on redelivery, but never wedge or duplicate.

## Related

- [start()](/docs/api-reference/workflow-api/start): The standard way to start workflow runs
- [Starting Workflows](/docs/foundations/starting-workflows): Core concepts for workflow invocation
- [Storage](/docs/api-reference/workflow-runtime/world/storage): Create events that trigger queue dispatch

---

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

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

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