引言
Telegram Bot API为开发者提供了丰富的交互能力，其中发送联系人功能（sendContact）允许机器人向用户或群组发送联系人卡片，便于交换电话号码、姓名甚至完整的vCard信息。无论是构建商务工具、社交助手还是简单的电话簿机器人，掌握sendContact的参数都至关重要。本文将从参数含义到实际代码，全方位剖析这个API。
什么是sendContact方法？
sendContact是Telegram Bot API中的一个方法，用于向指定聊天发送一个联系人卡片。该卡片在Telegram客户端中会显示为可点击的按钮，用户点击后可以查看联系人详情或直接添加。与普通文本消息不同，它结构化地传递了电话和姓名信息，大大提升了机器人的实用性。
sendContact方法的完整参数列表
sendContact方法的参数主要分为两类：联系人专属参数和通用消息参数。下面先介绍联系人专属参数，再简要说明通用参数。
联系人专属参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
| chat_id | Integer 或 String | 是 | 接收消息的聊天ID，可以是用户ID、群组ID或频道用户名（@channelusername）。 |
| phone_number | String | 是 | 联系人的电话号码，建议使用国际格式（+号+国家码），例如 +8613800138000。 |
| first_name | String | 是 | 联系人的名字（名）。 |
| last_name | String | 否 | 联系人的姓氏（姓），若不需要可省略。 |
| vcard | String | 否 | 完整的vCard字符串，最多2048字节，用于提供更丰富的联系人信息（如公司、邮箱、头像等）。若提供此参数，客户端会优先展示vCard内容。 |
通用消息参数
除了上述专属参数，sendContact还支持以下常用参数，用于控制消息的发送行为：
- disable_notification：(Boolean，可选) 为True时，发送的消息不触发通知，适用于静默发送。
- protect_content：(Boolean，可选) 为True时，禁止接收者转发或保存该消息。
- reply_to_message_id：(Integer，可选) 要回复的消息ID。
- reply_markup：(InlineKeyboardMarkup 或 ReplyKeyboardMarkup，可选) 附加自定义键盘或内联键盘。
参数详解与使用场景
理解每个参数的实际含义，能帮你避免踩坑并设计出更专业的机器人。
chat_id：精准定位聊天对象
chat_id是必填参数，它指定联系人卡片发送到的位置。对于用户，常见格式为纯数字ID（如123456789）；对于群组或频道，可以是负ID（如 -1001234567890）或公共频道的@用户名（如 @my_channel）。注意，如果聊天是频道，需要先让Bot成为频道管理员。
phone_number：标准化存储
phone_number必须是有效的字符串。虽然API并不强制要求“+”，但为了跨地区识别，强烈建议使用国际格式（如 +86 10 8888 8888，但通常不带空格）。出于隐私保护，避免发送不含区号的本地号码。
first_name 与 last_name：显示名的学问
first_name为必填，last_name可选。在Telegram客户端，联系人会显示为“first_name last_name”的顺序（英文习惯是名在前，姓在后）。如果只想显示单字或昵称，可以只填first_name，省去last_name。
vcard：发送完整数字名片
vCard是一种广泛使用的电子名片格式，支持姓名、电话、邮箱、公司、地址甚至头像等字段。当你需要传递结构化信息时，优先使用vCard。但要注意，Telegram对vCard字符串的长度限制为2048字节，超过会返回错误。构建vCard时，建议使用标准格式（vCard 3.0或4.0），并注意转义特殊字符。
代码示例：使用Python发送联系人
下面用Python的requests库演示如何调用sendContact方法。假设你已经有了Bot Token（可通过BotFather获取）。
import requests
# Bot Token
TOKEN = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
chat_id = "123456789"
phone_number = "+8613800138000"
first_name = "张三"
last_name = "李四"
url = f"https://api.telegram.org/bot/sendContact"
payload = {
"chat_id": chat_id,
"phone_number": phone_number,
"first_name": first_name,
"last_name": last_name,
"protect_content": True # 可选
}
response = requests.post(url, json=payload)
print(response.json())
若需要发送vCard，只需在payload中加入vcard字段：
vcard = "BEGIN:VCARD\nVERSION:3.0\nFN:张三\nTEL:+8613800138000\nEND:VCARD"
payload["vcard"] = vcard
代码示例：使用curl发送联系人
如果你习惯用命令行，curl是快速测试API的利器。
curl -X POST https://api.telegram.org/bot<TOKEN>/sendContact \
-H "Content-Type: application/json" \
-d '{"chat_id": "123456789", "phone_number": "+8613800138000", "first_name": "张三"}'
将<TOKEN>替换为你的Bot Token即可。
常见问题与最佳实践
1. phone_number需要加“+”吗？
虽然不加强制，但为了国际通用性和避免歧义，强烈建议拨打格式使用“+”开头。例如 +86 10 88888888。同时，号码中不要包含空格或短横线，Telegram会将其作为纯字符串处理。
2. vCard如何构造？
vCard需遵循vCard标准。最简单的vCard如下：
BEGIN:VCARD
VERSION:3.0
N:张;三;;;
FN:张三
TEL;TYPE=CELL:+8613800138000
END:VCARD注意字段中的换行符必须使用真正的换行（\n），而不是字面量“\n”。构建完成后，建议在Telegram客户端进行测试。
3. 发送联系人失败有哪些常见原因？
- chat_id无效：Bot没有该用户或群的访问权，或ID格式错误。
- phone_number格式不合法：过长的号码或非法字符。
- first_name为空：必填参数缺失。
- vCard格式错误或过大：超过2048字节或缺少必需字段。
- Bot未初始化：或Token无效。
4. 最佳实践：保护用户隐私
发送联系人涉及个人数据，务必遵守当地隐私法规。建议仅在用户明确请求时发送，并考虑使用“protect_content”参数防止转发，降低滥用风险。
总结
sendContact是Telegram Bot中功能明确且实用的API，通过合理使用phone_number、first_name、last_name和vcard，你可以快速实现联系人分享、名片传递等场景。本文从参数到代码完整演示，希望能帮助你在开发中少走弯路。记住，参数的细节决定体验的优劣，多测试多验证，你的Bot会更强大。