Telegram Bot API sendVenue 使用教程

8 阅读 0 评论 0 点赞

## 1. sendVenue 方法用途介绍

sendVenue 是 Telegram Bot API 提供的一个核心方法，用于向指定聊天发送场所信息，包含地理位置坐标、场所名称和地址等详细信息。

**主要用途：**

- 向用户、群组或频道发送场所的完整地理位置信息

- 提供场所名称和地址的结构化展示

- 可附加网站链接和查询字符串以便进一步探索

**核心特点：**

- 结合地理位置坐标和场所信息，提供更完整的地理参考

- 支持设置场所名称、地址、网站链接和查询字符串

- 可选择是否禁用通知

- 支持回复到聊天中的特定消息

- 可将场所信息发送到 Direct Messages 聊天主题

- 支持设置建议的帖子参数

## 2. 原生 PHP 调用实例

### 2.1 准备工作

确保你的 PHP 环境满足以下要求：

- PHP 5.6 或更高版本

- 已安装 cURL 扩展

- 已创建 Telegram Bot 并获取 Bot Token

### 2.2 发送基本场所信息

<?php
/**
 * 使用 Telegram Bot API 发送基本场所信息
 * @param string $botToken Bot Token
 * @param int|string $chatId 聊天 ID
 * @param float $latitude 纬度
 * @param float $longitude 经度
 * @param string $title 场所名称
 * @param string $address 场所地址
 * @return array 响应结果
 */
