ページの一覧

ドキュメント

連携

会話中の AI に、Google カレンダー・Microsoft 365 のカレンダー・Google スプレッドシート・kintone を読み書きさせ、会話のあとに Slack・Chatwork・LINE WORKS・Microsoft Teams へ要約を知らせる連携(コネクター)の使い方。テナントごと・環境ごとの連携のしかた、埋め込みの連携の画面、エージェント設定での使い方。

Markdown で見る

連携(コネクター)を使うと、会話中の AI がほかのサービスを読み書きします。AI が予約の空きを探して予約を入れたり、電話番号で台帳から前の記録を探して聞き取った内容を記録したりします。会話のあとには、要約をチャットに知らせます。自社で API を作る必要はありません。

自社やほかの会社の API を呼ぶときは、エージェントのツールを使います。ほかの会社の API を呼ぶカスタムの連携(URL と API キー)は、ツールに置き換わりました。ツールの署名なしの呼び出し(sign: false)と API キーで、ほかの会社の API を直接呼べます。作成済みのカスタムの連携は、そのまま動きます。

使える連携先#

コネクター 名前 連携の方法 AI が使える操作
google_calendar Google カレンダー Google のアカウントでログイン find_free_slots・create_event・cancel_event・find_events_by_phone_or_name
m365_calendar Microsoft 365 のカレンダー Microsoft 365 の職場のアカウントでログイン find_free_slots・create_event・cancel_event・find_events_by_phone_or_name
google_sheets Google スプレッドシート Google のアカウントでログイン find_row_by_phone・append_row
kintone kintone お客さまの cybozu.com で登録した OAuth クライアントでログイン find_record_by_phone・create_record・update_record
slack Slack お客さまのワークスペースで作った Incoming Webhook の URL を貼る 会話のあとに知らせる
chatwork Chatwork お客さまの API トークンを貼る 会話のあとに知らせる
lineworks LINE WORKS お客さまの Developer Console で作ったアプリと Bot でログイン 会話のあとに知らせる
teams Microsoft Teams Workflows の Webhook の URL を貼る 会話のあとに知らせる
http URL と API キー POST /v1/connections 設定したツール(10 個まで)

ログインで連携する連携先は、管理画面の[連携]か埋め込みの連携の画面から連携します。GET /v1/connectors(MCP は list_connectors)で、使える連携先・操作の説明・AI に見せるツールの名前(sheets_append_row など)・連携の前に入力する項目を確認できます。

リモートの MCP サーバーを会話中の AI につなぐ連携は提供していません。設定した人のアカウントでログインしたトークンで、その環境のすべての会話から MCP サーバーを呼び出す作りになるためです。MCP サーバーの機能を会話で使うときは、相手の API を会話中のツールで呼び出してください(署名なしのツールと API キーで、ほかの会社の API も直接呼べます)。

準備中の連携先#

HubSpot は、準備が済むと連携先の一覧(GET /v1/connectors)に出ます。出るまでは、エージェント設定の connectors に指定すると 422 です。

連携の持ち方#

プリセットの連携は、2 通りの持ち方ができます。

持ち方 使いどころ 連携のしかた
テナントの連携 事業者(テナント)ごとに、自分のカレンダーや台帳を使う 事業者が埋め込みの連携の画面を開いて連携する。リンクは管理画面のテナントの編集画面の[設定用のリンクを発行]か、POST /v1/tenants/{id}/connect-links で発行する
環境の連携 サービス全体で 1 つのカレンダーや台帳を使う 管理画面の左のメニューの[連携]で連携する

会話のときは、テナントの連携を先に使います。テナントの連携があれば(もう一度連携が必要な状態でも)、環境の連携には切り替えません。テナントの連携は GET /v1/tenants/{id}/connections で確認できます。

認証の情報(OAuth のトークン・API キー)は voicast が暗号化して保管します。API の応答や音声サーバーには出しません。

