From 5be0fa74736e8fdd8c0680f04ce68cc431f632ec Mon Sep 17 00:00:00 2001
From: Richard Chien <richardchienthebest@gmail.com>
Date: Sat, 10 Nov 2018 21:41:16 +0800
Subject: [PATCH] Add calling-cqhttp-api

---
 docs/.vuepress/config.js         |  1 +
 docs/glossary.md                 |  2 +-
 docs/guide/calling-cqhttp-api.md | 38 ++++++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/guide/calling-cqhttp-api.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index d4e60907..e6443056 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -45,6 +45,7 @@ module.exports = {
                         'nl-processor',
                         'tuling',
                         'notice-and-request',
+                        'calling-cqhttp-api',
                         'scheduler',
                         'whats-next',
                     ]
diff --git a/docs/glossary.md b/docs/glossary.md
index a12dcc0a..f321d63d 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -12,7 +12,7 @@ sidebar: auto
 
 [CoolQ HTTP API 插件](https://cqhttp.cc/) 是酷 Q 的一个第三方插件，用于将酷 Q 所提供的所有 DLL 接口转换为 HTTP 或 WebSocket 的 web 形式，从而使利用任意语言编写酷 Q 插件成为可能。
 
-有时被称为 cqhttp、CQHttp、酷 Q HTTP API 等。
+有时被称为 cqhttp、CQHTTP、酷 Q HTTP API 等。
 
 ## aiocqhttp
 
diff --git a/docs/guide/calling-cqhttp-api.md b/docs/guide/calling-cqhttp-api.md
new file mode 100644
index 00000000..2282d514
--- /dev/null
+++ b/docs/guide/calling-cqhttp-api.md
@@ -0,0 +1,38 @@
+# 主动调用 CQHTTP 接口
+
+到目前为止，我们都在调用 `CommandSession` 类的 `send()` 方法，而这个方法只能回复给消息的发送方，不能手动指定发送者，因此当我们需要实现将收到的消息经过处理后转发给另一个接收方这样的功能时，这个方法就用不了了。
+
+幸运的是，`NoneBot` 类是继承自 [python-aiocqhttp] 的 `CQHttp` 类的，而这个类实现了一个 `__getattr__()` 方法，由此提供了直接通过 bot 对象调用 CQHTTP 的 API 的能力，如下：
+
+[python-aiocqhttp]: https://github.com/richardchien/python-aiocqhttp
+
+```python
+bot.send_private_msg(user_id=12345678, message='你好～')
+```
+
+这里，`send_private_msg` 实际上对应 CQHTTP 的 [`/send_private_msg` 接口](https://cqhttp.cc/docs/#/API?id=send_private_msg-%E5%8F%91%E9%80%81%E7%A7%81%E8%81%8A%E6%B6%88%E6%81%AF)，其它接口同理。
+
+通过这种方式调用 API 时，需要注意两点：
+
+1. **所有参数必须为命名参数（keyword argument）**，否则无法正确调用
+2. **调用失败时（没有权限、对方不是好友、无 API 连接等）可能抛出 `none.CQHttpError` 异常**，注意捕获
+
+另外，在需要动态性的场合，除了使用 `getattr()` 方法外，还可以直接调用 `bot.call_action()` 方法，传入 `action` 和 `params` 即可，例如上例中，`action` 为 `'send_private_msg'`，`params` 为 `{'user_id': 12345678, 'message': '你好～'}`。
+
+下面举出一些主动发送消息和调用 API 的例子：
+
+```python
+bot.send_private_msg(user_id=12345678, message='你好～')
+bot.send_group_msg(group_id=123456, message='大家好～')
+
+ctx = session.ctx.copy()
+del ctx['message']
+bot.send_msg(**ctx, message='喵～')
+
+bot.delete_msg(**session.ctx)
+bot.set_group_card(**session.ctx, card='新人请改群名片')
+self_info = bot.get_login_info()
+group_member_info = bot.get_group_member_info(group_id=123456, user_id=12345678, no_cache=True)
+```
+
+其它更多接口请自行参考 CQHTTP 的 [API 列表](https://cqhttp.cc/docs/#/API?id=api-列表)。