在Telegram机器人开发中，发送联系人名片是一个高频需求，尤其适用于名片交换、客户线索收集或用户信息快速录入等场景。通过官方Bot API，开发者可以轻松实现向用户或群组推送联系人卡片。本教程将带你从零掌握 sendContact 方法的完整用法，并提供可直接运行的代码示例。
前置准备：创建机器人与获取Token
在调用任何API之前，你需要先拥有一个机器人Token。具体步骤：
- 在Telegram中搜索 @BotFather，并发送
/newbot命令。 - 按提示设置机器人显示名称和唯一用户名（以
bot结尾）。 - 创建成功后，BotFather会返回一个HTTP API Token（如
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11），请妥善保存。
如果你的机器人已存在，可以通过 /mybots 查看或重新获取Token。
理解sendContact方法：核心API解析
Telegram Bot API中的 sendContact 方法用于发送联系人卡片。其官方参数如下：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| chat_id | Integer/String | 是 | 聊天标识，可以是用户ID或群组ID（支持@频道用户名） |
| phone_number | String | 是 | 联系人的电话号码 |
| first_name | String | 是 | 联系人的名字 |
| last_name | String | 否 | 联系人的姓氏 |
| vcard | String | 否 | 联系人完整vCard字符串，覆盖上述字段 |
| reply_markup | InlineKeyboardMarkup | 否 | 附加的按钮（如“添加联系人”） |
除此之外，还支持 reply_to_message_id 等通用参数。官方文档地址：https://core.telegram.org/bots/api#sendcontact。
完整代码示例：通过HTTP API发送联系人名片
下面分别使用Python和curl演示如何调用 sendContact。
Python示例（使用requests库）
import requests
TOKEN = "你的机器人Token"
chat_id = "用户或群组ID"
phone = "+86 138 0013 8000"
first_name = "张三"
last_name = "李四"
url = f"https://api.telegram.org/bot/sendContact"
payload = {
"chat_id": chat_id,
"phone_number": phone,
"first_name": first_name,
"last_name": last_name
}
resp = requests.post(url, json=payload)
print(resp.json())
curl示例
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendContact" \
-H "Content-Type: application/json" \
-d '{"chat_id":"<CHAT_ID>","phone_number":"+8613800138000","first_name":"张三","last_name":"李四"}'
执行后，用户会收到一张可点击的联系人卡片，点击即可保存到通讯录。
增加交互：附带按钮与自定义键盘
为了让名片更有用，你可以通过 reply_markup 添加内联按钮，例如“添加联系人”或“分享给好友”。下面是一个带按钮的Python示例：
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
# 需安装 python-telegram-bot 库
button = InlineKeyboardButton("添加联系人", callback_data="add_contact")
markup = InlineKeyboardMarkup([[button]])
bot.sendContact(
chat_id=chat_id,
phone_number=phone,
first_name=first_name,
last_name=last_name,
reply_markup=markup
)
如果你使用原生HTTP方式，则需要构造JSON格式的 reply_markup，例如：
"reply_markup": {"inline_keyboard": [[{"text": "添加联系人", "callback_data": "add"}]]}
常见问题与错误排查
开发中可能会遇到以下问题：
- 错误401 Unauthorized：Token错误或过期，请重新从BotFather获取。
- 错误400 Bad Request：参数格式不正确，例如
phone_number缺失、chat_id无效。 - 联系人名片无法保存：确保电话号码符合国际格式（建议带国家区号）。
- 按钮无响应：需配置回调处理逻辑，或者使用
url按钮打开外部链接。
安全与隐私注意事项
发送联系人名片涉及用户隐私，请务必遵守以下原则：
- 仅向用户主动请求授权后发送其联系人信息。
- 避免随意发送真实电话号码到公共群组，防止泄露。
- 使用vCard时，确保不包含多余敏感字段。
- 记录API调用日志时，隐藏完整电话号码，以保障安全。
总结
通过调用Telegram Bot API的 sendContact 方法，开发者可以在机器人中快速发送联系人名片。本文提供了完整的参数说明、代码示例和常见问题排查，帮助你规避陷阱。建议结合官方文档进行二次开发，并在测试环境中充分验证后再上线。