Google スプレッドシート#

連携する#

  1. 管理画面の[連携](環境の連携)か、埋め込みの連携の画面(テナントの連携)で、Google スプレッドシートの[連携]を押します。
  2. Google のアカウントでログインし、許可します。許可の画面の項目はすべてチェックを入れたままにしてください。外すと連携できません。
  3. 連携すると、voicast がその Google ドライブに台帳のスプレッドシート「AI 電話応対の台帳」を作成します。シート「台帳」の 1 行目に、見出し(受付日時・電話番号・お名前・用件)が入ります。
  4. 続けて開く設定の画面で、台帳のスプレッドシート・シートと、電話番号・名前・用件・受付日時の列を選択して保存すると、使える状態(active)になります。保存するまでは設定待ち(needs_setup)で、AI には渡りません。
  • Google のアクセス権は drive.file だけです。voicast が作成したスプレッドシートのほかは読み書きしません(Google ドライブのほかのファイルは見えません)。今お使いの台帳は、作成したスプレッドシートに貼り付けて使ってください。
  • 電話番号は文字のまま書き込みます(先頭の 0 を残します)。
  • シートの名前を変えたり、シートを消したりしたら、設定でシートを選び直してください。選び直すまで、AI には not_configured が返ります。電話番号の列の見出しが無いときも not_configured です。
  • API では、設定の選択肢を GET /v1/connections/{id}/options(?spreadsheet= と ?sheet= で絞る)で取得し、PATCH /v1/connections/{id} の config(spreadsheet_id・spreadsheet_name・sheet・phone_column・name_column・note_column・date_column)で保存します。

操作#

操作 AI に見せる名前 内容
find_row_by_phone sheets_find_row_by_phone 電話番号で台帳の行を探します(先頭から 2,000 行まで読み、5 件まで返します)。電話の会話では、番号を省くとかけてきた番号で探します
append_row sheets_append_row 受付日時・電話番号・名前・用件の行を足します。確認してから使う操作です(外せません)

AI の使い方#

エージェント設定に操作を付けると、AI の役割(persona)に書かなくても、AI は次のように使います。

  • find_row_by_phone: 電話番号を伺って復唱で確かめたら台帳を探し、前の記録が見つかれば、前回の用件などに一言触れます。台帳にあるお名前は聞き直さず、確かめるだけにします。
  • append_row: 聞き取りが終わったら記録します。記録の前に、voicast が決まった文(「〇〇様のご用件として、〜を承ってよろしいでしょうか」)で相手の同意を伺い、記録したら「ご用件を承りました」と伝えてから、会話を終えます。用件の欄には、用件と、聞き取ったほかの項目(希望の日時など)を短くまとめて入れます。
  • 記録せずに会話を終えるのは、相手が記録を断ったときだけです。質問に答えただけで終える会話と、担当者に転送する会話は記録しません。記録が失敗したときは、おわびして担当者からの折り返しを伝えます。
  • 台帳への記録は、予約などが済んだことではありません。締めのあいさつは、エージェント設定の closing のままです。

Google カレンダー#

連携する#

  1. [連携]を押し、Google のアカウントでログインして許可します。許可の画面の項目はすべてチェックを入れたままにしてください。外すと連携できません。
  2. 続けて開く設定の画面で、予約を入れるカレンダー(書き込めるものだけ出ます)・受付の時間(曜日ごとに 4 つまで)・予約の長さ・前後の余白を選んで保存すると、使える状態(active)になります。
  3. API では、GET /v1/connections/{id}/options で { calendars: { id, name, primary }[] } を取得し、PATCH /v1/connections/{id} の config(calendar_id・calendar_name・hours・duration_minutes・buffer_minutes・title_template)で保存します。hours は { "mon": [["09:00", "12:30"], ["14:00", "18:00"]], "sun": [] } の形です。
  • 予定の題名は title_template(既定「予約({name})」)です。用件はメモにだけ入れます。予定を作っても、参加者への通知は送りません。
  • 祝日は見ません。休みの日は、カレンダーに終日の予定を入れて埋めてください。

