telnyx-voice-media-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx Voice Media - Python

Telnyx 语音媒体 - Python

Installation

安装

bash

pip install telnyx

bash

pip install telnyx

Setup

配置

python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)

All examples below assume

client

is already initialized as shown above.

python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # 这是默认配置，可以省略
)

以下所有示例均假设

client

已按上述方式完成初始化。

Error Handling

错误处理

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

python

import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
    # 429: rate limited — wait and retry with exponential backoff
    import time
    time.sleep(1)  # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("Validation error — check required fields and formats")

Common error codes:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

所有API调用都可能出现网络错误、速率限制(429)、校验错误(422)或鉴权错误(401)。在生产代码中请始终做好错误处理：

python

import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("网络错误 — 检查网络连接后重试")
except telnyx.RateLimitError:
    # 429: 触发速率限制 — 等待后采用指数退避策略重试
    import time
    time.sleep(1)  # 可查看Retry-After响应头获取实际需要等待的时长
except telnyx.APIStatusError as e:
    print(f"API错误 {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("校验错误 — 检查必填字段和格式是否正确")

常见错误码：

无效API密钥、

权限不足、

资源不存在、

校验错误（检查字段格式）、

触发速率限制（使用指数退避策略重试）。

Play audio URL

播放音频URL

Play an audio file on the call. If multiple play audio commands are issued consecutively, the audio files will be placed in a queue awaiting playback. Notes:

When
```
overlay
```
is enabled,
```
target_legs
```
is limited to
```
self
```
.

POST /calls/{call_control_id}/actions/playback_start

Optional:

audio_type

(enum: mp3, wav),

audio_url

(string),

cache_audio

(boolean),

client_state

(string),

command_id

(string),

loop

(string),

media_name

(string),

overlay

(boolean),

playback_content

(string),

stop

(string),

target_legs

(string)

python

response = client.calls.actions.start_playback(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    audio_url="https://example.com/audio.mp3",
)
print(response.data)

Returns:

result

(string)

在通话中播放音频文件。如果连续发出多个播放音频的命令，音频文件将进入队列等待播放。注意：

当开启
```
overlay
```
时，
```
target_legs
```
仅支持设置为
```
self
```
。

POST /calls/{call_control_id}/actions/playback_start

可选参数：

audio_type

(枚举值: mp3, wav),

audio_url

(字符串),

cache_audio

(布尔值),

client_state

(字符串),

command_id

(字符串),

loop

(字符串),

media_name

(字符串),

overlay

(布尔值),

playback_content

(字符串),

stop

(字符串),

target_legs

(字符串)

python

response = client.calls.actions.start_playback(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    audio_url="https://example.com/audio.mp3",
)
print(response.data)

返回值：

result

(字符串)

Stop audio playback

停止音频播放

Stop audio being played on the call. Expected Webhooks:

```
call.playback.ended
```
or
```
call.speak.ended
```

POST /calls/{call_control_id}/actions/playback_stop

Optional:

client_state

(string),

command_id

(string),

overlay

(boolean),

stop

(string)

python

response = client.calls.actions.stop_playback(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns:

result

(string)

停止通话中正在播放的音频。预期触发的Webhook：

```
call.playback.ended
```
或
```
call.speak.ended
```

POST /calls/{call_control_id}/actions/playback_stop

可选参数：

client_state

(字符串),

command_id

(字符串),

overlay

(布尔值),

stop

(字符串)

python

response = client.calls.actions.stop_playback(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

返回值：

result

(字符串)

Record pause

暂停录制

Pause recording the call. Recording can be resumed via Resume recording command. Expected Webhooks:

There are no webhooks associated with this command.

POST /calls/{call_control_id}/actions/record_pause

Optional:

client_state

(string),

command_id

(string),

recording_id

(uuid)

python

response = client.calls.actions.pause_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns:

result

(string)

暂停通话录制。可通过恢复录制命令恢复录制。预期触发的Webhook：

该命令没有关联的Webhook。

POST /calls/{call_control_id}/actions/record_pause

可选参数：

client_state

(字符串),

command_id

(字符串),

recording_id

(uuid)

python

response = client.calls.actions.pause_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

返回值：

result

(字符串)

Record resume

恢复录制

Resume recording the call. Expected Webhooks:

There are no webhooks associated with this command.

POST /calls/{call_control_id}/actions/record_resume

Optional:

client_state

(string),

command_id

(string),

recording_id

(uuid)

python

response = client.calls.actions.resume_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns:

result

(string)

恢复通话录制。预期触发的Webhook：

该命令没有关联的Webhook。

POST /calls/{call_control_id}/actions/record_resume

可选参数：

client_state

(字符串),

command_id

(字符串),

recording_id

(uuid)

python

response = client.calls.actions.resume_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

返回值：

result

(字符串)

Recording start

开始录制

Start recording the call. Recording will stop on call hang-up, or can be initiated via the Stop Recording command. Expected Webhooks:

```
call.recording.saved
```
```
call.recording.transcription.saved
```
```
call.recording.error
```

POST /calls/{call_control_id}/actions/record_start

— Required:

format

channels

Optional:

client_state

(string),

command_id

(string),

custom_file_name

(string),

max_length

(int32),

play_beep

(boolean),

recording_track

(enum: both, inbound, outbound),

timeout_secs

(int32),

transcription

(boolean),

transcription_engine

(enum: A, B, deepgram/nova-3),

transcription_language

(enum: af, af-ZA, am, am-ET, ar, ar-AE, ar-BH, ar-DZ, ar-EG, ar-IL, ar-IQ, ar-JO, ar-KW, ar-LB, ar-MA, ar-MR, ar-OM, ar-PS, ar-QA, ar-SA, ar-TN, ar-YE, as, auto_detect, az, az-AZ, ba, be, bg, bg-BG, bn, bn-BD, bn-IN, bo, br, bs, bs-BA, ca, ca-ES, cs, cs-CZ, cy, da, da-DK, de, de-AT, de-CH, de-DE, el, el-GR, en, en-AU, en-CA, en-GB, en-GH, en-HK, en-IE, en-IN, en-KE, en-NG, en-NZ, en-PH, en-PK, en-SG, en-TZ, en-US, en-ZA, es, es-419, es-AR, es-BO, es-CL, es-CO, es-CR, es-DO, es-EC, es-ES, es-GT, es-HN, es-MX, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, es-VE, et, et-EE, eu, eu-ES, fa, fa-IR, fi, fi-FI, fil-PH, fo, fr, fr-BE, fr-CA, fr-CH, fr-FR, gl, gl-ES, gu, gu-IN, ha, haw, he, hi, hi-IN, hr, hr-HR, ht, hu, hu-HU, hy, hy-AM, id, id-ID, is, is-IS, it, it-CH, it-IT, iw-IL, ja, ja-JP, jv-ID, jw, ka, ka-GE, kk, kk-KZ, km, km-KH, kn, kn-IN, ko, ko-KR, la, lb, ln, lo, lo-LA, lt, lt-LT, lv, lv-LV, mg, mi, mk, mk-MK, ml, ml-IN, mn, mn-MN, mr, mr-IN, ms, ms-MY, mt, my, my-MM, ne, ne-NP, nl, nl-BE, nl-NL, nn, no, no-NO, oc, pa, pa-Guru-IN, pl, pl-PL, ps, pt, pt-BR, pt-PT, ro, ro-RO, ru, ru-RU, rw-RW, sa, sd, si, si-LK, sk, sk-SK, sl, sl-SI, sn, so, sq, sq-AL, sr, sr-RS, ss-latn-za, st-ZA, su, su-ID, sv, sv-SE, sw, sw-KE, sw-TZ, ta, ta-IN, ta-LK, ta-MY, ta-SG, te, te-IN, tg, th, th-TH, tk, tl, tn-latn-za, tr, tr-TR, ts-ZA, tt, uk, uk-UA, ur, ur-IN, ur-PK, uz, uz-UZ, ve-ZA, vi, vi-VN, xh-ZA, yi, yo, yue-Hant-HK, zh, zh-TW, zu-ZA),

transcription_max_speaker_count

(int32),

transcription_min_speaker_count

(int32),

transcription_profanity_filter

(boolean),

transcription_speaker_diarization

(boolean),

trim

(enum: trim-silence)

python

response = client.calls.actions.start_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    channels="single",
    format="wav",
)
print(response.data)

Returns:

result

(string)

开始通话录制。录制会在通话挂断时自动停止，也可以通过停止录制命令主动终止。预期触发的Webhook：

```
call.recording.saved
```
```
call.recording.transcription.saved
```
```
call.recording.error
```

POST /calls/{call_control_id}/actions/record_start

— 必填参数：

format

channels

可选参数：

client_state

(字符串),

command_id

(字符串),

custom_file_name

(字符串),

max_length

(int32),

play_beep

(布尔值),

recording_track

(枚举值: both, inbound, outbound),

timeout_secs

(int32),

transcription

(布尔值),

transcription_engine

(枚举值: A, B, deepgram/nova-3),

transcription_language

(枚举值: af, af-ZA, am, am-ET, ar, ar-AE, ar-BH, ar-DZ, ar-EG, ar-IL, ar-IQ, ar-JO, ar-KW, ar-LB, ar-MA, ar-MR, ar-OM, ar-PS, ar-QA, ar-SA, ar-TN, ar-YE, as, auto_detect, az, az-AZ, ba, be, bg, bg-BG, bn, bn-BD, bn-IN, bo, br, bs, bs-BA, ca, ca-ES, cs, cs-CZ, cy, da, da-DK, de, de-AT, de-CH, de-DE, el, el-GR, en, en-AU, en-CA, en-GB, en-GH, en-HK, en-IE, en-IN, en-KE, en-NG, en-NZ, en-PH, en-PK, en-SG, en-TZ, en-US, en-ZA, es, es-419, es-AR, es-BO, es-CL, es-CO, es-CR, es-DO, es-EC, es-ES, es-GT, es-HN, es-MX, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, es-VE, et, et-EE, eu, eu-ES, fa, fa-IR, fi, fi-FI, fil-PH, fo, fr, fr-BE, fr-CA, fr-CH, fr-FR, gl, gl-ES, gu, gu-IN, ha, haw, he, hi, hi-IN, hr, hr-HR, ht, hu, hu-HU, hy, hy-AM, id, id-ID, is, is-IS, it, it-CH, it-IT, iw-IL, ja, ja-JP, jv-ID, jw, ka, ka-GE, kk, kk-KZ, km, km-KH, kn, kn-IN, ko, ko-KR, la, lb, ln, lo, lo-LA, lt, lt-LT, lv, lv-LV, mg, mi, mk, mk-MK, ml, ml-IN, mn, mn-MN, mr, mr-IN, ms, ms-MY, mt, my, my-MM, ne, ne-NP, nl, nl-BE, nl-NL, nn, no, no-NO, oc, pa, pa-Guru-IN, pl, pl-PL, ps, pt, pt-BR, pt-PT, ro, ro-RO, ru, ru-RU, rw-RW, sa, sd, si, si-LK, sk, sk-SK, sl, sl-SI, sn, so, sq, sq-AL, sr, sr-RS, ss-latn-za, st-ZA, su, su-ID, sv, sv-SE, sw, sw-KE, sw-TZ, ta, ta-IN, ta-LK, ta-MY, ta-SG, te, te-IN, tg, th, th-TH, tk, tl, tn-latn-za, tr, tr-TR, ts-ZA, tt, uk, uk-UA, ur, ur-IN, ur-PK, uz, uz-UZ, ve-ZA, vi, vi-VN, xh-ZA, yi, yo, yue-Hant-HK, zh, zh-TW, zu-ZA),

transcription_max_speaker_count

(int32),

transcription_min_speaker_count

(int32),

transcription_profanity_filter

(布尔值),

transcription_speaker_diarization

(布尔值),

trim

(枚举值: trim-silence)

python

response = client.calls.actions.start_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    channels="single",
    format="wav",
)
print(response.data)

返回值：

result

(字符串)

Recording stop

停止录制

Stop recording the call. Expected Webhooks:

```
call.recording.saved
```

POST /calls/{call_control_id}/actions/record_stop

Optional:

client_state

(string),

command_id

(string),

recording_id

(uuid)

python

response = client.calls.actions.stop_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns:

result

(string)

停止通话录制。预期触发的Webhook：

```
call.recording.saved
```

POST /calls/{call_control_id}/actions/record_stop

可选参数：

client_state

(字符串),

command_id

(字符串),

recording_id

(uuid)

python

response = client.calls.actions.stop_recording(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

返回值：

result

(字符串)

Speak text

文本播报

Convert text to speech and play it back on the call. If multiple speak text commands are issued consecutively, the audio files will be placed in a queue awaiting playback. Expected Webhooks:

```
call.speak.started
```
```
call.speak.ended
```

POST /calls/{call_control_id}/actions/speak

— Required:

payload

voice

Optional:

client_state

(string),

command_id

(string),

language

(enum: arb, cmn-CN, cy-GB, da-DK, de-DE, en-AU, en-GB, en-GB-WLS, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, is-IS, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sv-SE, tr-TR),

loop

(string),

payload_type

(enum: text, ssml),

service_level

(enum: basic, premium),

stop

(string),

target_legs

(enum: self, opposite, both),

voice_settings

(object)

python

response = client.calls.actions.speak(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    payload="Say this on the call",
    voice="female",
    language="en-US",
)
print(response.data)

Returns:

result

(string)

将文本转换为语音并在通话中播放。如果连续发出多个文本播报命令，生成的音频将进入队列等待播放。预期触发的Webhook：

```
call.speak.started
```
```
call.speak.ended
```

POST /calls/{call_control_id}/actions/speak

— 必填参数：

payload

voice

可选参数：

client_state

(字符串),

command_id

(字符串),

language

(枚举值: arb, cmn-CN, cy-GB, da-DK, de-DE, en-AU, en-GB, en-GB-WLS, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, is-IS, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sv-SE, tr-TR),

loop

(字符串),

payload_type

(枚举值: text, ssml),

service_level

(枚举值: basic, premium),

stop

(字符串),

target_legs

(枚举值: self, opposite, both),

voice_settings

(对象)

python

response = client.calls.actions.speak(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    payload="Say this on the call",
    voice="female",
    language="en-US",
)
print(response.data)

返回值：

result

(字符串)

Webhooks

Webhook Verification

Webhook 验证

Telnyx signs webhooks with Ed25519. Each request includes

telnyx-signature-ed25519

and

telnyx-timestamp

headers. Always verify signatures in production:

python

undefined

Telnyx使用Ed25519对Webhook进行签名。每个请求都会携带

telnyx-signature-ed25519

和

telnyx-timestamp

请求头。在生产环境中请始终验证签名：

python

undefined

In your webhook handler (e.g., Flask — use raw body, not parsed JSON):

在你的Webhook处理逻辑中（例如Flask — 使用原始请求体，不要使用解析后的JSON）:

@app.route("/webhooks", methods=["POST"]) def handle_webhook(): payload = request.get_data(as_text=True) # raw body as string headers = dict(request.headers) try: event = client.webhooks.unwrap(payload, headers=headers) except Exception as e: print(f"Webhook verification failed: {e}") return "Invalid signature", 400 # Signature valid — event is the parsed webhook payload print(f"Received event: {event.data.event_type}") return "OK", 200


The following webhook events are sent to your configured webhook URL.
All webhooks include `telnyx-timestamp` and `telnyx-signature-ed25519` headers for Ed25519 signature verification. Use `client.webhooks.unwrap()` to verify.

| Event | Description |
|-------|-------------|
| `callPlaybackEnded` | Call Playback Ended |
| `callPlaybackStarted` | Call Playback Started |
| `callRecordingError` | Call Recording Error |
| `callRecordingSaved` | Call Recording Saved |
| `callRecordingTranscriptionSaved` | Call Recording Transcription Saved |
| `callSpeakEnded` | Call Speak Ended |
| `callSpeakStarted` | Call Speak Started |

@app.route("/webhooks", methods=["POST"]) def handle_webhook(): payload = request.get_data(as_text=True) # 字符串格式的原始请求体 headers = dict(request.headers) try: event = client.webhooks.unwrap(payload, headers=headers) except Exception as e: print(f"Webhook验证失败: {e}") return "Invalid signature", 400 # 签名有效 — event是解析后的Webhook payload print(f"收到事件: {event.data.event_type}") return "OK", 200


以下Webhook事件会发送到你配置的Webhook地址。所有Webhook都会携带`telnyx-timestamp`和`telnyx-signature-ed25519`请求头用于Ed25519签名验证，可使用`client.webhooks.unwrap()`方法完成验证。

| 事件 | 描述 |
|-------|-------------|
| `callPlaybackEnded` | 通话音频播放结束 |
| `callPlaybackStarted` | 通话音频播放开始 |
| `callRecordingError` | 通话录制错误 |
| `callRecordingSaved` | 通话录制已保存 |
| `callRecordingTranscriptionSaved` | 通话录制转写结果已保存 |
| `callSpeakEnded` | 通话文本播报结束 |
| `callSpeakStarted` | 通话文本播报开始 |

Webhook payload fields

Webhook payload 字段

callPlaybackEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.playback.ended	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.media_url`	string	The audio URL being played back, if audio_url has been used to start.
`data.payload.media_name`	string	The name of the audio media file being played back, if media_name has been used to start.
`data.payload.overlay`	boolean	Whether the stopped audio was in overlay mode or not.
`data.payload.status`	enum: file_not_found, call_hangup, unknown, cancelled, cancelled_amd, completed, failed	Reflects how command ended.
`data.payload.status_detail`	string	Provides details in case of failure.

callPlaybackStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.playback.started	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.media_url`	string	The audio URL being played back, if audio_url has been used to start.
`data.payload.media_name`	string	The name of the audio media file being played back, if media_name has been used to start.
`data.payload.overlay`	boolean	Whether the audio is going to be played in overlay mode or not.

callRecordingError

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.recording.error	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.reason`	enum: Failed to authorize with storage using custom credentials, Invalid credentials json, Unsupported backend, Internal server error	Indication that there was a problem recording the call.

callRecordingSaved

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.recording.saved	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.recording_started_at`	date-time	ISO 8601 datetime of when recording started.
`data.payload.recording_ended_at`	date-time	ISO 8601 datetime of when recording ended.
`data.payload.channels`	enum: single, dual	Whether recording was recorded in `single` or `dual` channel.

callRecordingTranscriptionSaved

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.recording.transcription.saved	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.calling_party_type`	enum: pstn, sip	The type of calling party connection.
`data.payload.recording_id`	string	ID that is unique to the recording session and can be used to correlate webhook events.
`data.payload.recording_transcription_id`	string	ID that is unique to the transcription process and can be used to correlate webhook events.
`data.payload.status`	enum: completed	The transcription status.
`data.payload.transcription_text`	string	The transcribed text

callSpeakEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.speak.ended	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.status`	enum: completed, call_hangup, cancelled_amd	Reflects how the command ended.

callSpeakStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.speak.started	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.

callPlaybackEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.playback.ended	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.client_state`	字符串	从命令中携带的状态信息
`data.payload.media_url`	字符串	正在播放的音频URL（如果是通过audio_url启动的播放）
`data.payload.media_name`	字符串	正在播放的音频媒体文件名（如果是通过media_name启动的播放）
`data.payload.overlay`	布尔值	停止的音频是否处于叠加模式
`data.payload.status`	枚举值: file_not_found, call_hangup, unknown, cancelled, cancelled_amd, completed, failed	命令结束的状态
`data.payload.status_detail`	字符串	失败场景下的详细说明

callPlaybackStarted

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.playback.started	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.client_state`	字符串	从命令中携带的状态信息
`data.payload.media_url`	字符串	正在播放的音频URL（如果是通过audio_url启动的播放）
`data.payload.media_name`	字符串	正在播放的音频媒体文件名（如果是通过media_name启动的播放）
`data.payload.overlay`	布尔值	音频是否采用叠加模式播放

callRecordingError

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.recording.error	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.client_state`	字符串	从命令中携带的状态信息
`data.payload.reason`	枚举值: Failed to authorize with storage using custom credentials, Invalid credentials json, Unsupported backend, Internal server error	通话录制出现问题的原因

callRecordingSaved

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.recording.saved	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.client_state`	字符串	从命令中携带的状态信息
`data.payload.recording_started_at`	date-time	录制开始的ISO 8601格式时间
`data.payload.recording_ended_at`	date-time	录制结束的ISO 8601格式时间
`data.payload.channels`	枚举值: single, dual	录制采用的是单声道还是双声道

callRecordingTranscriptionSaved

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.recording.transcription.saved	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.client_state`	字符串	从命令中携带的状态信息
`data.payload.calling_party_type`	枚举值: pstn, sip	主叫方连接类型
`data.payload.recording_id`	字符串	录制会话唯一ID，可用于关联Webhook事件
`data.payload.recording_transcription_id`	字符串	转写流程唯一ID，可用于关联Webhook事件
`data.payload.status`	枚举值: completed	转写状态
`data.payload.transcription_text`	字符串	转写得到的文本内容

callSpeakEnded

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.speak.ended	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.client_state`	字符串	从命令中携带的状态信息
`data.payload.status`	枚举值: completed, call_hangup, cancelled_amd	命令结束的状态

callSpeakStarted

字段	类型	描述
`data.record_type`	枚举值: event	标识资源类型
`data.event_type`	枚举值: call.speak.started	触发的事件类型
`data.id`	uuid	资源ID
`data.occurred_at`	date-time	事件发生的ISO 8601格式时间
`data.payload.call_control_id`	字符串	用于通过呼叫控制API下发命令的呼叫ID
`data.payload.connection_id`	字符串	通话使用的呼叫控制应用ID（原Telnyx连接ID）
`data.payload.call_leg_id`	字符串	通话唯一ID，可用于关联Webhook事件
`data.payload.call_session_id`	字符串	通话会话唯一ID，可用于关联Webhook事件
`data.payload.client_state`	字符串	从命令中携带的状态信息