Voice Insights SDK Events Reference
Voice Insights enables you to see key events that occur in the lifecycle of a Twilio Client call. The event log provides events on any state change transitions that occur during a call, warnings seen on deteriorating network quality or audio equipment malfunction, and the events raised when the feedback submitted by the end user. Event log also contains errors seen on connection failures. Connection errors occur when the Twilio SDK fails to connect with Twilio servers. These failures can occur because of severe network degradation or due to a firewall.
イベント・リファレンスでは通話のライフサイクルについて把握できるようにするための各イベントについて触れています。
- ERROR and WARNING events
- INFO and DEBUG events
- Network Warning Cleared events
- Audio Warning Cleared events
- Audio Events
- ICE Connection State Events
- Signaling State Change Events
- ユーザー・メディア・イベント
- Connection Events
- Peer Connection Events
- ICE Candidate Events
- ICE Gathering State Events
- ICE Connection State Events
- Settings Events
- フィードバック・イベント
- Registration Events
- Network Change Events
ERROR and WARNING events
The following events are logged to the Voice Insights system and are also raised as error or warning events in the SDK.
Network warnings
The following events are raised when Twilio SDKs detect deteriorating network conditions on the stream received at the SDK sensors from the Twilio media gateway. These events belong to the network-quality-warning-raised group.
#warning イベントをリスニングすることで、これらのイベントに対するハンドラーを実装でき、エンドユーザーが問題に気づけるように視覚的なインジケーターを表示できます。
| EventName | イベントレベル | 発生条件 | 概要 |
|---|---|---|---|
high-rtt |
Warning | 最新の5サンプル中3サンプルについて、ラウンド・トリップ・タイム（RTT = Round Trip Time）が400ミリ秒を上回った場合 | ラウンド・トリップ・タイム（RTT = Round Trip Time）はネットワーク中のレイテンシー（遅延）の目安です。 高レイテンシーは耳で聴こえるくらいの遅延となって現れます。 |
low-mos |
Warning | 最新の5サンプル中3サンプルについて、平均オピニオン評点 (MOS = Mean Opinion Score) が3.5を下回った場合 | 平均オピニオン評点 (MOS = Mean Opinion Score) は通話品質に影響する全般的なネットワーク状態の目安です。 |
high-jitter |
Warning | 最新の5サンプル中3サンプルについて、ジッターが30ミリ病を上回った場合 | Jitter is the measure of variability at which packets arrive at the SDK sensors. High jitter can result in audio quality problems on the call, such as crackling and choppy audio. |
high-packet-loss |
Warning | Packet loss > 1% in 3 out of last 5 samples | Packet loss is measured as the percentage of packets that were sent but not received at the SDK sensors. High packet loss can result in choppy audio or a dropped call. |
high-packets-lost-fraction |
Warning | Packet loss > 3% in 7 out of last 10 samples | A more severe event than merely high-packet-loss. Packet loss can result in choppy audio or a dropped call (Android/iOS SDKs only). |
low-bytes-received |
Warning | Bytes received = 0 for three consecutive seconds | The SDK sensors detect no bytes being received at the SDK (JS SDK only). |
low-bytes-sent |
Warning | Bytes sent = 0 for three consecutive seconds | The SDK sensors detect no bytes being sent from the SDK (JS SDK only). |
ice-connectivity-lost |
Warning | ICE transitions to disconnected state |
The previously selected ICE connection was lost and renegotiation will be required. (JS SDK only). |
Audio warnings
The following events are raised whenever Twilio SDKs detect that the audio level has stayed constant for an unexpected duration. As the participants interact on the call, audio levels vary. Although these events could indicate a problem, constant audio levels could occur when one of the participants has muted their microphone using a hardware mute.
これらのイベントの発生がかなりの時間続いた場合、ユーザーのマイクが誤ってミュートされていないか確認を促す用途に、この機能は役に立つかもしれません。
#warning イベントをリスニングすることで、これらのイベントに対するハンドラーを実装でき、エンドユーザーが問題に気づけるように視覚的なインジケーターを表示できます。
The following warning events belong to the audio-level-warning-raised group. These are also emitted by the SDK through the event emitter. These warning level events are cleared on any fluctuation in audio levels.
| EventName | イベントレベル | 発生条件 |
|---|---|---|
constant-audio-input-level |
Warning | Audio input level from the microphone is unchanged for 20 seconds. JS SDK 1.13.0 and later: The most recent ten seconds of volume values are recorded and then analyzed. If the standard deviation of these samples is less than 1% of the maximum audio value, then the warning is raised. |
constant-audio-output-level |
Warning | Audio output level from the speakers/headset is unchanged for 20 seconds. JS SDK 1.13.0 and later: The most recent ten seconds of volume values are recorded and then analyzed. If the standard deviation of these samples is less than 1% of the maximum audio value, then the warning is raised. |
Audio errors are also fired when speaker and ringtone devices fail to set (JS SDK only).
| EventName | イベントレベル | 発生条件 |
|---|---|---|
ringtone-devices-set-failed |
ERROR | Output selection is not supported by the browser, a specified deviceId wasn’t found, or no deviceIds were specified |
speaker-devices-set-failed |
ERROR | Output selection is not supported by the browser, a specified deviceId wasn’t found, or no deviceIds were specified |
Connection warnings
| EventName | イベントレベル | 発生条件 |
|---|---|---|
listening-error |
Warning | Raised when an attempt to listen for cancellation has failed (Android/iOS only) |
error |
ERROR | 接続エラーが発生しました。 低品質なネットワーク接続やセットアップのミスがエラーの原因となった可能性があります。 |
Peer Connection warnings
The following events are logged as part of the pc-connection-state group.
| EventName | イベントレベル | 発生条件 |
|---|---|---|
failed |
Warning | Raised when one or more of the ICE transports on the connection is in the "failed" state. |
ICE Gathering State warnings
These events are logged as part of the ice-gathering-state group.
| EventName | イベントレベル | 発生条件 |
|---|---|---|
none |
Warning | Raised when no ICE candidates are gathered. |
timeout |
Warning | Raised when ICE candidate gathering times out. |
ICE Connection warnings
下記のイベントはice-connection-state グループに属します。 これらは下記で説明されている標準の RTCPeerConnection.iceConnection 状態となります。ICEイベントについてのさらなる詳細については、こちらをご参照ください。
| EventName | イベントレベル | 発生条件 |
|---|---|---|
failed |
ERROR | ICE候補がすべての候補の組み合わせで確認され、接続のすべてのコンポーネントにおいて互換性のある一致の検索に失敗しました。 これはしかし、ICEエージェントがいくつかのコンポーネントについては互換性のある接続を見つけた可能性があります。 |
User Media Errors
下記のイベントは get-user-media グループに属します。 これらのイベントは、twilio.jsがユーザーのオーディオ・マイクにアクセスできたかどうかを示しています。
| EventName | イベントレベル | 発生条件 |
|---|---|---|
failed |
ERROR | Twilioクライアントはユーザーのメディア・デバイスのアクセスに失敗しました。 このイベントは、ユーザーのデバイス上のその他のエラーによってマイクがアクセスできなかった場合に記録されます。 |
denied |
ERROR | ユーザーがマイク／スピーカーへのアクセス許可を拒否し、結果接続を確立できませんでした。 |
登録エラー
| EventName | イベントレベル | 発生条件 |
|---|---|---|
unsupported-cancel-message-error |
ERROR | Raised when a "cancel" push notification is processed by the SDK. The version of the SDK does not support "cancel" push notifications. |
registration-error |
ERROR | Raised when registration fails. |
unregistration-error |
ERROR | Raised when unregistration fails. |
unregistration-registration-error |
ERROR | In order to unregister, a registration needs to have been performed. Attempts to unregister a client instance that is not registered will result in this error. |
INFO and DEBUG events
The following events are logged to the Voice Insights system, but are not raised as warning events in the Twilio SDKs.
Network warning cleared events
When Twilio SDKs detect that network conditions are back to normal, these warnings are cleared. The warning-cleared events belong to the network-quality-warning-cleared group.
| EventName | イベントレベル | 発生条件 |
|---|---|---|
high-rtt |
info | 最新の5サンプル中3サンプルについて、ラウンド・トリップ・タイム（RTT = Round Trip Time）が400ミリ秒を下回った場合 |
low-mos |
info | 最新の5サンプル中3サンプルについて、平均オピニオン評点 (MOS = Mean Opinion Score) が3.5を上回った場合 |
high-jitter |
info | 最新の5サンプル中3サンプルについて、ジッターが30ミリ病を下回った場合 |
high-packet-loss |
info | packet loss < 3% in 7 out of last 10 samples |
Audio warning cleared events
These belong to the group audio-level-warning-cleared.
| EventName | イベントレベル | 発生条件 |
|---|---|---|
constant-audio-input-level |
info | Raised when audio input level starts varying again after a warning was raised |
constant-audio-output-level |
info | Raised when audio output level starts varying again after a warning was raised |
Audio Events
Audio events are fired when speaker and ringtone devices are set and when a device change is detected (JS SDK only).
| EventName | イベントレベル | 発生条件 |
|---|---|---|
speaker-devices-set |
info | speakerDevices set via Twilio.AudioOutputCollection |
ringtone-devices-set |
info | ringtoneDevices set via Twilio.AudioOutputCollection |
device-change |
info | Fired whenever a new audio device is found, an existing audio device is lost or the label of an existing device is changed. This typically happens when the user plugs in or unplugs an audio device, like a headset or a microphone. This will also trigger after the user has given access to user media via getUserMedia for the first time, as the labels will become populated. If you want to allow users to choose a specific audio device in your application’s UI, attach a listener to this event. Note that this does not detect a customer plugging in headphones or other speakers through the headphone jack, as the headphone jack only redirects audio from the internal audio device. |
ICE-Connection-State イベント
下記のイベントはice-connection-state グループに属します。 これらは下記で説明されている標準の RTCPeerConnection.iceConnection 状態となります。ICEイベントについてのさらなる詳細については、こちらをご参照ください。
| EventName | イベントレベル | 概要 |
|---|---|---|
checking |
debug | ICEエージェントに1つ以上のリモート候補が与えられ、互換性の一致を見つけようとローカルおよびリモート候補の組を相互に確認していますが、まだ組が見つかっていません。 候補の収集が依然として進行中である可能性があります。 |
connected |
debug | ローカルおよびリモートの候補に使用できるペアリングが接続のすべてのコンポーネントにおいて見つかり、接続が確立されました。 収集は依然として進行中の可能性があり、またICEエージェントは依然として使用できるより良い他の接続の候補を探している可能性があります。 |
closed |
debug | このRTCPeerConnection用のICEエージェントはシャットダウンし、もうリクエストを処理することができません。 |
completed |
debug | ICEエージェントは候補の収集を終え、すべての組み合わせについてチェックを行い、すべてのコンポーネントにおいて接続が見つかりました。 |
disconnected |
debug | RTCPeerConnectionの最低1つのコンポーネントについて、まだ接続が成功していないことを示します。 これは failed よりもより緩いテストで、信頼性の低いネットワーク、あるいは一時的なネットワークの切断時のそれのように断続的にトリガーされ、また自然に復帰することがあります。 問題が解決すると、接続は connected 状態に戻ることがあります。 |
シグナリング状態イベント
下記のイベントは signaling-state グループに属します。 これらは、下記で述べるような標準の RTCPeerConnection.signalingState イベントです。
| EventName | イベントレベル | 概要 |
|---|---|---|
stable |
debug | 進行中のオファーの交換がなく、応答は進行中です。 RTCPeerConnectionオブジェクトが新しく、localDescriptionおよびremoteDescriptionがnullの可能性があります; これはネゴシエーションが完了し、接続が確立されたことを意味する可能性もあります。 |
closed |
debug | コネクションが閉じられました。 |
have-remote-offer |
debug | リモート・ピアがオファーを作成し、シグナリング・サーバーを使用してRTCPeerConnection.setRemoteDescription()を呼ぶことでリモート・デスクリプションとしてオファーを設定したローカル・ピアに対してそれを送り届けます。 |
have-local-offer |
debug | ローカル・ピアはRTCPeerConnection.setLocalDescription()を呼び、オファー（通常はRTCPeerConnection.createOffer()を呼ぶことで作成されます）を表すSDPを渡すと、そのオファーの適用が成功します。 |
have-remote-pranswer |
info | Android/iOS SDK only |
シグナリング・イベントについての詳細は、こちらでご確認ください。
接続イベント
The following events belong to the connection group. They are logs of the key events that describe the state of the connection between the SDK and Twilio.
| EventName | イベントレベル | 概要 |
|---|---|---|
disconnected-by-local |
info | The connection was disconnected by the local participant. |
incoming |
info | Twilioクライアントは着信接続を受信しました。 |
accepted-by-local |
info | クライアントAppによって接続が受理されました。 |
accepted-by-remote |
info | 接続が、電話の着信したリモートの参加者で受理されました。 |
disconnected-by-remote |
info | リモートの参加者が切断しました。 |
ignored-by-local |
info | 着信接続がクライアントによって無視されました。 |
unmuted |
info | 接続がミュート解除されました。 |
muted |
info | 接続がミュートされました。 |
rejected-by-local |
info | 着信接続がローカルの参加者によって拒否されました。 |
connected |
info | (Android and iOS SDK only). |
outgoing |
info | (Android and iOS SDK only). |
ringing |
info | Indicates the incoming call is ringing (Android and iOS SDK only). |
disconnect-called |
info | (Android and iOS SDK only). |
outgoing-ringing |
info | Indicates the outbound call is ringing. |
listen |
info | Raised when an attempt to listen for cancellations is made (Android and iOS SDK only). |
listening |
info | Raised when an attempt to listen for cancellations has succeeded(Android and iOS SDK only). |
cancel |
info | Raised when a cancellation has been reported (Android and iOS SDK only). |
reconnecting |
info | Raised when media connection fails and automatic reconnection has been started by issuing ICE Restarts. |
reconnected |
info | Raised when media connection has been restored which is detected when media starts flowing. |
hold |
info | Indicates the call has been put on hold (Android and iOS SDK only). |
unhold |
info | Indicates the call has been taken off hold (Android and iOS SDK only). |
Peer Connection events
The following events are logged as part of the pc-connection-state group. They indicate key events that describe the state of the peer connection between the SDK and Twilio's WebRTC gateway. (JS SDK Only)
| EventName | イベントレベル | 概要 |
|---|---|---|
connecting |
debug | One or more of the ICE transports are currently in the process of establishing a connection; that is, their RTCIceConnectionState is either "checking" or "connected", and no transports are in the "failed" state. |
connected |
debug | Every ICE transport used by the connection is either in use (state "connected" or "completed") or is closed (state "closed"); in addition, at least one transport is either "connected" or "completed". |
disconnected |
debug | At least one of the ICE transports for the connection is in the "disconnected" state and none of the other transports are in the state "failed", "connecting", or "checking". |
new |
debug | At least one of the connection's ICE transports (RTCIceTransports or RTCDtlsTransports) are in the "new" state, and none of them are in one of the following states: "connecting", "checking", "failed", or "disconnected", or all of the connection's transports are in the "closed" state. |
closed |
debug | The RTCPeerConnection is closed. |
ICE Candidate Events
These events are logged as part of the ice-candidate group.
| EventName | イベントレベル | 概要 |
|---|---|---|
ice-candidate |
debug | Raised during ICE gathering process when an ICE candidate is identified. |
selected-ice-candidate-pair |
debug | Shows the transport protocol and ICE candidate type for both local and remote participants. |
ICE Gathering State Events
The events below are logged as part of the ice-gathering-state group.
| EventName | イベントレベル | 概要 |
|---|---|---|
new |
debug | Indicates the peer connection was just created and hasn't done any networking yet. |
gathering |
debug | Indicates the ICE agent is in the process of gathering candidates for the connection. |
complete |
debug | Raised when the ICE agent has finished gathering candidates. If something happens that requires collecting new candidates, such as a new interface being added or the addition of a new ICE server, the state will revert to gathering to gather those candidates. |
ICE Connection State Events
The following events are logged as part of the ice-connection-state group.
| EventName | イベントレベル | 概要 |
|---|---|---|
connecting |
debug | The ICE agent is connecting to the remote candidate. |
new |
debug | The ICE agent is gathering addresses or is waiting to be given remote candidates. |
gathering |
debug | The ICE agent is gathering candidates. |
completed |
debug | ICEエージェントは候補の収集を終え、すべての組み合わせについてチェックを行い、すべてのコンポーネントにおいて接続が見つかりました。 |
none |
debug | No ICE candidates returned. |
timeout |
debug | The ICE connection has timed out. |
checking |
debug | ICEエージェントに1つ以上のリモート候補が与えられ、互換性の一致を見つけようとローカルおよびリモート候補の組を相互に確認していますが、まだ組が見つかっていません。 候補の収集が依然として進行中である可能性があります。 |
disconnected |
debug | Checks to ensure that components are still connected failed for at least one component of the RTCPeerConnection. This is a less stringent test than "failed" and may trigger intermittently and resolve just as spontaneously on less reliable networks, or during temporary disconnections. When the problem resolves, the connection may return to the "connected" state. |
closed |
debug | このRTCPeerConnection用のICEエージェントはシャットダウンし、もうリクエストを処理することができません。 |
connected |
debug | ローカルおよびリモートの候補に使用できるペアリングが接続のすべてのコンポーネントにおいて見つかり、接続が確立されました。 収集は依然として進行中の可能性があり、またICEエージェントは依然として使用できるより良い他の接続の候補を探している可能性があります。 |
ユーザー・メディア・イベント
下記のイベントは get-user-media グループに属します。 これらのイベントは、twilio.jsがユーザーのオーディオ・マイクにアクセスできたかどうかを示しています。
| EventName | イベントレベル | 概要 |
|---|---|---|
succeeded |
info | Twilioクライアントはユーザーのメディア・デバイスに正常にアクセスできました。 これは、接続を確立するための特権です。 |
Settings events
| EventName | イベントレベル | 概要 |
|---|---|---|
codec |
info | Raised when the codec has been selected |
フィードバック・イベント
Twilio.jsは postFeedback APIを通じて、ユーザーに個々の通話についての品質評価をしてもらうことができます。 フィードバックが送信されると、Voice Insightsダッシュボードから結果を視覚化、分析できるようになります。
フィードバック・イベントは 右記のグループに属します: feedback
| EventName | イベントレベル | 概要 |
|---|---|---|
received |
info | このイベントはpostFeedbackAPIを使用してTwilioにフィードバックを投稿した際に記録されます。 イベントにはユーザーによってつけられた事象名 (issue-name) および 品質スコア (quality-score) を含みます。 |
received-none |
info | このイベントはパラメーターを伴わずにpostFeedback APIを呼び出した場合に記録されます。 このイベントは、ユーザーにフィードバックを促したもののユーザーによってフィードバックの送信が辞退された場合に使用されます。 |
Registration events (Android & iOS SDKs only)
| EventName | イベントレベル | 概要 |
|---|---|---|
registration |
info | Raised when the client identity is registered. |
unregistration |
info | Raised when the client identity is unregistered. |
Network Information events (JS SDK only)
| EventName | イベントレベル | 概要 |
|---|---|---|
network-change |
info | Experimental feature: https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation |
ヘルプが必要ですか？
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.