シェア:
){kind=small}
Liz AcostaはVonageのDeveloper Advocateです。映画学生からマーケター、エンジニア、デベロッパー・アドボケイトという彼女のキャリア・パスは型破りに見えるかもしれないが、デベロッパー・リレーションズにとってはごく一般的なものだ！ピザ、植物、パグ、Pythonが大好き。
Pythonでインバウンドの電話を処理する
所要時間：2 分
このチュートリアルでは、Pythonの FastAPIを使って着信電話を受ける音声アプリケーションを開発する方法を学びます。 Vonage Voice API を使います。.電話を受信してルーティングするソフトウェアは、企業が顧客体験を向上させるのに役立ちます。よりパーソナライズされた効率的なサポートが可能になります。このチュートリアルでは、3つの一般的なカスタマーサポートコールフローシナリオについて説明します：
このチュートリアルが終わる頃には、Python FastAPIアプリと ngrok.このガイドを読めば、アプリの機能を拡張してユーザーとリアルタイムにつながり、アプリケーションをよりインタラクティブで魅力的なものにすることができます。カスタマーサービスソリューションやコミュニケーションツールのいずれを構築する場合でも、これらのスキルを習得することで、プロジェクトの機能とユーザーエクスペリエンスを向上させることができます。
Vonageボイス・アプリケーションは以下を採用しています。 Vonageコール・コントロール・オブジェクト(NCCO) を使用してコールフローを構築します。 NCCOアクション.言い換えれば、NCCOは着信コールを制御できるアクションのJSON配列です。典型的なNCCOは以下のようになります：
[
{"action": "talk",
"text": "Hello, one moment please, your call is being forwarded to our agent."},
{"action": "connect",
"from": VONAGE_NUMBER,
"endpoint": [{"type": 'phone',
"number": YOUR_SECOND_NUMBER}]}
]
この例では、2つのアクションがある： talk そして connect.アクションには通常、設定可能なキーと値のオプションのセットが付属しています：
アクションは
talkアクションではtextオプションは音声合成スクリプトを提供します。詳しくは NCCOトークアクションのドキュメント.この
connectアクションには2つのオプションがある：fromとendpoint.アクションの設定は NCCO Connectアクションリファレンスを参照してください。
その talkと connectアクションはリストされた順番で同期的に実行される。一部のアクションは、非同期になるように設定できる。これは、呼び出し元が言語選択などのオプションメニューから選択できるような コールフローを構築するときに便利である。このようなシナリオでは、通話を続行するために、発呼側で言語メニュー全体を 待たせる必要はない。これは、非同期で実行したいことである。この動作を理解するには 非同期NCCOアクションガイド.
要約すると、NCCOは特定のニーズに合わせて洗練されたコールフローを作成するためのビルディングブロックを提供します。
このチュートリアルを完成させるために、Vonage以外の技術的なコンセプトやツールに頼りますが、それはソフトウェア開発の他の分野で役に立つかもしれません。
ウェブフックとは、あるウェブベースのアプリケーションが他のアプリケーションにデータやイベント通知をプッシュする方法のことで、一方のアプリケーションがもう一方のアプリケーションに常に更新をポーリングする代わりに、自動的な通信を可能にします。一般的に、これはHTTPリクエストを使ってAPI経由でウェブ上でやりとりすることを意味します。このチュートリアルでは、誰かがあなたのバーチャル番号に電話をかけたことをウェブアプリケーションに通知し、コールフローアクションのNCCOを返すためにウェブフックを使用します。
FastAPIは、PythonでHTTPベースのサービスAPIを構築するための高性能なWebフレームワークです。FastAPIが他のPython Webフレームワークと異なる点は、Pythonと密接に連携していることです。 Pydanticと密接に連携していることです。この連携により、FastAPIはデータの検証、シリアライズ、デシリアライズを行うことができます。これにより、HTTPボディや送信レスポンスなどの受信リクエストに対して、より宣言的な方法でデータの構造やタイプを指定することができます。また、FastAPI は自動的に OpenAPI仕様も自動的に生成します。これらの機能を組み合わせることで、最新のREST API、マイクロサービス開発、リアルタイム機能を必要とするアプリケーションに特に適しています。
このチュートリアルでは、ウェブアプリケーションを作成し、あなたのマシン上でローカルに実行します。ローカルで実行するため、公共のインターネットからアクセスすることはできません。もしウェブアプリにアクセスできなければ、Vonageはウェブフックにリクエストを出すことができません。そこでトンネリングの登場です。トンネリングは、一時的または静的なパブリックURLを通じて、ローカルサーバーをパブリックインターネットに公開します。 ngrokはこのサービスを提供するソフトウェア・プラットフォームだ。
要約すると、Webhookを持つPython FastAPIウェブアプリを作成し、ngrokを使用して、パブリックURLへのトンネリングを介してローカルアプリケーションにアクセスできるようにします。
このチュートリアルでは、FastAPIを使用して、誰かがあなたのバーチャル番号に電話をかけたときにVoice APIがリクエストできるWebhookを定義します。ngrokを使ってWebhookを公衆インターネットに公開します。そして、Vonageを使ってバーチャル番号を購入し、Voice APIを使って着信処理を完了させます。
お望みであれば、次のコードをプルダウンすることもできる。 インバウンドコールの処理を Vonage Community GitHub からダウンロードすることもできます。
このチュートリアルを完了するには、以下のものが必要です：
Python 3.8+
アカウント ngrokアカウントおよびインストール
接続先の「エージェント」として機能する追加の電話番号
組み立てを始める前に、すべてのことを整理しておこう。
Voice APIはWebhookにリクエストできるようにアクセスできなければならないため、エンドポイントのURLは公衆インターネット経由でアクセスできなければなりません。
このチュートリアルでは、そのために ngrok.私たちの チュートリアルをご覧ください。
ターミナル・ウィンドウで、このプロジェクト用のディレクトリを作成し、そこに移動する：
mkdir vonage-inbound-call && cd vonage-inbound-call
すべての準備が整ったところで、いよいよビルド開始だ。
このチュートリアルでは、3つの異なるコールフローについて説明します：
各シナリオに入る前に、まずVonageアプリケーションを作成し、以下を完了させて開発環境を整えます：
Voice APIがWebhookにリクエストできるように、Webhookにアクセスできなければなりません。そのためには、エンドポイントURLを公共のインターネットに公開する必要があります。これがngrokの目的だ。
別のターミナル・ウィンドウで実行する：
ngrok http 3000このコマンドは、ローカルサーバーがポート3000にトンネリングする公開URLを生成します。公開URLに注意してください：
Forwarding https://0a6ec0a950eb.ngrok-free.app -> http://localhost:3000
まず、Voice APIアプリケーションを作成する必要があります。ここでいう「アプリケーション」とは、以下のようなものです。 Voice APIに必要な設定やセキュリティ情報のためのコンテナです。.これから作成する FastAPI Web アプリケーションとは異なります。
Voice APIアプリケーションの作成 開発者ダッシュボードに移動して アプリケーションウィンドウに移動し、"Create new application" ボタンをクリックします。アプリケーション作成メニューが開きます。アプリケーションに名前を付けます。 inbound-call.
以下の 機能セクションで Voiceのオプションを切り替えます。テキストフィールドの 応答 URLというテキストフィールドに、FastAPI アプリで定義した Webhook で修正した ngrok 公開 URL を入力します。これは次のようになります： https://96b34a48a639.ngrok-free.app/webhooks/answer.
新規アプリケーションの作成」ボタンをクリックします。
A screenshot of the Create an application menu in the Vonage developer dashboard.アプリケーションの作成が完了したら、マイナンバーをアプリケーションにリンクさせることができます。 リンクボタンをクリックします。これで、アプリケーションは着信コールに応答する準備ができました。これからコーディングするシナリオは、Webhookが呼び出されたときにアプリケーションが何をすべきかを指示するものです。 /answerが呼び出されたときにアプリケーションに何をするかを伝えます。
Python 仮想環境を使うと、システムの他の部分から隔離された場所にパッケージをインストールすることができます。これはシステム全体の混乱を防ぎ、異なる Python バージョンやパッケージとの衝突を防ぐのに役立ちます。私たちの 仮想環境を参照してください。
プロジェクト・ディレクトリで、以下のコマンドを実行して仮想環境を作成し、仮想環境をアクティブにします：
python3 -m venv venv && source venv/bin/activateこれでターミナルのプロンプトの先頭に (venv).仮想環境を停止するには deactivateコマンドを実行してください。
このチュートリアルで必要な依存関係をインストールするために、以下を実行する：
pip install vonage python-dotenv 'fastapi[standard]'これでコーディングを始めるのに必要なものはすべて揃った。
この特別なシナリオでは、バーチャル番号への着信コールに対して、音声合成メッセージを再生して応答する。
という名前のファイルを作成する。 scenario-1.pyという名前のファイルを作成する：
from fastapi import FastAPI, Query
from vonage_voice import Talk
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call(from_: str = Query(..., alias='from')):
from_ = '-'.join(from_)
return [Talk(text=f'Thank you for calling from {from_}').model_dump(by_alias=True, exclude_none=True)]
このコードは /webhooks/answerエンドポイントを作成します。このエンドポイントは Voice API からのリクエストを受信すると NCCOリストを Talkアクションを持つNCCOリストを作成し、反復処理します。これが、発信者が番号をダイヤルしたときに聞く音声合成の役割を果たします。音声合成を使った通話への応答についてもっと知りたい方は、コードサンプルをご覧ください、 コードサンプルをご覧ください。.
さあ、アプリを試す時間だ。
ターミナル・ウィンドウで実行する：
fastapi dev --port 3000 scenario-1.pyこれにより、ポート3000のWebhookエンドポイントを持つローカルサーバーがスピンアップされます。これでアプリケーションはコールを受け取る準備ができました！
ダッシュボードでアプリケーションにリンクしたバーチャル番号に電話をかけます。すべてが正しく動作していれば、Pythonコードで定義した音声合成メッセージが表示されるはずです。
テストが終わったらサーバーを終了し、次のシナリオをコーディングできるようにする。
このシナリオでは、NCCOアクションを含める。 Connectアクションが含まれます。 Talkアクションが含まれます。
という名前の新しいファイルを作成し scenario-2.pyという名前の新しいファイルを作成し、以下のコードを追加する：
from fastapi import FastAPI, Query
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint
VONAGE_VIRTUAL_NUMBER = 'Replace-this-text-with-your-Vonage-virtual-number'
AGENT_NUMBER = 'Replace-this-text-with-your-agent-number'
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call():
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]このコードは /webhooks/answerエンドポイントを作成します。このエンドポイントは Voice API からのリクエストを受信すると NCCOリストを Talkアクションと Connectアクションを持つこの Connectアクションでは、Vonageバーチャル番号と追加のエージェント番号の両方を、変数 VONAGE_VIRTUAL_NUMBERと AGENT_NUMBERにそれぞれ指定する必要があります。Voice APIを使った通話接続の詳細については を参照してください。.
このチュートリアルの他のシナリオで実行中のアプリケーションを停止し、実行します：
fastapi dev --port 3000 scenario-2.pyこの特別なシナリオを試すには、2つの電話番号が必要だ：ひとつはバーチャル番号にかけるための電話番号、もうひとつは接続するための電話番号です。Vonageのバーチャル番号にダイヤルし、すべてが正しく実装されていれば、音声合成メッセージが表示され、2番目の番号（エージェント番号）が鳴るはずです。
このシナリオでは、発信者を保留にし、エージェントが応答できるまで音楽を流すことで、着信コールを処理します。その後、通話はエージェントに転送されます。
これがこれから実装するコールフローだ：
電話に出ると、発信者は音声合成メッセージを聞くことができます。
発信者は保留状態になり、音楽が流れます。
30秒のシミュレーションの後、通話は2番目のNCCOに転送されます。
2番目のNCCOは音声合成メッセージを再生し、発信者をエージェントにつなぐ。
このシナリオでは Voice API を使用して進行中の通話を更新する。クライアントを作成するには、Vonage アプリケーション ID と秘密鍵が必要です。これによって、更新を行うユーザが認証され、通話の所有権を持っていることが保証される。友人との通話中に突然保留音楽が聞こえてきたら、かなり不安になるだろう！アプリケーションIDと秘密鍵は、Vonage開発者ダッシュボードから取得できます。
開発者ダッシュボードの Applications メニューで、このチュートリアル用に作成したアプリケーションをクリックし、"Edit" をクリックします。編集ウィンドウが開いたら、"Generate public and private key "というボタンをクリックします。これにより、秘密鍵が拡張子 .key. このファイルは秘密にしておき、漏洩する可能性のある場所では共有しないでください。Save changes"（変更を保存）ボタンをクリックします。 アプリケーションID.
A screenshot of the application Edit menu in the Vonage developer dashboard showing where to generate a public and private key.
A screenshot of the inbound-call application in the Vonage developer dashboard showing where you can find the application ID.秘密鍵ファイルを、Pythonコードがあるのと同じディレクトリに移動する。同じディレクトリに .envという名前のファイルを作成し、以下を追加する：
APPLICATION_ID=Replace-this-with-your-application-ID
PRIVATE_KEY=Replace-this-with-the-name-of-your-private-key-file
という名前の新しいファイルを作成し scenario-3.pyという名前の新しいファイルを作成し、以下のコードを追加する：
import os
from dotenv import load_dotenv
from threading import Timer
from fastapi import FastAPI, Query
from vonage import Auth, Vonage
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint, Stream
load_dotenv()
APPLICATION_ID = os.getenv("APPLICATION_ID")
PRIVATE_KEY = os.getenv("PRIVATE_KEY")
VONAGE_VIRTUAL_NUMBER = '**********' # Replace with your Vonage virtual number
AGENT_NUMBER = '**********' # Replace with your "agent" number
AUDIO_URL = "https://download.samplelib.com/mp3/sample-12s.mp3"
app = FastAPI()
def transfer_call(call_id):
print("Transferring the call ... ")
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
client = Vonage(Auth(application_id=APPLICATION_ID, private_key=PRIVATE_KEY,))
client.voice.transfer_call_ncco(uuid=call_id, ncco=ncco)
@app.get('/webhooks/answer')
async def answer_call(call_id: str = Query(..., alias='uuid')):
print(f"The UUID for this call is:====> {call_id}")
Timer(30, transfer_call, [call_id]).start()
ncco: list[NccoAction] = [
Talk(text="Hello, our agents are assisting other customers. Please hold and we will connect you as soon as possible."),
Stream(streamUrl=[AUDIO_URL],loop=0),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]このコードでは多くのことが起こっているので、それを分解してみよう。
まず、以下の変数を更新する必要がある：
vonage_virtual_number：プレースホルダーのテキストをVonageのバーチャル番号に置き換えてください。
AGENT_NUMBER：プレースホルダーのテキストを、発信者が転送される「エージェント」の電話番号に置き換える。
このコードでは /webhooks/answerエンドポイントを定義します。このエンドポイントは Voice API からのリクエストを受信すると NCCOリストを Talkアクションと Streamアクションでホールドミュージックを再生します。
機能 transfer_callは Vonageクライアントを作成し、一意の識別子番号を使用して通話を転送する。を行います。
保留にされることをシミュレートしているので、コードは Timerオブジェクトを使って transfer_call関数を呼び出している。
コードを理解したところで、実際に動かしてみよう。他のアプリケーションが起動していないことを確認してから実行してください：
fastapi dev --port 3000 scenario-3.pyこの特別なシナリオを試すには、2つの電話番号が必要だ：ひとつはバーチャル番号にかけるための電話番号、もうひとつは接続するための電話番号です。Vonageのバーチャル番号にダイヤルすると、音声合成メッセージと保留音楽が流れます。30秒後、通話は指定したエージェント番号に転送されます。
このチュートリアルでは、Vonage Voice API と Python FastAPI アプリケーションを使って着信電話を処理する方法を学びました。Vonage Call Control Objects (NCCOs) がどのようにコールフローを定義し、Webhook がどのようにアプリケーションをリアルタイムで着信コールに応答させるかを学びました。3つの実践的なシナリオを通して、一般的なカスタマーサポートのワークフローを実装しました：音声合成メッセージの再生、発信者をエージェントに接続、電話を転送する前に音楽で保留にする。
さらに、Voice API アプリケーションを構成し、ngrok を使用してローカルの FastAPI サーバーを公開し、Voice API を使用して進行中の通話を更新しました。これらの基本的な要素は、顧客との対話を大幅に強化し、応答時間を改善し、ビジネスのオペレーションを合理化します。例えば 電話会議システムの構築, カスタムコールフローの構築または キャンペーンのパフォーマンス追跡.
さらに知識を深めたい方は、以下の関連記事をご覧ください。 Python音声アプリケーションまたは APIインテグレーションをご覧ください。これらのコンセプトを実装することで、パーソナライズされた顧客体験や自動化の機会を得ることができ、ビジネスの成長と効率化を促進することができます。
をチェックしてください。 Voice APIリファレンスVoiceアプリケーションに組み込めるものの詳細なリストについては、Voice APIリファレンスを参照してください。
NCCOのアクションについては、公式ガイドの ガイド
ご質問がある場合、またはあなたが作っているものを共有したい場合は、こちらをクリックしてください。
登録する 開発者ニュースレター
フォローする X（旧ツイッター）最新情報
チュートリアルを見る YouTubeチャンネル
LinkedInの LinkedIn の Vonage デベロッパーページ
最新の開発者向けニュース、ヒント、イベント情報をお届けします。