連携

連携（コネクター）を使うと、通話中の AI が Google カレンダーの空きを調べて予約を入れたり、kintone で電話番号から顧客を探したりできます。通話のあとには、要約と聞き取った項目を Slack や Teams に知らせます。通話中の道具と違い、自社で API を作らずに使えます。

連携の持ち方#

連携は 2 通りの持ち方ができます。

通話のときは、テナントの連携を先に使います。テナントの連携があれば（もう一度連携が要る状態でも）、環境の連携には切り替えません。

鍵（OAuth のトークン・API キー・Webhook の URL）は voicast が暗号化して持ちます。API の応答や音声サーバーには出しません。

プリセット#

GET /v1/connectors（MCP は list_connectors）で、操作の説明・つなぐ前に聞く項目・AI に見せる道具の名前（gcal_find_free_slots など）を確かめられます。available: false の連携先は、まだ使えません。

操作の中身#

• Google カレンダー・Microsoft 365: find_free_slots { date_from, date_to?, duration_minutes? } は、受付の時間・前後の余白・埋まっている時間を考えて空きを 8 件まで返します（14 日先まで）。create_event { start, name, phone?, note?, duration_minutes? }・cancel_event { event_id }・find_events_by_phone_or_name { phone?, name? }（電話番号を省くと、かけてきた番号）。つないだあとに、使うカレンダー・予約の長さ（5〜480 分、既定 30）・前後の余白・曜日ごとの受付の時間・予定の題名を決めます。予定の題名には病名などを入れず、用件は予定のメモにだけ入れます。
• Google スプレッドシート: find_row_by_phone { phone? }・append_row { name?, phone?, note? }。使う表と、電話番号・名前・メモ・日時の列を決めます。
• kintone: find_record_by_phone { phone? }・create_record { name?, phone?, note? }・update_record { record_id, name?, note? }。使うアプリと、電話番号・名前・メモのフィールドを決めます。
• HubSpot: find_contact_by_phone { phone? }・create_contact { name, phone? }・log_call { summary, contact_id? }（受けた電話として記録します）。
• 通知（Slack・Chatwork・LINE WORKS・Teams）: 通話のあと（要約ができたあと）に、要約・用件の分類・聞き取った項目・管理画面へのリンクを送ります。失敗した通知は送り直し、ほかの通知は止めません。

会話の設定に書く#

連携を AI に使わせるには、会話の設定の connectors に並べます。

"connectors": [
  { "connector": "google_calendar", "actions": ["find_free_slots", "create_event", "cancel_event"] },
  { "connector": "slack" },
  { "connection": "con_…", "actions": ["*"] }
]

• 予約を作る・取り消すなど書き換える操作は、いつも内容を読み上げて相手の同意を得てから使います（外せません）。
• 使える状態（active）の連携の操作だけが、通話のときに AI に渡ります。
• 同じ連携先は 1 回だけ、connectors は 10 個までです。AI に見せる道具の名前（gcal_create_event など）が tools の名前と重なると 422 です。

埋め込みの連携の画面#

事業者（テナント）が自分の Google カレンダーや Slack をつなぐ画面です。voicast の名前は出さないので、サービスの画面の一部として見せられます。

リンクの作り方#

curl https://api.voicast.jp/v1/tenants/ten_…/connect-links \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectors": ["google_calendar", "slack"], "frame_origin": "https://app.example.com" }'

{ "url": "https://app.voicast.jp/connect/vcl_…", "expires_at": 1790000900000 }

• リンクは 15 分で切れます。事業者が設定の画面を開くたびに、サーバーで作り直します。
• 言語は url に ?lang=ja か ?lang=en を付けて選べます（無ければブラウザの言語）。
• ログインは要りません。リンクのトークンで、そのテナントの連携だけを扱えます。

埋め込み#

<iframe src="https://app.voicast.jp/connect/vcl_…?lang=ja" title="連携" style="width: 100%; height: 720px; border: 0"></iframe>

