Telynx API 主叫显示名称失效？问题排查及解决

2024-12-20 23:50:44

Telynx API “from_display_name” 字段失效问题解析及处理

在基于 Telynx API 构建呼叫系统中，开发者需要为外呼指定主叫号码及显示名称。通过合理配置这两个字段，被叫用户可以看到来电者的基本信息。Telynx 平台的 NodeJS SDK 中提供了 calls.create 方法创建呼叫，参数中 from_display_name 字段用于设置呼叫者显示名称，在某些应用场景下起着关键作用。然而部分开发者反馈该字段未能生效。

一、问题现象

通过 Telynx NodeJS SDK 发起呼叫时，from_display_name 属性设置后，被叫设备无法正确显示预设的呼叫者信息。即便设置有效值，该信息也无法在被叫的设备屏幕上体现，直接导致了功能设计与预期不符。

二、问题排查及潜在原因

在着手解决这个问题前，要对其潜在原因做出正确判断。通过细致分析，可将可能导致问题的原因大致分为三个方面。

1. Telynx 平台配置问题

Telynx 平台的相关服务可能配置存在问题，这些问题会阻止客户端设置成功传达到服务器，导致该功能失效。平台本身的特性与限制条件未能满足要求，将导致相应功能无法实现。因此需要重点排查三个方面：

号码配置问题。 所使用的电话号码可能没有正确配置该项功能，导致呼叫发起后，设置信息无法正常解析。
CNAM 设置错误。 Telynx 平台关于 Caller ID Name (CNAM) 的设置会影响号码名称显示。该项错误也会导致自定义名称无法传递。
平台功能变动。 平台自身存在调整或故障也会造成 API 无法正确响应客户端的请求，从而使相应功能暂时失效。

2. 客户端代码问题

开发者在使用 SDK 过程中代码编写有误，没有把 SDK 参数中的 from_display_name 与被叫用户端主叫姓名显示逻辑关联起来。比如变量填写不正确，没有正确使用 SDK 方法或者传参。此类失误将导致传入参数无效或直接被忽略。

3. 被叫运营商问题

被叫用户所属运营商的相关处理流程可能不支持主叫显示名信息展示。即使正确配置好全部设置，但由于运营商没有对应实现对呼叫人名称展示的支持，因此即便呼叫到达了目标用户的手机，呼叫者名称也无从显示。此为运营商侧问题。

三、解决方案

根据以上可能原因分析，需采取相应措施进行排查和验证。主要包括四个解决方案：

1. 确认 Telynx 号码和 CNAM 配置

首先需要检查 Telynx 账户中电话号码配置及 CNAM 服务设置。此步骤需要仔细检查。

操作步骤：

登录 Telynx 门户。
导航至“My Account”- “Phone Numbers”部分，找到要使用的号码。
确认此号码支持号码展示功能，检查 CNAM 设置状态是否正常。如果你的号码当前关闭了主叫 ID 名称显示，请务必启用它。此步操作必须且准确。

验证效果: 如果问题在于未启用显示名配置，上述配置能初步排除该问题。通过调整，可将可能的原因锁定到其它两个方向，方便下一步排查处理。

2. 验证 SDK 代码中参数设置

如果 Telynx 平台的配置正常，那么就需要仔细排查客户端代码，特别需要检查 SDK 中 from_display_name 属性的值设置，该参数在客户端的设置是否正确无误、参数是否为有效的字符串形式等等，是 SDK 使用排查重点，尤其需要重点关注 from_display_name 属性的动态值生成方式。

代码示例：

const telnyx = require('telnyx')('YOUR_TELNYX_API_KEY');

async function makeCall(customer, event) {
  try {
    const newCall = await telnyx.calls.create({
      connection_id: customer.telnyx_connection_id,
      to: customer.phone_number,
      from: customer.telnyx_phone_number,
      from_display_name: `Call from ${event.data.payload.from}`, // 确保这里的表达式正确生成所需字符串
      answering_machine_detection: 'premium'
    });
    console.log("Call created:", newCall.data);
  } catch (error) {
    console.error("Error creating call:", error);
  }
}

操作步骤：

