Telegram CRM 联系人丰富化：将注册数据添加到联系人记录

销售和 CRM 团队如何通过 API 调用或批量 result.csv 导入，将 Telegram 注册字段（以及可选的用户名和近似活跃度数据）添加到现有联系人记录中。

Telegram CRM 联系人丰富化是指将与 Telegram 相关的字段添加到您现有的联系人记录中，最常见的是为每个电话号码添加带日期的 Telegram 注册状态。借助 TG Validator，可以通过同步响应 API 检查新联系人或已编辑的联系人，同时可以通过运行批量任务并导入其 result.csv 来回填现有数据库。生成的字段最适合作为除许可和互动数据之外的路由信号，而非对联系人的最终判定。

Telegram CRM 联系人丰富化涵盖的内容

针对此关键词的搜索结果大多描述的是围绕 Telegram 对话构建的 CRM：即那些将聊天记录同步到销售流程并将消息历史记录附加到交易中的工具。当销售团队已经在 Telegram 上与潜在客户沟通时，这非常有用，但对于拥有数千条基于电话的记录并希望在规划任何渠道之前了解其中哪些拥有 Telegram 账号的团队来说，这并无帮助。

本指南涵盖了第二种情况：使用一小组带日期的字段来丰富您现有的记录。它不涉及读取聊天记录、联系人、群组或私人资料内容。丰富化回答了以下具体问题：

• 该电话号码在检查时是否拥有 Telegram 账号？
• 如果团队运行批量活跃度任务，返回了什么用户名和自上次活跃以来的近似天数？
• 该信息是何时产生的，以及通过什么工作流产生的？

将范围保持在如此狭窄的程度，使得数据更容易向销售代表解释、更容易刷新，也更容易根据数据保护规则进行合规说明。

在进行任何检查前设计 CRM 字段

在运行第一次检查之前，请决定结果将存放在哪里。预先规划好的字段设计可以避免产生以后无法筛选的自由文本备注。

两个设计选择在后期会带来回报。首先，将“未检查”和“无法判定”作为与“未注册”不同的值保留；合并它们会掩盖那些仅仅需要再次尝试的记录。其次，当 CRM 被那些会将数字解读为精确值的用户使用时，存储一个活跃度区间而不是原始天数。activedays 是近似值，因此区间可以传达出适当的置信度水平。

先规范化电话号码

丰富化的质量取决于电话字段，而非检查本身。单号码检查接受一个 E.164 号码：一个加号、国家代码和国家号码，不含空格、标点符号或主干前缀。CRM 电话字段通常包含本地格式（如 07700 900123）、分机号或一个单元格内包含两个号码的情况。

一个实用的顺序：

1. 将电话字段复制到工作列，而不是覆盖原始字段。
2. 使用解析库（如 Google 的 libphonenumber）将每个值转换为 E.164，并使用记录的国家/地区作为默认区域。
3. 标记解析失败的值，并将其 Telegram 字段保留为“未检查”。
4. 对规范化后的号码进行去重，以确保同一个电话号码不会因为重复的联系人而被检查多次。

此步骤还决定了哪些记录进入哪些批量文件，因为电话号码批量任务是为选定的一个国家/地区创建的。

路径 A：针对新联系人和已更新联系人的 API 丰富化

对于由表单、导入或销售代表创建的记录，同步响应 REST API 可以自然地融入 CRM 工作流或中间件步骤中。

• 单个联系人： 将规范化后的号码发送至 POST /api/v1/check，并附带 X-API-Key 标头和服务类型 tg。响应会在同一会话中到达，因此工作流可以立即写入 Telegram 注册字段。
• 小组： POST /api/v1/batch-check 在一次请求中最多接受 100 个号码，这适用于处理当天已更改联系人的夜间作业。
• 无法判定的检查： 无法判定的检查会返回非零业务代码且没有完整结果。请写入“无法判定”及日期，并稍后重试，而不是记录为负面值。

当前的 API 文档描述了每用户并发和超时控制：同时进行 5 次检查，单次检查超时为 60 秒，多次检查超时为 300 秒，且每个账户一次只能进行一次多次检查。遵守这些限制并对超时进行退避的队列可以避免错误突发。目前没有发布每分钟请求速率限制，因此集成应遵循文档记录的控制措施，而不是假设的速率。无论结果是正面还是负面，每次完成的检查都会计费，因此仅在电话字段实际更改时触发检查可以使使用量与实际编辑保持一致。

路径 B：使用 result.csv 导入回填现有记录