function sendBasicVenue($botToken, $chatId, $latitude, $longitude, $title, $address) {
    $url = "https://api.telegram.org/bot{$botToken}/sendVenue";
    
    $data = [
        'chat_id' => $chatId,
        'latitude' => $latitude,
        'longitude' => $longitude,
        'title' => $title,
        'address' => $address
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// 使用示例
$botToken = "YOUR_BOT_TOKEN";
$chatId = 123456789; // 用户或群组的聊天 ID
$latitude = 39.9042; // 北京天安门纬度
$longitude = 116.4074; // 北京天安门经度
$title = "天安门广场";
$address = "北京市东城区东长安街天安门广场";

$result = sendBasicVenue($botToken, $chatId, $latitude, $longitude, $title, $address);

if ($result['ok']) {
    echo "场所信息发送成功！消息 ID: " . $result['result']['message_id'];
} else {
    echo "发送失败：" . $result['description'];
}
?>
```

### 2.3 发送带高级选项的场所信息

```php
<?php
/**
 * 使用 Telegram Bot API 发送带高级选项的场所信息
 * @param string $botToken Bot Token
 * @param int|string $chatId 聊天 ID
 * @param float $latitude 纬度
 * @param float $longitude 经度
 * @param string $title 场所名称
 * @param string $address 场所地址
 * @param array $options 高级选项
 * @return array 响应结果
 */
function sendAdvancedVenue($botToken, $chatId, $latitude, $longitude, $title, $address, $options = []) {
    $url = "https://api.telegram.org/bot{$botToken}/sendVenue";
    
    $data = [
        'chat_id' => $chatId,
        'latitude' => $latitude,
        'longitude' => $longitude,
        'title' => $title,
        'address' => $address
    ];
    
    // 合并高级选项
    $allowedOptions = [
        'foursquare_id', 'foursquare_type', 'google_place_id', 'google_place_type',
        'disable_notification', 'protect_content', 'reply_to_message_id',
        'allow_sending_without_reply', 'reply_markup', 'direct_messages_topic_id',
        'suggested_post_parameters'
    ];
    
    foreach ($allowedOptions as $option) {
        if (isset($options[$option])) {
            $data[$option] = $options[$option];
        }
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// 使用示例 - 带查询信息的场所发送
$botToken = "YOUR_BOT_TOKEN";
$chatId = 123456789;
$latitude = 39.9088;
$longitude = 116.3974;
$title = "故宫博物院";
$address = "北京市东城区景山前街4号";

$result = sendAdvancedVenue(
    $botToken,
    $chatId,
    $latitude,
    $longitude,
    $title,
    $address,
    [
        'google_place_id' => 'ChIJtV7X5a5F8DUR22P8z8VJ1SU', // Google Place ID
        'google_place_type' => 'museum', // 场所类型
        'disable_notification' => false,
        'protect_content' => true, // 防止内容被转发
        'direct_messages_topic_id' => 67890 // Direct Messages 聊天主题 ID
    ]
);

if ($result['ok']) {
    echo "高级场所信息发送成功！";
} else {
    echo "发送失败：" . $result['description'];
}
?>
```

### 2.4 完整的 Telegram Bot 场所发送类

```php
<?php
class TelegramVenueBot {
    private $botToken;
    
    /**
     * 构造函数
     * @param string $botToken Bot Token
     */
    public function __construct($botToken) {
        $this->botToken = $botToken;
    }
    
    /**
     * 发送基本场所信息
     * @param int|string $chatId 聊天 ID
     * @param float $latitude 纬度
     * @param float $longitude 经度
     * @param string $title 场所名称
     * @param string $address 场所地址
     * @return array 响应结果
     */
    public function sendVenue($chatId, $latitude, $longitude, $title, $address) {
        return $this->sendAdvancedVenue($chatId, $latitude, $longitude, $title, $address, []);
    }
    
    /**
     * 发送带高级选项的场所信息
     * @param int|string $chatId 聊天 ID
     * @param float $latitude 纬度
     * @param float $longitude 经度
     * @param string $title 场所名称
     * @param string $address 场所地址
     * @param array $options 高级选项
     * @return array 响应结果
     */
    public function sendAdvancedVenue($chatId, $latitude, $longitude, $title, $address, $options = []) {
        $url = "https://api.telegram.org/bot{$this->botToken}/sendVenue";
        
        $data = [
            'chat_id' => $chatId,
            'latitude' => $latitude,
            'longitude' => $longitude,
            'title' => $title,
            'address' => $address
        ];
        
        // 验证坐标有效性
        if ($latitude < -90 || $latitude > 90) {
            return [
                'ok' => false,
                'error_code' => 400,
                'description' => 'Invalid latitude value. Must be between -90 and 90.'
            ];
        }
        
        if ($longitude < -180 || $longitude > 180) {
            return [
                'ok' => false,
                'error_code' => 400,
                'description' => 'Invalid longitude value. Must be between -180 and 180.'
            ];
        }
        
        // 合并高级选项
        $allowedOptions = [
            'foursquare_id', 'foursquare_type', 'google_place_id', 'google_place_type',
            'disable_notification', 'protect_content', 'reply_to_message_id',
            'allow_sending_without_reply', 'reply_markup', 'direct_messages_topic_id',
            'suggested_post_parameters'
        ];
        
        foreach ($allowedOptions as $option) {
            if (isset($options[$option])) {
                $data[$option] = $options[$option];
            }
        }
        
        return $this->sendRequest($url, $data);
    }
    
    /**
     * 发送 HTTP 请求
     * @param string $url 请求 URL
     * @param array $data 请求数据
     * @return array 响应结果
     */
    private function sendRequest($url, $data) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        
        if (curl_errno($ch)) {
            $error = curl_error($ch);
            curl_close($ch);
            return [
                'ok' => false,
                'error_code' => $httpCode,
                'description' => 'cURL 错误: ' . $error
            ];
        }
        
        curl_close($ch);
        return json_decode($response, true);
    }
    
    /**
     * 获取更新
     * @param int|null $offset 更新偏移量
     * @param int|null $limit 更新数量
     * @return array 响应结果
     */
    public function getUpdates($offset = null, $limit = null) {
        $url = "https://api.telegram.org/bot{$this->botToken}/getUpdates";
        
        $data = [];
        if ($offset !== null) $data['offset'] = $offset;
        if ($limit !== null) $data['limit'] = $limit;
        
        return $this->sendRequest($url, $data);
    }
}

// 使用示例
$botToken = "YOUR_BOT_TOKEN";
$bot = new TelegramVenueBot($botToken);
$chatId = 123456789;

// 发送基本场所信息
echo "发送基本场所信息...\n";
$result1 = $bot->sendVenue(
    $chatId,
    39.9042, // 纬度
    116.4074, // 经度
    "天安门广场", // 场所名称
    "北京市东城区东长安街天安门广场" // 地址
);

if ($result1['ok']) {
    echo "基本场所信息发送成功！消息 ID: " . $result1['result']['message_id'] . "\n";
} else {
    echo "发送失败：" . $result1['description'] . "\n";
}

// 发送带Foursquare信息的场所
echo "\n发送带Foursquare信息的场所...\n";
$result2 = $bot->sendAdvancedVenue(
    $chatId,
    31.2304, // 上海南京路纬度
    121.4737, // 上海南京路经度
    "南京路步行街", // 场所名称
    "上海市黄浦区南京路", // 地址
    [
        'foursquare_id' => '5a843284d203c9002c52a7e2', // Foursquare ID
        'foursquare_type' => 'shopping_mall', // 场所类型
        'disable_notification' => false,
        'protect_content' => false
    ]
);

if ($result2['ok']) {
    echo "带Foursquare信息的场所发送成功！";
} else {
    echo "发送失败：" . $result2['description'] . "\n";
}

// 发送带Google Places信息的场所
echo "\n发送带Google Places信息的场所...\n";
$result3 = $bot->sendAdvancedVenue(
    $chatId,
    23.1291, // 广州塔纬度
    113.2644, // 广州塔经度
    "广州塔", // 场所名称
    "广州市海珠区阅江西路222号", // 地址
    [
        'google_place_id' => 'ChIJBxZ3Rq9CgzQRmQOv7m9a1tE', // Google Place ID
        'google_place_type' => 'tourist_attraction', // 场所类型
        'direct_messages_topic_id' => 67890 // Direct Messages 聊天主题 ID
    ]
);

if ($result3['ok']) {
    echo "带Google Places信息的场所发送成功！";
} else {
    echo "发送失败：" . $result3['description'] . "\n";
}
?>

2.5 注意事项

1. **坐标要求：**

- 纬度（latitude）范围：-90 到 90

- 经度（longitude）范围：-180 到 180

- 精度建议：至少保留6位小数以确保准确性

2. **场所信息：**

- `title`：场所名称，不能为空

- `address`：场所地址，不能为空

3. **查询标识符：**

- `foursquare_id` 和 `foursquare_type`：用于关联Foursquare场所信息

- `google_place_id` 和 `google_place_type`：用于关联Google Places场所信息

- 这些参数是可选的，但如果提供，会丰富场所的展示效果

4. **聊天 ID 格式：**

- 私人聊天 ID 是整数

- 群组和频道 ID 通常以 `-100` 开头的负数

5. **高级选项：**

- `direct_messages_topic_id` 用于将场所信息发送到 Direct Messages 聊天主题

- `protect_content` 可防止场所信息被转发或保存

- `suggested_post_parameters` 可设置建议的帖子参数

## 3. 应用场景

- **场所推荐：** 向用户推荐餐厅、酒店、景点等场所

- **活动地点：** 发送会议、聚会、活动等的地点信息

- **导航指引：** 提供目的地场所的完整信息，便于导航

- **商家展示：** 展示商家的地理位置、名称和地址

- **旅游指南：** 为用户提供旅游景点的详细场所信息

## 4. 运行指南

1. 将以上代码保存为 `.php` 文件

2. 替换 `YOUR_BOT_TOKEN` 为你的实际 Bot Token

3. 替换聊天 ID、坐标、场所名称和地址为实际值

4. 在命令行或浏览器中运行 PHP 文件

```bash

php telegram-send-venue.php

```

所有代码均为原生 PHP 编写，无需任何框架依赖，可直接使用。

点赞(0) 打赏

本文分类：教程
本文标签：sendVenue
浏览次数：8 次浏览
发布日期：2025-12-21 16:06:22
本文链接：https://telegrambotdev.com/jiaocheng/166.html

上一篇 > 飞机Bot API sendLocation
下一篇 > Telegram Bot API sendContact 使用教程

Telegram Bot API sendVenue 使用教程

评论列表共有 0 条评论

发表评论取消回复

Telegram Bot API sendVenue 使用教程

Telegram Bot API sendVenue 使用教程

评论列表 共有 0 条评论

发表评论 取消回复

评论列表共有 0 条评论

发表评论取消回复