会話
Conversationは、Vonage APIが依存する共有コアコンポーネントです。会話は複数のメディア（テキスト、音声）を介して行われ、関連する ユーザー を通して メンバー オブジェクトがある。
ConversationオブジェクトはConversation APIを理解するための鍵です。Userが通信するには、Conversationに接続する必要があり、その時点で関連するMemberオブジェクトがそのConversationに作成されます。
カンバセーションはテキストメッセージングやオーディオ通話をサポートすることができます。テキストメッセージの場合、カンバセーションはチャットルームのように考えることができます。ユーザーは会話に招待され、会話から退出することができます。また、1人のユーザーが複数のメンバーオブジェクトを介して複数のカンバセーションに参加することもできます。
会話中、Vonageは様々な情報を発信します。 イベント.これらのイベントは、メッセージや音声ストリームのような通信イベントや、ユーザの追加や削除、タイピングインジケータなどのその他のイベントとなります。Vonageではイベントのログを記録し、後で検索できるようにしていますが、これらのイベントは発生したときに処理することを意図しています。
会話という文脈の外では、コミュニケーションは成立しない。
会話は、通話のような、始まりと終わりのある一時的なコミュニケーションに使うことができる。あるいは、関連するすべてのやりとりの完全な履歴を保存する永続的なコンテナとして利用することもできます。
会話例
Product deprecation notice
Effective April 30th, 2026, the messaging functionality of the Vonage Conversation API will be discontinued. Access for new users will be closed, and messaging capabilities will no longer be available to existing users after this date.
The voice functionality of the Conversation API will remain available and is not impacted by this change. If you have any questions regarding this partial discontinuation, please contact your account manager or our support team.
次の例を考えてみましょう。ユーザーがVonageアプリケーションに関連付けられたVonage Numbersに電話をかけます。アプリケーションは通話を2台目の電話に転送します。これを下図に示します：
会話内容
呼は、2つのレグ(インバウンドとアウトバウンド)と2つのメンバで構成され、すべてConversationオブジェクトに 含まれる。Conversation APIコールを使用した場合、次のようになります。 会話を得る この会話の詳細を得るには、次のような回答を得るだろう：
{
"id": "CON-bc643220-2542-499a-892e-c982c4150c06",
"name": "NAM-1b2c4274-e3f2-494e-89c4-46856ee84a8b",
"timestamp": {
"created": "2018-10-25T09:26:18.999Z"
},
"sequence_number": 8,
"numbers": {},
"properties": {
"ttl": 172800,
"video": false
},
"members": [
{
"member_id": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"user_id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6",
"name": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6",
"state": "JOINED",
"timestamp": {
"joined": "2018-10-25T09:26:30.334Z"
},
"channel": {
"type": "phone",
"id": "797168e24c19a3c45e74e05b10fef2b5",
"from": {
"type": "phone",
"number": "447700000001"
},
"to": {
"type": "phone",
"number": "447700000002"
},
"leg_ids": [
"797168e24c19a3c45e74e05b10fef2b5"
]
},
"initiator": {
"joined": {
"isSystem": true
}
}
},
{
"member_id": "MEM-25ccda92-839d-4ac6-a7b2-de310224878b",
"user_id": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b",
"name": "vapi-user-f59c1ff26c0543fdb6c02fd30617a1c0",
"state": "JOINED",
"timestamp": {
"invited": "2018-10-25T09:26:19.385Z",
"joined": "2018-10-25T09:26:30.270Z"
},
"invited_by": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b",
"channel": {
"type": "phone",
"id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
"from": {
"number": "Unknown",
"type": "phone"
},
"leg_ids": [
"30cecc87-7ac9-4d03-910a-e9d69558263c"
],
"to": {
"number": "447700000001",
"type": "phone"
},
"cpa": false,
"preanswer": false,
"ring_timeout": 60000,
"cpa_time": 5000,
"max_length": 7200000
},
"initiator": {
"invited": {
"isSystem": true
}
}
}
],
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06"
}
}
}
上記の回答では、電話番号は以下のようになっている：
| Numbers | 説明 |
|---|---|
| 447700000001 | 電話をかける（アリス） |
| 447700000002 | VonageアプリケーションにリンクされたVonage番号 |
| 447700000003 | 相手先の電話（ボブ） |
レスを注意深く見ると、次のことがわかる：
- フォームのIDで識別されるカンバセーションが1つある。
CON-<uuid>. - この会話には2人のメンバーがいます。
- 両メンバーは
JOINED会話の中に - 各メンバーは
phone. - 各チャンネルはIDを持っている。
- 各チャンネルには異なるレグが関連付けられている。
- 各レッグには固有のIDがある。
これは以下の図に示されている：
要約すると、この例では、2つのレグ(インバウンドとアウトバウンド)で構成され る、1つの呼と1つの会話がある。呼に関係する各ユーザーは、その会話のメン バーになることで、会話に参加する。
イベント
通話セッション中に イベント一覧 APIコールでは、コール中にこれまでに発生したイベントが表示される：
[
{
"id": 1,
"type": "member:joined",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"user": {
"id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6"
},
"channel": {
"type": "phone",
"id": "797168e24c19a3c45e74e05b10fef2b5",
"from": {
"type": "phone",
"number": "447700000001"
},
"to": {
"type": "phone",
"number": "447700000002"
},
"leg_ids": [
"797168e24c19a3c45e74e05b10fef2b5"
]
},
"timestamp": {
"joined": "2018-10-25T09:26:19.204Z"
}
},
"state": "",
"timestamp": "2018-10-25T09:26:19.207Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/1"
},
{
"id": 2,
"type": "sip:ringing",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"channel": {
"type": "phone",
"id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
"from": {
"number": "Unknown",
"type": "phone"
},
"leg_ids": [
"30cecc87-7ac9-4d03-910a-e9d69558263c"
],
"to": {
"number": "447700000003",
"type": "phone"
},
"cpa": false,
"preanswer": false,
"ring_timeout": 60000,
"cpa_time": 5000,
"max_length": 7200000
}
},
"state": "",
"timestamp": "2018-10-25T09:26:24.384Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/2"
},
{
"id": 3,
"type": "sip:answered",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"channel": {
"type": "phone",
"id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
"from": {
"number": "Unknown",
"type": "phone"
},
"leg_ids": [
"30cecc87-7ac9-4d03-910a-e9d69558263c"
],
"to": {
"number": "447700000003",
"type": "phone"
},
"cpa": false,
"preanswer": false,
"ring_timeout": 60000,
"cpa_time": 5000,
"max_length": 7200000
},
"direction": "outbound"
},
"state": "",
"timestamp": "2018-10-25T09:26:30.277Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/3"
},
{
"id": 4,
"type": "member:joined",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"user": {
"id": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b"
},
"channel": {
"type": "phone",
"id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
"from": {
"number": "Unknown",
"type": "phone"
},
"leg_ids": [
"30cecc87-7ac9-4d03-910a-e9d69558263c"
],
"to": {
"number": "447700000003",
"type": "phone"
},
"cpa": false,
"preanswer": false,
"ring_timeout": 60000,
"cpa_time": 5000,
"max_length": 7200000
},
"timestamp": {
"invited": "2018-10-25T09:26:19.385Z",
"joined": "2018-10-25T09:26:30.270Z"
}
},
"state": "",
"timestamp": "2018-10-25T09:26:30.273Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/4"
},
{
"id": 5,
"type": "member:media",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"audio": true,
"media": {
"audio": true,
"audio_settings": {
"enabled": true,
"earmuffed": false,
"muted": false
}
},
"channel": {
"type": "phone",
"id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
"from": {
"number": "Unknown",
"type": "phone"
},
"leg_ids": [
"30cecc87-7ac9-4d03-910a-e9d69558263c"
],
"to": {
"number": "447700000003",
"type": "phone"
},
"cpa": false,
"preanswer": false,
"ring_timeout": 60000,
"cpa_time": 5000,
"max_length": 7200000
}
},
"state": "",
"timestamp": "2018-10-25T09:26:30.274Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/5"
},
{
"id": 6,
"type": "sip:answered",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"channel": {
"type": "phone",
"id": "797168e24c19a3c45e74e05b10fef2b5",
"from": {
"type": "phone",
"number": "447700000001"
},
"to": {
"type": "phone",
"number": "447700000002"
},
"leg_ids": [
"797168e24c19a3c45e74e05b10fef2b5"
]
},
"direction": "inbound"
},
"state": "",
"timestamp": "2018-10-25T09:26:30.340Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/6"
},
{
"id": 7,
"type": "member:joined",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"user": {
"id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6"
},
"channel": {
"type": "phone",
"id": "797168e24c19a3c45e74e05b10fef2b5",
"from": {
"type": "phone",
"number": "447700000001"
},
"to": {
"type": "phone",
"number": "447700000002"
},
"leg_ids": [
"797168e24c19a3c45e74e05b10fef2b5"
]
},
"timestamp": {
"joined": "2018-10-25T09:26:30.334Z"
}
},
"state": "",
"timestamp": "2018-10-25T09:26:30.337Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/7"
},
{
"id": 8,
"type": "member:media",
"from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
"to": "",
"body": {
"audio": true,
"media": {
"audio": true,
"audio_settings": {
"enabled": true,
"earmuffed": false,
"muted": false
}
},
"channel": {
"type": "phone",
"id": "797168e24c19a3c45e74e05b10fef2b5",
"from": {
"type": "phone",
"number": "447700000001"
},
"to": {
"type": "phone",
"number": "447700000002"
},
"leg_ids": [
"797168e24c19a3c45e74e05b10fef2b5"
]
}
},
"state": "",
"timestamp": "2018-10-25T09:26:30.337Z",
"href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/8"
}
]
この一時的な会話中に発生したイベントは以下の通りである：
| イベントID | 会員ID | イベントタイプ | 説明 |
|---|---|---|---|
| 1 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:joined | アリスからヴォネージ番号へ |
| 2 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | sip:ringing | ボンテージからボブへ |
| 3 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | sip:answered | ボブが答えた |
| 4 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | member:joined | ボブが会話に参加 |
| 5 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | member:media | ボブ・オーディオのセットアップ |
| 6 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:answered | アリスが答える |
| 7 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:joined | アリスが会話に参加 |
| 8 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:media | アリス・オーディオ・セットアップ |
注： 各イベントにはイベントIDがある。
これは一時的な会話(呼)であるため、呼が終了すると、特に指定しない限り、 会話は利用できなくなる。そのため、会話が生きている間に起こったイベントのみを 見ることができ、終了イベントは見ることができない。そのため、会話が生きている間に発生したイベントのみを見ることができ、 終了イベントは見ることができない。 conversation アクションを呼び出します。アプリケーションのEvent webhookのアクティビティを見れば、終了イベントを見ることができる。 https://www.example.com:9000/webhooks/event のような一連のイベントを見ることになる：
| タイムスタンプ | 方向（脚） | より | へ | イベントの種類（ステータス） | 備考 |
|---|---|---|---|---|---|
| 2018-10-25T09:26:18.991Z | インバウンド | 447700000001 | 447700000002 | started | Vonage番号に発信 |
| 2018-10-25T09:26:18.991Z | インバウンド | 447700000001 | 447700000002 | ringing | 今、鳴っている |
| 2018-10-25T09:26:19.827Z | 該当なし | 447700000001 | 447700000002 | 該当なし | この時点で電話に出る |
| 2018-10-25T09:26:24.384Z | アウトバウンド | 不明 | 447700000003 | started | ボネージが呼びかける |
| 2018-10-25T09:26:24.384Z | アウトバウンド | 不明 | 447700000003 | ringing | ボブが鳴っている |
| 2018-10-25T09:26:30.277Z | アウトバウンド | 不明 | 447700000003 | answered | ボブが答える |
| 2018-10-25T09:26:30.340Z | インバウンド | 447700000001 | 447700000002 | answered | アリスとボブがつながった |
| 2018-10-25T09:31:30.179Z | インバウンド | 447700000001 | 447700000002 | completed | インバウンド・レッグ完了 |
| 2018-10-25T09:31:30.179Z | アウトバウンド | 不明 | 447700000003 | completed | 往路終了 |
これはボブが completed その会話はその後削除された。
ここまでの説明では、2つのレグを持つ電話(チャネル)を介した音声(メディア)通話を扱った。しかし、同じ基本コンセプトが、異なるメディア(テキスト、 In-A Voice、またはVideo)や異なるチャネル(電話、SIP、Websocket、またはApp)にも適用される。例えば、ビデオ通話には異なるイベントタイプが含まれる。