handset

Handset UI

午後のうちに、製品にテキストメッセージ機能を組み込めます。

組み込み型メッセージング向けのオープンソース React コンポーネントです。 Handset API を基盤としています。shadcn 方式で配布します。CLI がソースコードをリポジトリにコピーし、Tailwind トークンでスタイルを設定します。自由に変更できます。

# 1. Point the shadcn CLI at the Handset registry
npx shadcn@latest registry add @handset=https://ui.handset.dev/r/{name}.json

# 2. Install a complete texting surface + the server proxy route
npx shadcn@latest add @handset/messaging @handset/next-routes

環境変数に HANDSET_API_KEY を設定し、生成されたルートの resolveTenantId() をセッションに接続して、次のようにレンダリングします。

import { HandsetProvider } from "@handset/react";
import { Messaging } from "@/components/handset/messaging";

export default function MessagesPage() {
  return (
    <HandsetProvider>
      <div className="h-[600px]">
        <Messaging />
      </div>
    </HandsetProvider>
  );
}

レジストリに含まれるもの

項目	内容
@handset/messaging	2ペインのテキストメッセージ画面 — モバイルにも対応した受信トレイ＋スレッド
@handset/inbox	会話リスト：プレビュー、相対時刻、STOP バッジ、無限スクロール
@handset/thread	メッセージ履歴：配信状態、オプトアウト処理、接続済みのメッセージ作成欄
@handset/composer	SMS セグメント数のリアルタイム表示と Unicode 検出に対応した下書きボックス
@handset/next-routes	Next.js プロキシルート — API キーがブラウザーに渡ることはありません

アーキテクチャ

shadcn と Radix の組み合わせのように、2つのレイヤーで構成されています。

• @handset/react（npm、バージョン管理あり）— ヘッドレスフック： useConversations、useThread、useComposer に加え、セグメント計算と小さな クライアントを提供します。ロジックは当社が保守します。必要に応じて、お好みの UI をご用意ください。
• レジストリ（apps/www/registry）— ビジュアル コンポーネントをソースコードとしてプロジェクトにコピーします。

コンポーネントが API キーを保持することはありません。お客様のバックエンドにあるプロキシルート（@handset/next-routes が追加）を呼び出します。サーバーが Handset キーを保持し、既存のセッション認証によって、サインインした各ユーザーがどのテナントを表示できるかを決定します。残りの処理は Handset API が担います。電話番号、配信、スレッド化、10DLC 準拠、STOP／HELP などに対応しています。

開発

pnpm install
pnpm --filter @handset/react build   # hooks package
pnpm dev                             # docs site + live demo at localhost:3000
pnpm registry:build                  # compile registry.json → public/r/*.json

ドキュメントサイトはモック Handset API（apps/www/app/api/handset）を提供しているため、セットアップ不要でデモを動作させられます。

要件

• React 18 以降（コンポーネントは React 19／Tailwind v4／shadcn CLI ≥ 3 を対象としています）
• 実際のトラフィックには Handset のアカウントが必要です — デモはアカウントなしでもモックデータで動作します

ロードマップ

ROADMAP.md をご覧ください — リリース済みのコンポーネント、今後の予定（通話の要約、MMS 添付ファイル、各種フレームワーク向けプロキシ）、および対象外の項目を掲載しています。実際のユースケースを伴う Issue は、項目の優先順位を上げる参考になります。

ライセンス

MIT © Handset HQ, Inc.