审查代码中对 from_display_name 赋值部分。
确保该字段使用有效的字符串，且字符串生成逻辑能够正确反映要显示的内容。避免无效字符及编码错误等细节。
调试该段代码以输出确认该值内容符合预期。可在服务端运行态通过日志记录或中间件检测来获取真实有效的值。
将该 SDK 使用部分的关键变量及结果做记录并打印在控制台或记录至日志文件。检查日志输出结果。如果该值能正常传入且符合预期，这步操作能初步排除 SDK 使用不当问题。通过分析可以缩小排查方向到剩下的问题原因上。

安全建议： 务必替换 YOUR_TELNYX_API_KEY 为真实有效的值，并且需要确保API 密钥安全存放，避免泄露风险。安全第一，尤其是在使用云服务与云API时更应把数据安全保护放到第一位。密钥泄漏的风险需要妥善管理并予以严格保护，密钥权限管理非常关键。

3. 联系 Telynx 支持团队进行咨询

倘若号码配置和 SDK 使用都没有问题，仍然没有正确显示呼叫方姓名，这步可确认平台状态。可以直接联系 Telynx 支持团队进行更深层次的技术核查与分析支持。通过更直接的方式获取帮助。

操作步骤：

访问 Telynx 官方网站，找到“Support”或“Contact Us”等栏目。
准备好账号信息、号码、SDK 代码、出现问题的具体表现以及操作日志等详细信息，通过工单、电话等途径，与支持人员沟通，问题，寻求解决办法。通过更专业的人士提供支持。
根据客服人员指示提供相应信息以供排查，例如发起测试呼叫等，并查看后台具体运行信息与平台设置是否正确。此方法能确定平台自身服务功能是否存在故障以及问题发生大致范围。
咨询平台自身配置方面是否存在影响主叫名称显示的机制。与平台支持保持有效联系直到问题解决。通过专业人士介入，能够从后台确定更多问题可能性。

4. 使用其他方式传递标识信息

在被叫运营商不支持号码名展示的情形下，为了解决这个问题，就需要找到其它可行的技术方案来实现关键信息标识传递。此时可以利用一些替代方案，将主叫方标识传递到被叫方。

例如在 SIP Header 中传递标识信息:

通过在 SIP 头部中添加自定义字段的方式来实现此功能，可以借助 sip_headers 参数实现：

代码示例：

const telnyx = require('telnyx')('YOUR_TELNYX_API_KEY');

async function makeCall(customer, event) {
  try {
    const newCall = await telnyx.calls.create({
      connection_id: customer.telnyx_connection_id,
      to: customer.phone_number,
      from: customer.telnyx_phone_number,
      answering_machine_detection: 'premium',
      sip_headers: {
          "X-Custom-From-Name": event.data.payload.from
      }
    });
    console.log("Call created:", newCall.data);
  } catch (error) {
    console.error("Error creating call:", error);
  }
}

操作步骤：

确定要传递的标识信息及其格式。这些内容用于标识与业务逻辑相关的身份信息。
修改代码中发起呼叫的部分，设置好自定义的 SIP 头部。设置合理的数据结构来传递标识符。此方法可使业务信息有效通过SIP头传递到目的终端或业务服务器，可用来做进一步的数据展示应用开发提供信息支撑。
客户端与服务器端应用需解析接收到的 SIP 头部，获取有效信息，并基于有效信息实现对应显示和标识逻辑，例如业务系统中建立关联性机制以及号码名展示与逻辑。利用该方式实现与Telynx平台本身机制不一样的独立标识。
对使用了自定义头部后的功能做完整的功能测试和验收，确保它完全能够与原有的系统逻辑兼容。尤其是在多运营商对接处理中需要充分的单元测试和兼容性测试。保证服务对接的可靠性。

安全建议： 在使用 sip_headers 参数传递信息时需进行充分测试以确认信息的可靠传递，并注意安全与性能方面的保护，防范恶意攻击等行为。尤其要做好敏感信息的数据脱敏。确保所添加的信息正确且对数据脱敏与加密做好安全加固，避免暴露隐私或敏感内容，安全无小事，安全问题务必需要做妥善处置。