操作#

操作 AI に見せる名前 内容
find_free_slots gcal_find_free_slots 受付の時間の中で、埋まっていない枠を探します(14 日まで、8 件まで)
create_event gcal_create_event 予約の予定を作ります。確認してから使う操作です
cancel_event gcal_cancel_event 予約の予定を取り消します。確認してから使う操作です
find_events_by_phone_or_name gcal_find_events_by_phone_or_name 電話番号(作った予定に残す番号)か名前で、これからの予約を 5 件まで探します

AI は、希望の日を伺うと空きを探して候補を伝え、日時とお名前がそろったら予約の操作を呼びます。予約を入れる前に、voicast が決まった文(「10月19日月曜日の午後2時に、冷蔵庫の修理で、こばやし まこと様のご予約をお取りしてよろしいでしょうか」)で相手の同意を伺い、入れたら「ご予約をお取りしました。10月19日月曜日の午後2時です」と伝えます。名前は、聞こえた読み(name_kana)で言います。取り消しも同じく、探した予約の日時を読み上げて同意を伺います。予約の変更は、1 回の確認(「〜のご予約を、〇時から〇時に変更してよろしいでしょうか」)で、新しい予約を入れてから前の予約を取り消します。

Microsoft 365 のカレンダー#

連携する#

  1. [連携]を押し、Microsoft 365 の職場のアカウントでログインして許可します。個人の Microsoft アカウント(Outlook.com など)ではつなげません。組織の設定によっては、組織の管理者の承認が必要です。
  2. 続けて開く設定の画面で、予約を入れるカレンダー(書き込めるものだけ出ます)・受付の時間・予約の長さ・前後の余白を選んで保存すると、使える状態(active)になります。設定の項目と API(GET /v1/connections/{id}/options・PATCH /v1/connections/{id} の config)は、Google カレンダーと同じです。
  • 予定の題名・メモ・参加者への通知・祝日の扱いは、Google カレンダーと同じです。
  • 連携を解除すると、voicast が預かったトークンを消します。Microsoft のアカウントの[アプリとサービス]からも voicast を外してください。

操作#

操作 AI に見せる名前 内容
find_free_slots m365_find_free_slots 受付の時間の中で、埋まっていない枠を探します(14 日まで、8 件まで)
create_event m365_create_event 予約の予定を作ります。確認してから使う操作です
cancel_event m365_cancel_event 予約の予定を取り消します。確認してから使う操作です
find_events_by_phone_or_name m365_find_events_by_phone_or_name 電話番号(作った予定に残す番号)か名前で、これからの予約を 5 件まで探します

AI の使い方(空きの伝え方・予約と取り消しの確認)は、Google カレンダーと同じです。

kintone#

連携する#

kintone の OAuth クライアントは、お客さまの cybozu.com の共通管理者が登録します。

  1. cybozu.com 共通管理の「外部連携」で OAuth クライアントを追加します。リダイレクトエンドポイントは https://app.voicast.jp/api/connectors/callback です。追加したら、使う人の利用を許可します。
  2. [連携]を押し、サブドメイン(〇〇.cybozu.com の 〇〇)・クライアント ID・クライアントシークレットを入力して、kintone にログインして許可します。
  3. 設定の画面で、アプリと、電話番号・名前・用件の項目(文字列・リンク・文字列(複数行))を選んで保存します。API では GET /v1/connections/{id}/options(?app= で項目を絞る)と、PATCH の config(app_id・app_name・phone_field・name_field・note_field)です。

操作#

操作 AI に見せる名前 内容
find_record_by_phone kintone_find_record_by_phone 電話番号でレコードを 5 件まで探します(ハイフンの有無を問いません)
create_record kintone_create_record 電話番号・名前・用件のレコードを作ります。確認してから使う操作です
update_record kintone_update_record 見つけたレコードの名前・用件を直します。確認してから使う操作です

