Deliver Beta

Deliver content by intent and let Dopl route it to one of the user's devices

Beta. This endpoint is live for design partners, with keys that Dopl issues while the developer portal is being built.

POST /v1/users/{external_user_id}/deliver

Dopl routes the request, checks the grant and the tier, and enforces the device's limits without rewriting the content. routed_to says which device and why. An ask holds up to 200 seconds for the answer (send Prefer: respond-async to skip the hold); read it with Get an action and the delivery_id. With overflow: "callback" and content over the limits, nothing is delivered, status is failed and the response adds overflow_callback. Secret key, scope actions:write.

Authorizations

Authorizationrequiredheaderstring

A project secret key (sk_test_… or sk_live_…) sent as Authorization: Bearer <key>. Server to server only.

Idempotency-Keyheaderstring

Optional. When sent it must equal the body's idempotency_key, or the request fails with invalid_request. A retry with the same key and body returns the first response; the same key with a different body returns idempotency_conflict.

Preferheaderstring

respond-async (RFC 7240): do not hold an ask for its answer. The 202 returns at once with status queued or delivered; read the answer with GET /actions/{id} or the action.completed webhook. Other preferences are ignored.

Path parameters

external_user_idrequiredpathstring

Your own ID for the end user, 1 to 255 characters. End users never need a Dopl account.

Body

intentrequired"message" | "ask" | "notify" | "display"

message, ask, notify or display. The SDK's notify, show and ask set this for you.

contentrequiredDeliverContent

At least one of text, blocks (display blocks) or options (two or more choices).

urgencyrequired"low" | "normal" | "high"

low (the active device only), normal (the top device) or high (every eligible device).

targetstring

auto (the default), a device kind, or a device ID.

profilestring

One of your project's profile IDs, applied to this request only.

idempotency_keyrequiredstring

1 to 255 characters, unique per request within the environment. The TypeScript SDK fills one when you pass none.

StatusBody
202DeliverResponse
400, 401, 403, 404, 409, 429Error