workflow/docs/api-reference/workflow-runtime/world/queue.mdx

Workflow SDK - Build durable, resilient, and observable workflows

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

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

<Callout type="warn">
  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.
</Callout>

## 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