English Français العربية

io.github.handset-hq/handset

Registre officiel Médias et design

A business phone system for AI agents: send texts, place calls, read transcripts, buy numbers.

Code source Site web Documentation

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

NPM package @handset/mcp
Claude Code 
claude mcp add handset -e 'HANDSET_API_KEY=<your handset_api_key>' -e 'HANDSET_ALLOW_LIVE=<HANDSET_ALLOW_LIVE>' -- npx -y @handset/mcp@0.1.1
Configuration JSON (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "handset": {
            "command": "npx",
            "args": [
                "-y",
                "@handset/mcp@0.1.1"
            ],
            "env": {
                "HANDSET_API_KEY": "<your handset_api_key>",
                "HANDSET_ALLOW_LIVE": "<HANDSET_ALLOW_LIVE>"
            }
        }
    }
}

Variables d'environnement

  • HANDSET_API_KEY obligatoire secret Handset API key. Use a test-mode key (hs_test_…) — simulated carrier, free. Live keys are refused unless HANDSET_ALLOW_LIVE=1.
  • HANDSET_ALLOW_LIVE Set to 1 to permit a live-mode key (the agent can then text and call real people at real cost).

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. Handset UI
  2. What's in the registry
  3. Architecture
  4. Development
  5. Requirements
  6. Roadmap
  7. License

Handset UI

Texting inside your product, in an afternoon.

Open-source React components for embedded messaging, built on the Handset API. Distributed the shadcn way: the CLI copies the source into your repo, styled with your Tailwind tokens, yours to change.

# 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

Set HANDSET_API_KEY in your env, wire resolveTenantId() in the generated route to your session, and render it:

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

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

What's in the registry

ItemWhat it is
@handset/messagingTwo-pane texting surface — inbox + thread, responsive to mobile
@handset/inboxConversation list: previews, relative times, STOP badges, infinite scroll
@handset/threadMessage history: delivery states, opt-out handling, wired composer
@handset/composerDraft box with live SMS segment counting and unicode detection
@handset/next-routesNext.js proxy route — your API key never reaches the browser

Architecture

Two layers, like shadcn-on-Radix:

  • @handset/react (npm, versioned) — headless hooks: useConversations, useThread, useComposer, plus segment math and a tiny client. Logic we maintain; bring your own UI if you prefer.
  • The registry (apps/www/registry) — the visual components, copied into your project as source.

Components never hold API keys. They call proxy routes in your backend (added by @handset/next-routes); your server holds the Handset key and your existing session auth decides which tenant each signed-in user sees. The Handset API handles the rest — numbers, delivery, threading, 10DLC compliance, STOP/HELP.

Development

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

The docs site serves a mock Handset API (apps/www/app/api/handset) so the demo works with zero setup.

Requirements

  • React 18+ (components target React 19 / Tailwind v4 / shadcn CLI ≥ 3)
  • A Handset account for real traffic — the demo runs on mock data without one

Roadmap

See ROADMAP.md — shipped components, what's next (call summaries, MMS attachments, more framework proxies), and non-goals. Issues with real use cases move items up the list.

License

MIT © Handset HQ, Inc.

Questions fréquentes

Qu'est-ce que io.github.handset-hq/handset ?

A business phone system for AI agents: send texts, place calls, read transcripts, buy numbers.

Comment installer io.github.handset-hq/handset ?

Il s'exécute sur votre machine. Dans Claude Code : claude mcp add handset -e 'HANDSET_API_KEY=<your handset_api_key>' -e 'HANDSET_ALLOW_LIVE=<HANDSET_ALLOW_LIVE>' -- npx -y @handset/mcp@0.1.1. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour io.github.handset-hq/handset ?

Oui. Il attend HANDSET_API_KEY, à renseigner dans sa configuration.

io.github.handset-hq/handset est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient io.github.handset-hq/handset ?

Il est publié par handset-hq. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.