Telegram机器人如何发送Venue卡片（地点推荐）？从API参数到Python实战全解析

在Telegram机器人开发中，发送Venue地点推荐卡片是一项实用且高频的需求——无论是餐饮推荐、门店导航，还是活动位置分享，Venue卡片都能以结构化形式展示地点信息，并支持用户一键打开地图导航。本文将从Bot API底层参数出发，结合Python实例，手把手教你实现Venue卡片的发送，并避开常见的坑。

什么是Venue卡片？与位置消息有何区别？

Telegram中的Venue是专门用于展示具体场所的消息类型，包含名称、地址、经纬度以及可选的Foursquare ID。与普通位置（Location）消息相比，Venue多出title（标题）、address（地址）和foursquare_id（Foursquare场所ID），在UI上会以卡片形式呈现，底部直接附加“在地图中打开”等操作按钮。机器人发送Venue后，用户点击卡片即可看到地点详情或直接导航，极大提升交互效率。

发送Venue的必备条件

一个已创建并通过@BotFather获取的Bot Token（获取方法：向BotFather发送/newbot，按提示命名即可）。
目标地点的经纬度（纬度latitude和经度longitude，十进制度数，例如北京天安门为39.908869, 116.397429）。
可选但推荐：Foursquare Venue ID，用于展示更丰富的地点信息。若没有，也可只提供基本参数。
开发环境：Python 3.x及requests或python-telegram-bot库。本教程使用纯requests调用HTTP API，便于理解底层原理。

核心API参数详解：sendVenue

Telegram Bot API的sendVenue方法用于发送地点卡片。关键参数如下：

参数名	是否必填	说明
chat_id	是	接收消息的聊天ID（用户、群组或频道）
latitude	是	维度，范围 -90~90
longitude	是	经度，范围 -180~180
title	是	地点名称，1-64个字符
address	是	地点地址，1-64个字符
foursquare_id	否	Foursquare场所的唯一ID
foursquare_type	否	Foursquare场所类型，如“arts_entertainment”
google_place_id	否	Google Place ID（与Foursquare二选一）
google_place_type	否	Google Place类型
disable_notification	否	静默发送
reply_to_message_id	否	回复某条消息

注意：title和address最多64字符，超出会被截断或报错。若同时不提供Foursquare和Google相关ID，卡片仍可发送，但缺少增强信息。

Python实战：发送Venue卡片

我们使用requests库直接调用REST API，代码清晰易懂。以下是完整示例：

import requests

BOT_TOKEN = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"  # 替换为你的Bot Token
chat_id = "@my_channel"  # 或用户ID / 群组ID

url = f"https://api.telegram.org/bot/sendVenue"

payload = {
    "chat_id": chat_id,
    "latitude": 39.908869,
    "longitude": 116.397429,
    "title": "天安门广场",
    "address": "北京市东城区东长安街",
    "foursquare_id": "4b5f2c6bf964a520d0f729e3",  # 从Foursquare获取，可选
    "foursquare_type": "landmark",
}

resp = requests.post(url, json=payload)
result = resp.json()
if result["ok"]:
    print("Venue卡片发送成功! message_id:", result["result"]["message_id"])
else:
    print("发送失败:", result)

如果你使用python-telegram-bot库，可以更简洁地调用：

from telegram import Bot

bot = Bot(token=BOT_TOKEN)
bot.send_venue(
    chat_id=chat_id,
    latitude=39.908869,
    longitude=116.397429,
    title="天安门广场",
    address="北京市东城区东长安街",
    foursquare_id="4b5f2c6bf964a520d0f729e3"
)

运行前请确保网络能访问Telegram API（海外服务器或代理环境）。

如何获取地点的Foursquare ID和Google Place ID？

要获得更精确的卡片效果，推荐带上foursquare_id或google_place_id。获取方法主要有以下两种：

1. 从Foursquare API获取

前往Foursquare开发者平台注册应用，调用Places API搜索地点，返回的场所对象中fsq_id字段即为Venue ID。注意，Telegram要求的是Foursquare的venue ID（旧版），但新API中的place ID同样适用，可直接填入。

2. 从Telegram桌面端/网页版抓取

在Telegram中搜索一个Venue消息，点击右上角分享，复制链接，链接中通常带有?venue=参数，例如https://t.me/venue/BIZ_4b5f2c6bf964a520d0f729e3，从中提取BIZ_后面的部分（去掉前缀）就是Foursquare ID。另外，Telegram内置的“附近地点”搜索也可以直接显示Venue，但无法直接复制ID，此方法更为间接。

发送后的交互与常见错误排查

用户点击Venue会产生什么？

点击卡片会打开Telegram内置地图，显示地点详细信息，并提供“导航”“分享”等操作。如果foursquare_id有效，还会展示评分、照片等丰富内容。

常见错误及原因

400 Bad Request: title is empty：未填写title参数。
400 Bad Request: address is not valid：地址超长或包含非法字符（如换行）。
400 Bad Request: latitude out of range：维度不在-90~90区间。
404 Not Found：Bot Token错误或API地址写错。
429 Too Many Requests：发送频率过高，需等待重试。

调试技巧：始终打印API返回的JSON，错误信息会直接指出字段问题。建议用try-except捕获网络异常，并在重试时采用指数退避策略。

实战建议：提升Venue卡片的用户体验

动态获取坐标：结合位置更新服务，让机器人根据用户输入的地点名称自动查询坐标（如使用地理编码API），再发送Venue。
回复式推送：用户发送位置时，机器人用reply_to_message_id回传Venue推荐，形成闭环交互。
结合内联键盘：在Venue消息下附加按钮，如“到这里去”“查看详情”，通过InlineKeyboardMarkup实现。
批量发送：若需要推荐多个地点，可发送媒体组（但注意Venue不支持媒体组，所以建议逐条发送或使用自定义键盘选择）。

总结

发送Venue卡片并不复杂，核心在于理解sendVenue的参数结构和获取有效的地点ID。通过本文的Python示例，你可以快速集成到自己的机器人中，为用户提供优雅的地点推荐体验。如果希望进一步扩展，建议阅读Telegram Bot API官方文档中关于Venue的说明，并学习如何结合sendLocation实现动态位置追踪。开发过程中多测试边缘情况，你的机器人将更加健壮。