UnifyPortのWhatsApp音声・ビデオ通話：プライベートベータ

お客様がWhatsAppで問題を説明してくれたものの、文章を追加しても状況が伝わりにくい。配送の詳細を話して確認したい、あるいはカメラで実際の状態を見たい。そんな場面に向けて、UnifyPortのプライベートベータでは、業務アプリケーションから1対1のWhatsApp音声・ビデオ通話を準備し、担当者がブラウザーで開始して、バックエンドで通話状態のイベントを受け取れるようになりました。

現在の対象は、担当者が操作するWhatsAppの発信通話です。利用資格はテクニカルサポートがワークスペース単位で有効にします。APIキーを作成しただけでは利用できず、このベータでは着信通話も開放していません。

通話ベータで追加される機能

通話APIリファレンスでは、次の3つの操作を説明しています。

• POST /v1/calls：音声・ビデオ通話を準備し、有効期限が短く1回限り使用できるjoin_urlを返します。
• GET /v1/calls/active：選択したアカウントでUnifyPortが管理している現在の通話を取得します。
• POST /v1/calls/{call_id}/hangup：指定した通話を終了します。

通話の進行をアプリケーションに反映するために、2つのWebhookイベントを利用できます。call.answeredは接続を通知し、call.endedは終了理由と接続後の通話時間を通知します。これらを組み合わせることで、既存のサポートフローに担当者による通話のステップを追加できます。

APIリクエストが行うのは通話の準備です。担当者が返されたリンクを開き、Start callをクリックすると発信します。 発信前に対象のお客様を確認できるよう、この操作を画面上で明示してください。

チャットから通話へ切り替える場面

たとえば、次のようなサポート場面が考えられます。

• 注文内容の確認：短いメッセージでは説明しにくくなった配送の段取りを、担当者とお客様が話して確認する。
• トラブルシューティング：担当者が音声で順番に確認作業を案内する。
• 映像によるサポート：ビデオ通話で、商品の不具合や設置時の問題をお客様に見せてもらう。

これらは想定される利用フローであり、お客様の導入実績や成果を報告するものではありません。いつ通話するかはチームで判断し、次の対応は自社のサポートシステムに記録します。

共有受信箱では、選択したWhatsAppチャットに通話操作を追加できます。接続済みメッセージングアカウントの、そのチャットに対応するconversation_idを使用してください。通話APIは任意の電話番号の文字列を受け付けません。担当者の割り当てや対応完了は、WhatsApp共有受信箱ガイドで説明しているように、自社アプリケーションで管理します。

通話を準備し、担当者が開始する

まずワークスペースのベータ利用を申請し、認証済みのWhatsAppメッセージングアカウントを接続します。アカウントの接続をまだ設定している場合は、QRコード・Passkey認証ガイドで、通話利用とは別の初期設定手順を確認できます。

ワークスペースのX-Api-Keyを使い、バックエンドから作成リクエストを送信します。次のJSONは、ドキュメントに記載されたリクエストボディの例です。POST /v1/callsに送信する前に、acc_exampleと<conversation_id>を選択したアカウントと実際の会話IDに置き換えてください。

{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}

音声通話にはvoice、映像を利用できる通話にはvideoを指定します。APIキーはサーバー側で保持し、返されたjoin_urlは対象の担当者だけに非公開で渡してください。

作成に成功すると、201 Createdとともにcall_id、state: preparing、join_url、expires_atが返ります。この応答は、お客様に発信済み、またはお客様が応答済みであることを示すものではありません。

準備期間は、デフォルトで作成から2分間です。サーバー側で調整される場合があるため、実際の期限には返されたexpires_atを使用してください。担当者は期限までにリンクを開き、Start callをクリックする必要があります。この準備期限は、接続後の通話時間を制限するものではありません。

ブラウザーではマイクへのアクセス許可が必要です。カメラの利用は任意です。リンクは非公開かつ1回限りのものとして扱い、公開したり、URL全体をログに記録したりしないでください。