对于大型现有数据库，异步批量任务更合适。这是一种上传-等待-下载的工作流，与同步响应 API 分开。

1. 导出一个国家/地区的规范化电话号码，连同 CRM 的唯一记录键，放入工作表中。
2. 构建上传文件，每行一个电话号码（TXT 或 CSV），不包含其他列。
3. 选择服务。 tg_batch 仅返回注册状态。tg_active_batch 添加用户名、数字 Telegram 用户标识符和 activedays，这支持活跃度区间。在不需要活跃度时，请选择较小的服务。
4. 提交并轮询，通过仪表板的“批量检查”区域或 POST /api/v1/bulk-tasks 进行，然后每 30 秒最多检查一次 GET /api/v1/bulk-tasks/{id}。
5. 下载 result.csv，当任务报告成功时。它包含标识符和 activated 列以及特定于服务的列，其中一些可能为空。
6. 将 result.csv 连接到工作表上的电话号码，以便每一行恢复其 CRM 记录键。
7. 作为更新导入。 例如，在 HubSpot 中，导入通过唯一标识符匹配现有记录，例如记录键或电子邮件，“仅更新现有项”选项可防止导入创建新联系人。

号码未包含在任务中的记录将保留为“未检查”，这使得覆盖范围的差距在报告中清晰可见。

将 Telegram 丰富化作为路由信号

一旦字段存在，它们就可以为列表视图、工作流和代表队列提供信息。典型用途包括：

• 渠道规划： 构建一个包含 Telegram 注册结果为“已注册”且拥有 Telegram 外联记录许可的联系人视图，并将其他记录保留在电子邮件或电话序列中。
• 数据质量报告： 按来源跟踪“未检查”或“无法判定”记录的份额，这通常会揭示出收集格式错误号码的表单。
• 优先处理跟进： 将活跃度区间与 CRM 互动历史相结合，以便在长期沉寂且近期无回复的账户收到下一个序列步骤之前对其进行审查。

注册字段是检查时的账户存在信号。它为路由提供信息，但不确定是谁在使用该账户，联系人是否同意接收 Telegram 消息，或者他们是否会回复。因此，工作流应将其与团队已维护的许可字段配对，而不是将其视为许可本身。

保持丰富化字段随时间的准确性

丰富化数据会老化。人们会更换号码，Telegram 会在用户可调整的非活跃期后删除账户。GDPR 第 5 条要求个人数据仅限于必要范围，并保持准确，必要时进行更新，这在 CRM 术语中转化为以下几种习惯：

• 更改时刷新： 当电话字段被编辑时自动重新检查。
• 按计划刷新： 在大型活动之前或针对仍处于活跃流程中的记录按固定周期重新运行批量任务。
• 过期旧值： 一旦检查日期超过团队选择的有效期，工作流可以将注册字段重置为“未检查”。
• 减少收集： 除非有记录在案的流程使用它们，否则请跳过头像和个人资料估计；tg_profile_batch 的年龄、性别和肤色值是估计值，而非已验证的身份。

仪表板检查历史记录和使用情况报告有助于协调 CRM 显示的内容与实际检查的内容。测试该设置的团队可以在注册后联系支持团队以获得 100 次免费检查，当前计划列在 定价页面上。

常见问题解答

团队如何在不同步聊天记录的情况下将 Telegram 数据添加到 CRM 联系人中？

使用同步响应 API 检查每个联系人的规范化电话号码，或运行批量任务并导入其 result.csv，然后将结果写入带有检查日期的专用 Telegram 注册字段。此过程不涉及任何聊天记录或联系人列表。

哪种 TG Validator 服务适合一次性 CRM 回填？

当仅需要注册状态时，tg_batch 最合适。当团队还需要用户名和自上次活跃以来的近似天数以用于活跃度区间时，tg_active_batch 最合适。两者均作为每个电话文件针对选定国家/地区的异步文件任务运行。

当检查无法判定时，CRM 应该记录什么？

无法判定的检查会返回非零业务代码，而不是完整结果。请存储一个单独的值，例如带有日期的“无法判定”，并稍后重试，这样记录就不会被误认为是未拥有 Telegram 的联系人。

Telegram 丰富化字段应该多久刷新一次？

每当电话号码更改时进行刷新，并在大型活动之前或针对仍在使用中的记录按常规周期重新运行检查。在选择的有效期后使旧值过期，可以防止报告依赖过时的结果。

了解更多

选择适合您工作流下一步的产品信息。

• 查看产品文档 →
• 联系团队 →