AI に渡すのは、設定で選んだ項目の値だけです。

会話のあとの通知#

会話が終わると、結果・要約・聞き取った項目・管理画面へのリンクを知らせます。エージェント設定では { "connector": "teams" } のように、actions を書かずに並べます。

Slack・Chatwork・Microsoft Teams への通知は、voicast が送ります。届いたか・何度試したかは、会話記録の詳細の[Webhook の送信]に「Slack への通知」のように出ます(API は GET /v1/calls/{id}/webhooks の event_type が voicast.notify の行。connector に連携先が入ります)。一時的な失敗は送り直します。送り先が受け付けなくなった(Webhook の削除・トークンの無効・ルームから外れたなど)ときは、連携が needs_reauth になり、理由が連携の config.notify_error に入ります。URL やトークンを貼り直すと戻ります。

Slack#

  1. Slack の api.slack.com/apps で[Create New App]→[From scratch]を選び、通知を送るワークスペースにアプリを作ります。アプリはお客さまのワークスペースのもので、ほかの会社のアプリを入れる必要はありません。
  2. アプリの[Incoming Webhooks]をオンにし、[Add New Webhook]で通知するチャンネルを選びます。
  3. 表示された Webhook URL(https://hooks.slack.com/services/…)を、[連携]で貼って保存します(API は POST /v1/connections に { "connector": "slack", "secret": "<URL>" })。保存の前に、確認の通知を 1 回送ります。届かない URL は 422 verify_failed です。

Chatwork#

  1. Chatwork で、右上の利用者名 →[サービス連携]→ 左のメニューの[API トークン]を開き、API トークンを表示します。パーソナルプラン以外は、API を使うのに組織の管理者への申請(承認)が要ります(Chatwork の申請のページ)。
  2. [連携]で、API トークンを貼って保存します(API は POST /v1/connections に { "connector": "chatwork", "secret": "<API トークン>" })。保存の前に、トークンで Chatwork のアカウントを確認します。トークンが違うと 422 verify_failed です。
  3. 続けて開く設定の画面で、通知を送るルームを選んで保存します(閲覧だけのルームは出ません。API では GET /v1/connections/{id}/options の { rooms } と、config の room_id・room_name)。
  • 通知は、API トークンの持ち主の名前でルームに投稿されます。通知用のアカウントを作ってトークンを出すと、ほかの人の名前で投稿されません。
  • API トークンを作り直した・ルームから外れたときは、通知が届かなくなります(送り直しません)。新しいトークンを貼り直すと、選んだルームのまま戻ります。

LINE WORKS#

  1. お客さまの LINE WORKS の Developer Console でアプリを作ります。Redirect URL は https://app.voicast.jp/api/connectors/callback、OAuth Scopes は bot と user.read です。トークンの設定の Refresh Token Rotation は ON にしてください。
  2. Bot を作ってテナントに追加し、通知を受け取るメンバーが使えるようにします。
  3. [連携]を押し、アプリのクライアント ID・クライアントシークレットと Bot ID を入力して、ログインして許可します。
  4. 設定の画面で、通知を受け取るメンバーを選んで保存します(API では config の user_id・user_name)。

本文は 2,000 字までに収めます。

Microsoft Teams#

  1. Teams の Workflows で「Webhook 要求を受信したらチャネルに投稿する」のフローを作り、フローを起動できるユーザーを「すべてのユーザー」にします。
  2. [連携]で、フローの URL を貼って保存します(API は POST /v1/connections に { "connector": "teams", "secret": "<URL>" })。保存の前に、確認の通知を 1 回送ります。

旧 Office 365 コネクター(Incoming Webhook)の URL は使えません。

エージェント設定に書く#

連携を AI に使わせるには、エージェント設定の connectors に並べます。管理画面では、エージェント設定の[連携]で連携先を選び、使う操作を選択します。

json
"connectors": [
  { "connector": "google_calendar", "actions": ["find_free_slots", "find_events_by_phone_or_name"], "confirm": ["create_event", "cancel_event"] },
  { "connector": "google_sheets", "actions": ["find_row_by_phone", "append_row"] },
  { "connector": "teams" },
  { "connection": "con_…", "actions": ["find_customer"] }
]
項目 内容
connector プリセットの名前(google_calendar など)。テナントの連携を使い、無ければ環境の連携を使います
connection 決まった連携の ID(con_…)。カスタムの連携(URL と API キー)はこちらで指定します
actions AI に使わせる操作の名前(カスタムの連携は、連携の設定のツールの name)。通知だけの連携先には書きません
confirm 相手に確認してから使う操作を追加する。actions に無い名前を書くと、actions にも足して保存します
  • 書き換える操作(append_row など)と、連携の設定で「確認してから使う」にしたツールは、確認の文で相手の同意をいただいてから使い、結果も決まった文で伝えます(プリセットの書き換える操作は、確認を外せません)。決まった文の内容は会話中のツールを見てください。
  • 確認してから使うツールがあるとき、相手が予約・変更・取り消しを望んでいれば、そのツールを使うまで会話を終えません。失敗したら「申し訳ございません、ご予約はまだ確定しておりません。担当者から折り返しご連絡いたします」と伝えます(空きが埋まっていたなど相手が直せる失敗は、ほかの日時などを伺います)。
  • 確認してから使うツールの最後の結果が成功なら、予約でも取り消しでも、エージェント設定の closing の代わりに短いお礼のあいさつで締めます(済んだことは voicast がその前に伝えます)。最後の結果が失敗のとき・使わなかったときは closing で締めます。読み取りのツールの失敗と、台帳への記録(append_row)は数えません。
  • 確認してから使うツールを、1 つの会話で同じ内容(同じ引数)で 2 度は呼びません。2 度目は 1 度目の結果を返します。
  • AI に渡すのは、actions に名前を並べた操作だけです。あとから操作やツールが増えても、名前を並べるまで AI には渡りません。
  • actions に "*"(すべて)は使えません(422 invalid_config)。前に "*" で保存した設定は、移行した時点の操作の名前の一覧に置き換えています。
  • 使える状態(active)の連携の操作だけが、会話のときに AI に渡ります。
  • 同じ連携先は 1 回だけ、connectors は 10 個までです。AI に見せるツールの名前(sheets_append_row・api1_find_customer など)が tools の名前と重なると 422 です。

埋め込みの連携の画面#

事業者(テナント)が、自分のアカウントでカレンダーや台帳を連携する画面です。voicast の名前は出さないので、サービスの画面の一部として見せられます。

リンクの発行#

管理画面では、テナントの編集画面の[設定用のリンクを発行]で発行します。API では次のとおりです(MCP は create_connect_link)。

bash
curl https://api.voicast.jp/v1/tenants/ten_…/connect-links \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectors": ["google_sheets"], "frame_origin": "https://app.example.com" }'
json
{ "url": "https://app.voicast.jp/connect/vcl_…", "expires_at": 1790000900000 }
入力 内容
connectors 画面に出す連携先(省くと、使える連携先のすべて)。カスタムの連携は出せません
frame_origin iframe で埋め込む親のオリジン(https)。新しいタブで開くときは不要です
  • リンクの有効期限は 15 分です。事業者が設定の画面を開くたびに、サーバーで発行し直してください。
  • 言語は url に ?lang=ja か ?lang=en を付けて選べます(無ければブラウザの言語)。
  • ログインは不要です。リンクのトークンで、そのテナントの連携だけを扱えます。

埋め込み#

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

[連携]を押すと、連携先のログインの画面が小さな別のウィンドウで開きます(多くの連携先は iframe の中にログインの画面を出せないため)。ログインが終わると、同じ画面でカレンダーや台帳の設定を選択します。設定が済むまでは needs_setup で、AI には渡りません。連携の結果は GET /v1/tenants/{id}/connections で確認できます。

カスタムの連携#

カスタムの連携は環境の連携です。1 つの環境に、いくつでも追加できます。tenant_id を付けて作成すると 422 invalid_request です。テナントごとの振り分けは、呼び出しに付くテナントの external_id で行います。エージェント設定では { "connection": "con_…", "actions": [...] } で指定し、AI に見せるツールの名前には連携ごとの接頭辞(api1_…・api2_…)が付きます。

URL と API キー(http)#

自社やほかの会社の REST API を、URL と API キーで呼び出します。

bash
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 など)ならキーをそのまま付けます。
  • 認証の要らない API でも、ヘッダーの名前と API キーは入力が必要です。相手が使わないヘッダー(例:X-API-Key に任意の文字列)を入力してください。
  • 保存の前に確認するのは、URL とヘッダーの名前の形だけです(API は呼び出しません)。
  • 保存すると設定待ち(needs_setup)になり、ツール(10 個まで)を PATCH /v1/connections/{id} で保存すると使えます。
