統一通話記錄

VoIP 應用程式可將通話整合至系統通話記錄。這樣一來，使用者就能在系統撥號器應用程式中集中查看 VoIP 通話記錄，並直接從撥號器應用程式回撥電話。本指南說明VoIP 通話應用程式和系統撥號器應用程式的必要變更。

通話應用程式的變更

如要將 VoIP 應用程式與系統通話記錄整合，請按照下列步驟操作。

註冊回呼意圖篩選器

註冊受系統保護的意圖 TelecomManager.ACTION_CALL_BACK。

正確註冊這個意圖篩選器後，系統就會自動記錄應用程式使用 CallsManager.addCall 或其他相關 Telecom API 新增的任何呼叫。使用者在撥號器中選取 VoIP 通話記錄項目來回撥電話時，系統會使用這個已註冊的意圖，稍後將回呼傳送至您的應用程式。

<!-- Activity to handle the callback intent from the system dialer -->
<activity
    android:name=".VoipCallActivity"
    android:exported="true">

    <!-- Register callback intent -->
    <intent-filter>
        <action android:name="android.telecom.action.CALL_BACK" />
    </intent-filter>
</activity>AndroidManifest.xml

排除通話記錄

註冊回呼後，所有通話都會記錄在系統撥號程式中。如要逐一排除通話，請在 CallAttributesCompat 中將 isLogExcluded 布林值設為 true。

CallAttributesCompat(
    displayName = displayName,
    address = address,
    isLogExcluded = excludeCallLogging, // to exclude call from logging
    direction = if (isIncoming) {
        CallAttributesCompat.DIRECTION_INCOMING
    } else {
        CallAttributesCompat.DIRECTION_OUTGOING
    },
    callType = CallAttributesCompat.CALL_TYPE_AUDIO_CALL,
    callCapabilities = (
        CallAttributesCompat.SUPPORTS_SET_INACTIVE
            or CallAttributesCompat.SUPPORTS_STREAM
            or CallAttributesCompat.SUPPORTS_TRANSFER
        ),
)VoipCallActivity.kt

處理回呼

透過 CallsManager.addCall 新增的呼叫會透過 CallControlScope.getCallId 取得專屬 UUID。

// check the intent action for CALL_BACK
if (intent.action == TelecomManager.ACTION_CALL_BACK) {
    launchCall(
        // fetching stored call details for the UUID to initiate callback
        callDetails = getCallDetails(
            uuid = intent.getStringExtra(TelecomManager.EXTRA_UUID)
        )
    )
}VoipCallActivity.kt

驗證通話記錄項目

系統通話記錄會保留有限數量的項目，並在一段時間後清除舊的通話記錄。由於應用程式會儲存 UUID 對應的回呼處理呼叫詳細資料，因此應定期檢查系統通話記錄中仍有哪些 UUID。如果系統記錄中不再有 UUID，使用者就無法啟動該通話的回呼，應用程式也可以安全地從本機儲存空間移除對應。這項做法有助於最佳化儲存空間。

如要取得系統記錄中目前歸因於應用程式的 UUID 清單，請使用 CallLog.Calls.CONTENT_VOIP_URI。

撥號應用程式異動

請按照下列步驟操作，讓撥號應用程式顯示 VoIP 通話記錄，並向 VoIP 應用程式發起回撥。

在撥號應用程式中顯示 VoIP 通話記錄

根據預設，撥號應用程式不會顯示 VoIP 應用程式的通話記錄。如要在撥號應用程式中顯示整合的通話記錄，請按照下列步驟操作：

在 Android 16.1 (API 級別 36.1) 中，將查詢參數 include_voip_calls 附加至 CallLog.Calls 內容供應器，即可顯示 VoIP 通話記錄：
```
CallLog.Calls.CONTENT_URI.buildUpon()
    .appendQueryParameter("include_voip_calls", "true")
    .build()DialerActivity.kt
```
在 Android 17 (API 級別 37) 以上版本，請使用下列正式內容供應器和參數鍵：
- CallLog.Calls.CONTENT_URI_WITH_VOIP_CALLS
- CallLog.Calls.INCLUDE_VOIP_CALLS_PARAM_KEY

透過撥號應用程式發起回撥

如要從撥號器啟動回呼，請使用 TelecomManager.placeCall。平台會使用通話記錄項目的專屬 CallLog.Calls._ID 啟動正確的 VoIP 應用程式。啟動作業會包含 TelecomManager.ACTION_CALL_BACK 意圖，這是系統定義的動作，用於發起回撥電話。這個意圖會在意圖額外內容 TelecomManager.EXTRA_UUID 中包含通話的 UUID，讓 VoIP 應用程式識別要回撥的特定通話。

// Uri generated with unique ID of the call log entry to launch the respective VoIP app for callback
val address = ContentUris.withAppendedId(CallLog.Calls.CONTENT_URI, callId)

// extra information required to initiate callback
val extras = Bundle()

telecomManager.placeCall(address, extras)DialerActivity.kt