聊天机器人如何接入渣男语录？从调用到展示的全链路设计
# 聊天机器人如何接入渣男语录？从调用到展示的全链路设计
- **接口/接入点**：免费渣男语录（apiCode=2962，接入点 1） · **是否免费**：免费 · **请求方式**：POST/GET · **返回格式**：JSON · **适用人群**：聊天机器人/社群开发者、社交类 APP 产品 · **阅读时间**：约 6 分钟
## 核心要点
- 把渣男语录做成"一句话触发的彩蛋"：用户发关键词（如"来句渣男语录"）→ 机器人调用接口 → 返回 `text` 渲染成卡片。
- 关键不在调用，而在**失败兜底**：`ret_code=-1` 时重试/提示，避免把"准备中"展示给用户。
- 免费但有档位限制，机器人场景要注意节流与缓存去重（详见 [《档位与频率限制》](https://www.showapi.com/guides/zhanan-quotes-rate-limit-2962)）。
## Why：这跟我有什么关系
- 社群/私域里加一个"土味情话生成器"类彩蛋，能显著提升互动率，而接入成本几乎为零（免费接口 + 一次 HTTP 调用）。
- 相比本地写死文案，调用接口能持续拿到新鲜句子，避免用户刷到重复内容。
## What：前置条件
| 项 | 值 |
|----|----|
| 需要 | 一个可处理消息的机器人服务（Webhook/长连接均可） |
| 鉴权 | `appKey`（[控制台获取](https://www.showapi.com/console#/myApp)） |
| 接口 | `https://route.showapi.com/2962-1?appKey={your_appKey}` |
| 关键返回 | `showapi_res_body.text` / `ret_code` |
## How：全链路设计
### 步骤 1 · 设计触发词
在消息路由里匹配关键词，如「渣男语录」「土味情话」「来句梗」。命中即进入调用分支。
### 步骤 2 · 封装调用（带兜底）
```python
import requests
def get_zhanan_quote(appkey: str, retries: int = 2) -> str:
url = "https://route.showapi.com/2962-1"
for attempt in range(retries):
try:
resp = requests.post(url, params={"appKey": appkey}, timeout=10)
body = resp.json().get("showapi_res_body", {})
if body.get("ret_code") == 0 and body.get("text"):
return body["text"]
# ret_code=-1 接口准备中，退避后重试
except requests.RequestException:
pass
import time; time.sleep(0.5 * (attempt + 1))
return "渣男语录暂时开小差了，请稍后再试 😅" # 兜底文案
# 在消息处理里调用
# reply = get_zhanan_quote(APPKEY)
```
### 步骤 3 · 结果渲染
把返回的 `text` 包成一张卡片（引用样式 + emoji），比纯文本更有"梗"感：
```
💬 渣男语录
「你不要闹了，她只是我的小学同学。」
—— 仅供娱乐 · 来自 ShowAPI 渣男语录
```
### 步骤 4 · 防刷与缓存（机器人场景必做）
- 同一用户短时间重复触发 → 命中本地缓存（见 [《档位与频率限制》](https://www.showapi.com/guides/zhanan-quotes-rate-limit-2962)）。
- 高并发用令牌桶限速，避免触发档位限制。
## 返回示例与解析
成功返回示例（节选业务体）：
```json
{ "ret_code": 0, "text": "你不要闹了，她只是我的小学同学。", "remark": "" }
```
失败时 `ret_code=-1`，前端应展示兜底文案而非原文。
## 进阶 / 边界
- **缓存去重**：语录本身是随机的，但可在机器人侧对"同一用户 30 秒内"做去重，既省调用又避免刷屏。
- **内容边界**：语录含戏谑/土味内容，机器人场景务必配合 [《内容合规与娱乐边界》](https://www.showapi.com/guides/zhanan-quotes-content-compliance-2962) 把握分寸。
- **无业务参数**：本接口不能按关键词筛选语录类型，拿到什么展示什么。
## FAQ
- **Q：能让语录按类型返回吗（比如只要土味情话）？** A：不能，接口无筛选参数，返回内容随机。
- **Q：机器人频繁调用会被限流吗？** A：免费但有档位限制，建议做客户端节流+缓存，详见限流篇。
- **Q：ret_code=-1 要怎么处理？** A：属可重试状态，做退避重试；多次失败则展示兜底文案。
- **Q：返回内容能直接发给用户吗？** A：可以，但请遵守娱乐定位与合规边界，别用在不当时场合。
- **Q：需要额外依赖吗？** A：只需一个 HTTP 客户端（requests/fetch 等），无特殊依赖。
## 相关能力 / 下一步阅读
- [渣男语录：5 分钟接入，从注册到第一条土味情话](https://www.showapi.com/guides/zhanan-quotes-quickstart-2962)
- [渣男语录返回字段全解：ret_code / text / remark 一文读懂](https://www.showapi.com/guides/zhanan-quotes-response-fields-2962)
- [渣男语录使用档位与频率限制：如何避免触发限流](https://www.showapi.com/guides/zhanan-quotes-rate-limit-2962)
- **本系列共 7 篇**：查看[渣男语录指南总目录](https://www.showapi.com/guides/zhanan-quotes-guides-2962)
