Docs › Get started

Your first five minutes

You just received your Handset keys. This page gets you from "key in hand" to "message on screen" in five steps — all in test mode, where the carrier is simulated and everything is free and instant.

1. Stash your test key

Use the test key (hs_test_…) for everything today. It behaves exactly like live — same API, same webhooks — against a simulated carrier.

export HANDSET_API_KEY="hs_test_…"

2. Install the SDK

npm install @handset/sdk   # or: pip install handset

3. Give yourself a phone system

A tenant is one of your customers; a number is their business line. In test mode numbers are free and live instantly:

import { client } from "@handset/sdk/client";
import { createTenant, searchAvailableNumbers, purchaseNumber } from "@handset/sdk";

client.setConfig({ headers: { Authorization: `Bearer ${process.env.HANDSET_API_KEY}` } });

const tenant = await createTenant({ body: { name: "My First Customer" } });
const found  = await searchAvailableNumbers({ query: { area_code: "415" } });
const number = await purchaseNumber({
  body: { tenant_id: tenant.data!.id, phone_number: found.data!.data[0].phone_number! },
});
console.log(number.data!.id);   // num_… — a working line, sms + voice

4. Send your first text

import { sendMessage } from "@handset/sdk";

const res = await sendMessage({
  body: { from: number.data!.id, to: "+14155550123", body: "Hello from my platform." },
});
console.log(res.data!.status);  // "queued" → simulated carrier delivers in ~1s

Fetch it again a second later and status is delivered. Try to: "+15005550001" to watch a delivery fail on purpose — rehearsing failure is the point of test mode.

5. See it in the console

Open console.handset.dev and log in with the same test key. The conversation you just created is there — threads, delivery states, usage. Your customers' phone activity, live.