「連携する」を押すと、連携先のログインの画面が小さな別の窓で開きます（Google などは iframe の中にログインの画面を出せないため）。終わると、元の画面に postMessage で知らせます。

window.addEventListener('message', (e) => {
  if (e.origin !== 'https://app.voicast.jp' || e.data?.type !== 'voicast.connect') return;
  // { type: 'voicast.connect', result: 'ok' | 'error', error, connector, connection }
  if (e.data.result === 'ok') refreshConnections();
});

Google カレンダーなど設定の要る連携先は、つないだあとに同じ画面で、使うカレンダーや受付の時間を選びます。設定が済むまでは needs_setup で、AI には渡りません。

API キーや URL でつなぐ連携先#

Teams・シャノンの予約システム・カスタムの「URL と API キー」は、POST /v1/connections でつなげます。保存の前に 1 回試しに呼び、失敗すると 422 verify_failed です。

curl https://api.voicast.jp/v1/connections \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connector": "teams", "tenant_id": "ten_…", "secret": "https://….logic.azure.com/workflows/…" }'

カスタムの連携#

プリセットに無い相手は、管理画面の「連携」→「＋ API でつなぐ」でつなぎます。環境の連携だけで、いくつでもつなげます（シャノンの予約システムも環境の連携だけです。tenant_id を付けてつなごうとすると 422 invalid_request になります。テナントごとの振り分けは、呼び出しに付く tenant（external_id）で行います）。会話の設定では { "connection": "con_…", "actions": [...] } で指定し、AI に見せる道具の名前には連携ごとの頭（mcp1_…・api2_…）が付きます。

URL と API キー（http）#

自社や他社の REST API を、URL と API キーで呼びます。

curl https://api.voicast.jp/v1/connections \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connector": "http", "secret": "<API キー>", "input": { "base_url": "https://api.example.com", "header": "Authorization" } }'

• header が Authorization なら Bearer <キー> を、ほかの見出し（X-API-Key など）ならキーをそのまま付けます。
• 保存すると設定待ちになり、道具（10 個まで）を PATCH /v1/connections/{id} で保存すると使えます。

{
  "config": {
    "tools": [
      {
        "name": "find_customer",
        "description": "電話番号で顧客を探す",
        "method": "GET",
        "path": "/customers/search",
        "params": [{ "name": "phone", "description": "電話番号（数字だけ）", "required": true }],
        "confirm": false
      }
    ]
  }
}

• 引数はいつも文字列で、GET はクエリ、POST は JSON の本文で送ります（10 個まで）。path はつないだ URL の下だけです。
• 呼び出しには idempotency-key（通話と呼び出しごとに決まる値）が付きます。
• 応答は JSON ならそのまま、ほかは文字で AI に渡します（長い文字は切ります）。

MCP サーバー（mcp）#

リモートの MCP サーバー（Streamable HTTP）で、MCP の認可（OAuth）に対応したものをつなげます。管理画面で URL を入れると、相手のログインの画面が開きます。つないだあと、AI に使わせる道具と「確認してから使う」を選びます（読むだけと宣言された道具のほかは、既定で確認します）。

• ログインなしで使えるサーバー・手元（ローカル）の MCP サーバーはつなげません。
• 引数に文字列・数・真偽のほかの形が必須の道具は選べません。

呼んでよい URL#

連携から呼ぶ URL（MCP サーバー・HTTP・予約システム・Teams）は https だけです。IP アドレスの直書き・localhost・.local・.internal・点の無い名前・利用者名とパスワード入りの URL は受けません。別の URL へ移す応答（3xx）には付いて行きません。

連携の状態#

連携が切れると、Webhook の connection.needs_reauth が届きます。テナントの連携なら tenant が付くので、その事業者に新しい連携の画面のリンクを出して、つなぎ直してもらいます。

テナントを消すと、そのテナントの連携も取り消します。連携を解除する（DELETE /v1/connections/{id}）と、連携先のトークンも取り消します。