連携
会話中の
連携
自社やsign: false)
使える連携先#
| コネクター | 名前 | 連携の |
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 | お客さまの |
find_record_by_phone・create_record・update_record |
slack |
Slack | お客さまの |
会話の |
chatwork |
Chatwork | お客さまの |
会話の |
lineworks |
LINE WORKS | お客さまの |
会話の |
teams |
Microsoft Teams | Workflows の |
会話の |
http |
URL と |
POST /v1/connections |
設定した |
ログインでGET /v1/connectorslist_connectors)sheets_append_row など)
リモートの
準備中の連携先#
HubSpot は、GET /v1/connectors)connectors に
連携の持ち方#
プリセットの
| 持ち方 | 使いどころ | 連携の |
|---|---|---|
| テナントの |
事業者 |
事業者が埋め込みのPOST /v1/tenants/{id}/connect-links で |
| 環境の |
サービス全体で |
管理画面の |
会話のGET /v1/tenants/{id}/connections で
認証の
Google スプレッドシート#
連携する#
- 管理画面の
[連携] (環境の 連携) か、 埋め込みの 連携の 画面 (テナントの 連携) で、 Google スプレッドシートの [連携]を 押します。 - Google の
アカウントで ログインし、 許可します。 許可の 画面の 項目は すべて チェックを 入れたままに してください。 外すと 連携できません。 - 連携すると、
voicast が その Google ドライブに 台帳の スプレッドシート 「AI 電話応対の 台帳」 を 作成します。 シート 「台帳」 の 1 行目に、 見出し (受付日時・電話番号・ お名前・用件) が 入ります。 - 続けて
開く 設定の 画面で、 台帳の スプレッドシート・シートと、 電話番号・名前・用件・受付日時の 列を 選択して 保存すると、 使える 状態 ( 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 |
電話番号で |
append_row |
sheets_append_row |
受付日時・電話番号・名前・用件の |
AI の使い方#
エージェント設定にpersona)
find_row_by_phone: 電話番号を伺って 復唱で 確かめたら 台帳を 探し、 前の 記録が 見つかれば、 前回の 用件などに 一言 触れます。 台帳に ある お名前は 聞き直さず、 確かめるだけに します。 append_row: 聞き取りが終わったら 記録します。 記録の 前に、 voicast が 決まった 文 ( 「〇〇様の ご用件と して、 〜を 承って よろしいでしょうか」 ) で 相手の 同意を 伺い、 記録したら 「ご用件を 承りました」 と 伝えてから、 会話を 終えます。 用件の 欄には、 用件と、 聞き取った ほかの 項目 (希望の 日時など) を 短く まとめて 入れます。 - 記録せずに
会話を 終えるのは、 相手が 記録を 断った ときだけです。 質問に 答えただけで 終える 会話と、 担当者に 転送する 会話は 記録しません。 記録が 失敗した ときは、 おわびして 担当者からの 折り返しを 伝えます。 - 台帳への
記録は、 予約などが 済んだ ことではありません。 締めの あいさつは、 エージェント設定の closingのままです。
Google カレンダー#
連携する#
- [連携]を
押し、 Google の アカウントで ログインして 許可します。 許可の 画面の 項目は すべて チェックを 入れたままに してください。 外すと 連携できません。 - 続けて
開く 設定の 画面で、 予約を 入れる カレンダー ( 書き込める ものだけ出ます) ・受付の 時間 (曜日ごとに 4 つまで) ・予約の 長さ・ 前後の 余白を 選んで 保存すると、 使える 状態 ( active)に なります。 - 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 |
受付の |
create_event |
gcal_create_event |
予約の |
cancel_event |
gcal_cancel_event |
予約の |
find_events_by_phone_or_name |
gcal_find_events_by_phone_or_name |
電話番号 |
AI は、name_kana)
Microsoft 365 のカレンダー#
連携する#
- [連携]を
押し、 Microsoft 365 の 職場の アカウントで ログインして 許可します。 個人の Microsoft アカウント (Outlook.com など) では つなげません。 組織の 設定に よっては、 組織の 管理者の 承認が 必要です。 - 続けて
開く 設定の 画面で、 予約を 入れる カレンダー ( 書き込める ものだけ出ます) ・受付の 時間・予約の 長さ・ 前後の 余白を 選んで 保存すると、 使える 状態 ( 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 |
受付の |
create_event |
m365_create_event |
予約の |
cancel_event |
m365_cancel_event |
予約の |
find_events_by_phone_or_name |
m365_find_events_by_phone_or_name |
電話番号 |
AI の
kintone#
連携する#
kintone の
- cybozu.com 共通管理の
「外部連携」 で OAuth クライアントを 追加します。 リダイレクトエンドポイントは https://app.voicast.jp/api/connectors/callbackです。追加したら、 使う 人の 利用を 許可します。 - [連携]を
押し、 サブドメイン ( 〇〇.cybozu.comの〇〇)・クライアント ID・クライアントシークレットを 入力して、 kintone に ログインして 許可します。 - 設定の
画面で、 アプリと、 電話番号・名前・用件の 項目 (文字列・リンク・文字列 (複数行) ) を 選んで 保存します。 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 |
電話番号で |
create_record |
kintone_create_record |
電話番号・名前・用件の |
update_record |
kintone_update_record |
見つけた |
AI に
会話のあとの通知#
会話が{ "connector": "teams" } のように、actions を
Slack・Chatwork・Microsoft Teams へのGET /v1/calls/{id}/webhooks のevent_type がvoicast.notify のconnector にneeds_reauth にconfig.notify_error に
Slack#
- Slack の
api.slack.com/apps で [Create New App] →[From scratch]を 選び、 通知を 送る ワークスペースに アプリを 作ります。 アプリは お客さまの ワークスペースの もので、 ほかの 会社の アプリを 入れる 必要は ありません。 - アプリの
[Incoming Webhooks]を オンにし、 [Add New Webhook]で 通知する チャンネルを 選びます。 - 表示された
Webhook URL ( https://hooks.slack.com/services/…)を、 [連携]で 貼って 保存します (API は POST /v1/connectionsに{ "connector": "slack", "secret": "<URL>" })。 保存の 前に、 確認の 通知を 1 回送ります。 届かない URL は 422 verify_failedです。
Chatwork#
- Chatwork で、
右上の 利用者名 →[サービス連携] → 左の メニューの [API トークン]を 開き、 API トークンを 表示します。 パーソナルプラン以外は、 API を 使うのに 組織の 管理者への 申請 (承認) が 要ります (Chatwork の申請の ページ )。 - [連携]で、
API トークンを 貼って 保存します (API は POST /v1/connectionsに{ "connector": "chatwork", "secret": "<API トークン>" })。 保存の 前に、 トークンで Chatwork の アカウントを 確認します。 トークンが 違うと 422 verify_failedです。 - 続けて
開く 設定の 画面で、 通知を 送る ルームを 選んで 保存します (閲覧だけの ルームは 出ません。 API では GET /v1/connections/{id}/optionsの{ rooms }と、configのroom_id・room_name)。
- 通知は、
API トークンの 持ち主の 名前で ルームに 投稿されます。 通知用の アカウントを 作って トークンを 出すと、 ほかの 人の 名前で 投稿されません。 - API トークンを
作り直した・ルームから 外れた ときは、 通知が 届かなくなります (送り直しません) 。 新しい トークンを 貼り直すと、 選んだルームの まま 戻ります。
LINE WORKS#
- お客さまの
LINE WORKS の Developer Console で アプリを 作ります。 Redirect URL は https://app.voicast.jp/api/connectors/callback、OAuth Scopes は botとuser.readです。トークンの 設定の Refresh Token Rotation は ON に してください。 - Bot を
作って テナントに 追加し、 通知を 受け取る メンバーが 使えるようにします。 - [連携]を
押し、 アプリの クライアント ID・クライアントシークレットと Bot ID を 入力して、 ログインして 許可します。 - 設定の
画面で、 通知を 受け取る メンバーを 選んで 保存します (API では configのuser_id・user_name)。
本文は
Microsoft Teams#
- Teams の
Workflows で 「Webhook 要求を 受信したら チャネルに 投稿する」 の フローを 作り、 フローを 起動できる ユーザーを 「すべての ユーザー」 に します。 - [連携]で、
フローの URL を 貼って 保存します (API は POST /v1/connectionsに{ "connector": "teams", "secret": "<URL>" })。 保存の 前に、 確認の 通知を 1 回送ります。
旧 Office 365 コネクター
エージェント設定に書く#
連携をconnectors に
"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 |
決まったcon_…) |
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 です。
埋め込みの連携の画面#
事業者
リンクの発行#
管理画面では、create_connect_link)
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" }'{ "url": "https://app.voicast.jp/connect/vcl_…", "expires_at": 1790000900000 }| 入力 | 内容 |
|---|---|
connectors |
画面に |
frame_origin |
iframe で |
- リンクの
有効期限は 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>[連携]をneeds_setup で、GET /v1/tenants/{id}/connections で
カスタムの連携#
カスタムのtenant_id をinvalid_request です。external_id で{ "connection": "con_…", "actions": [...] } でapi1_…・api2_…)
URL と API キー(http)#
自社や
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}で保存すると 使えます。
{
"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 |
| 404 | not_found |
| ほかの |
upstream_error |
| 3 秒以内に |
timeout |
| 必須の |
invalid_arguments |
呼び出せる URL#
連携からlocalhost・.local・.internal・点の
連携の状態#
status |
内容 |
|---|---|
active |
使える |
needs_setup |
連携したが、 |
needs_reauth |
ログインでconfig.notify_error) |
会話の
連携先のneeds_reauth にconnection.needs_reauth がtenant が
テナントをDELETE /v1/connections/{id})