Deliver a message Beta

Send by intent and let Dopl pick the device

Beta. The Device SDK is live for design partners: Dopl issues your project's keys while the developer portal is being built, and @dopl/sdk is available on request. Agents that act for one signed in Dopl user can use the hosted MCP server instead.

Deliver is the one call most agents need. You say what you want to do, and Dopl picks the device, checks the grant and enforces the device's limits, as Context profiles and routing describes.

1. Choose the intent

Set intent to message, notify, display or ask, and put text, blocks or options in content. The SDK's notify, show and ask methods each make this call with the matching intent.

2. Send it

const delivery = await dopl.users.deliver("usr_123", {
  intent: "notify",
  content: { text: "Build finished in 4m 12s" },
  urgency: "normal",
  target: "auto",
});
{
  "delivery_id": "4f7e2a10-6c1b-4d9e-8a35-0b2c7d9e1f42",
  "routed_to": {
    "device_id": "8b0c6f1e-3d2a-4c51-9a7e-2f4d6b1c9e30",
    "kind": "glasses",
    "reason": "fallback chain"
  },
  "status": "done"
}

3. Pick the target when you need to

Leave target as auto to let Dopl route, or set a device kind such as desktop or a device ID to choose yourself. Add profile to apply one of your project's profiles to this request only, and urgency: "high" to reach every eligible device at once.

4. Retry safely

Every Deliver and device action carries an idempotency_key, in the body and optionally in an Idempotency-Key header, which must match it. Retrying with the same key and the same body returns the first response, status and body included, without delivering again. Reusing a key with a different body fails with idempotency_conflict. The SDK sends a fresh key on every call unless you pass your own as idempotencyKey, so pass one whenever you retry.

await dopl.notify("usr_123", { text: "Build finished", idempotencyKey: "build-4812" });

5. Read the outcome

Errors use the standard shape, and every response carries a Request-Id header naming the event Dopl recorded. The SDK throws a DoplError with the same code, retryable flag and requestId. Read the action later with GET /v1/actions/{id} and the delivery_id.

To call one capability on one device instead, use Run a device action.