Quickstart Beta

Connect a simulated device and reach it from TypeScript in a few minutes

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.

This walkthrough connects a simulated device for one of your users and reaches it from your server with the TypeScript SDK. It uses a test key, so it needs no hardware and never touches live data.

1. Get a test key and the SDK

Sign in to the developer portal, pick your project and switch to Test, then copy a secret key from API keys. Test secret keys start with sk_test_ and only ever touch test data, so keep yours on your server. @dopl/sdk is private during testing and is available to design partners on request from sales@usedopl.com.

To try a call before writing code, paste the key into the portal's Playground. It runs the call on Dopl's servers against your test data and shows the request, the response and the log row.

DOPL_SECRET_KEY=sk_test_…
import { Dopl } from "@dopl/sdk";

const dopl = new Dopl({ apiKey: process.env.DOPL_SECRET_KEY! });

2. Create a Connect session

A Connect session is a short lived link for one of your users, identified by your own ID. List the scopes your agent needs and where the flow should send the user when it finishes.

const session = await dopl.connectSessions.create({
  external_user_id: "usr_123",
  requested_scopes: ["present.*", "ask.*"],
  redirect_uri: "http://localhost:3000/connected",
});

console.log(session.url); // https://www.usedopl.com/connect/ct_…

3. Pair a simulated device

Open session.url. With a test key the hosted page lists a simulated device of every kind. Choose Simulated glasses, press Continue under the pairing code it shows, then approve the scopes, which are grouped by risk tier. The page returns to your redirect_uri with a public_token query parameter.

4. Exchange the token

On your server, exchange the public_token for a durable connection. Each token works once, within 30 minutes.

const { connection_id, device } = await dopl.connections.exchange({ public_token });

console.log(device.kind, device.model); // glasses simulated_glasses

5. Notify, show and ask

Send by intent and leave the device to Dopl. Each helper is one call to Deliver, and the response says which device received it and why.

const sent = await dopl.notify("usr_123", { text: "Your build finished in 4m 12s" });
console.log(sent.routed_to); // { device_id, kind: "glasses", reason: "fallback chain" }

await dopl.show("usr_123", {
  blocks: [{ id: "title", type: "heading", text: "Deploy ready" }],
});

const answer = await dopl.ask("usr_123", { question: "Ship it?", options: ["Yes", "No"] });
if (answer.status === "answered") console.log(answer.answer);
// { simulated: true, index: 0, label: "Yes" }

A simulated device answers every question at once and always picks the first option, so tests are deterministic. A real user can take up to 200 seconds, and ask waits that long by default.

6. Read the action

Every delivery is stored as an action. Read its status and result at any time with the delivery_id.

const action = await dopl.actions.get(sent.delivery_id);

console.log(action.status, action.result); // done { simulated: true }

7. See your calls in the log

Every call is one event, and its event_id equals the Request-Id header of the response. Open Request log in the portal, or read the log from code with a key that has the analytics:read scope.

const page = await dopl.events.list({ limit: 10, outcome: "error" });
for (const event of page.data) console.log(event.ts, event.capability, event.error_code);

if (page.has_more) {
  const older = await dopl.events.list({ limit: 10, outcome: "error", cursor: page.next_cursor! });
}

Usage in the portal charts your calls and failed calls per hour or per day, for test and live separately.

Next, shape output per device with Context profiles and routing and force failure states with Test mode.