通話状態をサポートフローへ戻す

返されたcall_idを、選択したアカウント、会話、サポート案件に関連付けて自社システムに保存します。現在の通話を取得するエンドポイントでは、通話IDが分からなくなった場合も含め、必要に応じて管理対象の通話を取得できます。管理対象の通話がなければdata: {}を返します。WhatsAppのモバイルアプリで、どちらかの参加者が通話中かどうかを判定することはできません。

call.answeredとcall.endedを購読し、アプリケーションの通話記録を更新してください。subscribed_eventsを明示的なリストで指定する場合は、この2つのイベント名を含める必要があります。ベータ対象ワークスペースでは、*、空のリスト、またはリストの省略により、許可された通話イベントも購読対象になります。通常のワークスペースは、ワイルドカード購読を使ってもこれらのイベントを受信できません。

終了イベントにはdata.call.id、reason、duration_secondsが含まれます。通話時間は接続後の時間を整数秒に切り捨てた値なので、0だけでは未応答だったと判断できません。応答イベントも記録してください。同期的な作成失敗では終了コールバックが届かない場合があります。そのため、HTTPエラーは別途処理します。

署名の検証とイベントIDによる重複排除については、Webhook配信リファレンスに従ってください。取得した状態は、その後の対応を進めるために利用できます。ただし、通話が終了しても、お客様の問題が自動的に解決済みになるわけではありません。

現在のプライベートベータの対象範囲

このベータが対応するのは、ブラウザーの操作フローから開始するWhatsAppの1対1の音声・ビデオ通話です。グループ通話、チャンネル通話、他のメッセージングプラットフォームでの通話、着信対応は現在の対象外です。日本でよく利用されるLINEを含め、WhatsApp以外の通話に対応するという意味ではありません。ドキュメントにあるcall.incomingイベントは将来のために予約された契約であり、イベント一覧に存在していても着信できるようにはなりません。

録音、文字起こし、SIP/PBX連携、AIによる音声エージェントは、このベータで提供する機能ではありません。UnifyPortは非公式インターフェースを提供しています。この記事はUnifyPort独自の通話契約について説明しており、Meta公式のWhatsApp Business Calling APIとして紹介するものではありません。

ワークスペースのis_betaは読み取り専用で、デフォルトでは無効です。利用資格はテクニカルサポートが有効にする必要があります。資格のないワークスペースが通話APIを利用すると、403 beta_feature_not_enabledと数値コード41002が返ります。metadataの設定やワークスペースへのPATCHでは、有効にできません。

利用前によくある質問

電話番号だけで通話を開始できますか？

できません。選択したWhatsAppメッセージングアカウントの実際のconversation_idを、to.type: userとともに使用してください。

APIを呼ぶとすぐに発信しますか？

いいえ。APIは通話リンクを準備します。担当者がexpires_atまでにリンクを開き、Start callをクリックすると発信します。

通話は2分間に制限されますか？

いいえ。2分間は、作成からの準備期間のデフォルト値です。接続後の通話時間の上限ではありません。

ベータ資格があれば着信に応答できますか？

できません。is_beta: trueのワークスペースを含め、現在のベータでは着信通話を開放していません。

チームの利用を申請する

ワークスペースの**通話ベータ利用をテクニカルサポートに申請してください**。用途を伝えやすくするために、ワークスペースID、WhatsAppでのサポート場面、音声とビデオのどちらを使いたいかを添えることをおすすめします。これらは申請を説明するための参考情報であり、自動登録の手続きではありません。申請にはAPIキーや非公開の通話リンクを含めないでください。

利用資格が有効になったら、通話作成リファレンスを使い、意図して選択した1つのテスト会話を担当者のブラウザー操作につなげてください。改善したいサポートフローから始め、担当者による通話を自社アプリケーションにどう組み込めるかをベータで評価できます。