json
{
  "config": {
    "tools": [
      {
        "name": "find_customer",
        "description": "電話番号で顧客を探す",
        "method": "GET",
        "path": "/customers/search",
        "params": [{ "name": "phone", "description": "電話番号(数字だけ)", "required": true }],
        "confirm": false
      }
    ]
  }
}
  • 確認してから使う(confirm: true)ツールには、確認の文(confirm_message)と完了の文(done_message)を付けられます(200 文字まで、{引数の名前} に値を差し込む。会話中のツールと同じ)。
  • 引数はいつも文字列で、GET はクエリ、POST は JSON の本文で送ります(10 個まで)。path は連携した URL の下だけです。
  • 呼び出しには idempotency-key(会話と呼び出しごとに決まる値)が付きます。
  • 応答は JSON ならそのまま、ほかは文字で AI に渡します(長い文字は切ります)。
  • 誤りの応答は、AI に次の種類で渡します。AI は相手に、確認して折り返すなどと伝えます。
相手の応答 AI に渡す error
401・403 unauthorized(API キーを確認してください)
404 not_found
ほかの 2xx 以外(3xx・429・5xx など) upstream_error
3 秒以内に応答が無い timeout
必須の引数が無い invalid_arguments

呼び出せる URL#

連携から呼び出す URL は https だけです。IP アドレスの直書き・localhost・.local・.internal・点の無い名前・ユーザー名とパスワード入りの URL は受け付けません。別の URL へ移す応答(3xx)には付いて行きません。

連携の状態#

status 内容
active 使える
needs_setup 連携したが、設定(カレンダーや台帳の選択・通知先の選択・ツールの保存など)がまだ。AI には渡らない
needs_reauth ログインで連携する連携先で、トークンが失効した。もう一度ログインが必要。Slack・Chatwork・Microsoft Teams は、通知の送り先が受け付けなくなった(理由は config.notify_error)。URL やトークンの貼り直しが必要

会話の無い期間が長くても、連携は切れません。voicast が毎日、しばらく使われていない連携のトークンを更新します。

連携先のアカウントで許可を取り消した・パスワードを変えたなどで更新できなくなると needs_reauth になり、Webhook の connection.needs_reauth が届きます(1 回だけ)。テナントの連携なら tenant が付くので、その事業者に新しい連携の画面のリンクを出して、連携し直してもらいます。

テナントを削除すると、そのテナントの連携も解除します。連携を解除する(DELETE /v1/connections/{id})と、連携先のトークンも取り消します(取り消しの API の無い Microsoft 365・kintone・Slack・Chatwork・Microsoft Teams は、voicast が預かったトークンや URL を消します)。