littlecodersh/ItChat

 littlecodersh / ItChat

littlecodersh / ItChat

A complete and graceful API for Wechat. 微信个人号接口、微信机器人及命令行微信,三十行即可自定义个人号机器人。 http://itchat.readthedocs.io

ItChat001010202030302017-06-222017-06-232017-06-242017-06-252017-06-262017-06-272017-06-282017-06-292017-06-302017-07-012017-07-022017-07-032017-07-042017-07-052017-07-062017-07-072017-07-082017-07-092017-07-102017-07-112017-07-122017-07-132017-07-142017-07-152017-07-162017-07-172017-07-182017-07-192017-07-202017-07-21ItChat199.1153846153879.56340849242017-06-223724.831564986710.15130077362017-06-231640.547745358191.13209311222017-06-24856.2639257294121.9819187652017-06-251771.980106100887.27586490562017-06-262087.696286472175.70718028582017-06-2737103.41246684410.15130077362017-06-2834119.12864721521.71998539342017-06-2920134.84482758675.70718028582017-06-3014150.56100795898.84454952542017-07-0110166.277188329114.2694623522017-07-0227181.993368748.71358283962017-07-0332197.70954907229.43244180662017-07-0415213.42572944394.98832131882017-07-0519229.14190981479.56340849242017-07-0613244.858090186102.7007777322017-07-078260.574270557121.9819187652017-07-082276.290450928145.1192880052017-07-0911292.0066313110.4132341452017-07-1018307.72281167183.4196366992017-07-1127323.43899204248.71358283962017-07-1217339.15517241487.27586490562017-07-1320354.87135278575.70718028582017-07-149370.587533156118.1256905582017-07-1514386.30371352898.84454952542017-07-1624402.01989389960.28226745942017-07-1737417.73607427110.15130077362017-07-1830433.45225464237.14489821982017-07-1932449.16843501329.43244180662017-07-2028464.88461538544.8573546332017-07-2149.11538461538137.4068315912017-06-22624.8315649867129.6943751782017-06-23540.5477453581133.5506033852017-06-24256.2639257294145.1192880052017-06-25571.9801061008133.5506033852017-06-26687.6962864721129.6943751782017-06-2712103.412466844106.5570059392017-06-281119.128647215148.9755162112017-06-2910134.844827586114.2694623522017-06-306150.561007958129.6943751782017-07-01-1166.277188329156.6879726242017-07-024181.9933687137.4068315912017-07-037197.709549072125.8381469722017-07-045213.425729443133.5506033852017-07-053229.141909814141.2630597982017-07-064244.858090186137.4068315912017-07-072260.574270557145.1192880052017-07-084276.290450928137.4068315912017-07-095292.0066313133.5506033852017-07-103307.722811671141.2630597982017-07-118323.438992042121.9819187652017-07-124339.155172414137.4068315912017-07-135354.871352785133.5506033852017-07-144370.587533156137.4068315912017-07-155386.303713528133.5506033852017-07-167402.019893899125.8381469722017-07-177417.736074271125.8381469722017-07-187433.452254642125.8381469722017-07-196449.168435013129.6943751782017-07-208464.884615385121.9819187652017-07-21-19.11538461538156.6879726242017-06-22624.8315649867129.6943751782017-06-23-140.5477453581156.6879726242017-06-24156.2639257294148.9755162112017-06-25-171.9801061008156.6879726242017-06-26387.6962864721141.2630597982017-06-271103.412466844148.9755162112017-06-280119.128647215152.8317444182017-06-292134.844827586145.1192880052017-06-301150.561007958148.9755162112017-07-010166.277188329152.8317444182017-07-024181.9933687137.4068315912017-07-030197.709549072152.8317444182017-07-040213.425729443152.8317444182017-07-051229.141909814148.9755162112017-07-061244.858090186148.9755162112017-07-072260.574270557145.1192880052017-07-08-1276.290450928156.6879726242017-07-092292.0066313145.1192880052017-07-100307.722811671152.8317444182017-07-111323.438992042148.9755162112017-07-120339.155172414152.8317444182017-07-130354.871352785152.8317444182017-07-14-2370.587533156160.5442008312017-07-152386.303713528145.1192880052017-07-161402.019893899148.9755162112017-07-173417.736074271141.2630597982017-07-183433.452254642141.2630597982017-07-191449.168435013148.9755162112017-07-204464.884615385137.4068315912017-07-21starforkwatch

 README

itchat

Gitter py27 py35 English version

itchat是一个开源的微信个人号接口,使用python调用微信从未如此简单。

使用不到三十行的代码,你就可以完成一个能够处理所有信息的微信机器人。

当然,该api的使用远不止一个机器人,更多的功能等着你来发现,比如这些

该接口与公众号接口itchatmp共享类似的操作方式,学习一次掌握两个工具。

如今微信已经成为了个人社交的很大一部分,希望这个项目能够帮助你扩展你的个人的微信号、方便自己的生活。

安装

可以通过本命令安装itchat:

pip install itchat

简单入门实例

有了itchat,如果你想要给文件传输助手发一条信息,只需要这样:

import itchat

itchat.auto_login()

itchat.send('Hello, filehelper', toUserName='filehelper')

如果你想要回复发给自己的文本消息,只需要这样:

import itchat

@itchat.msg_register(itchat.content.TEXT)
def text_reply(msg):
    return msg.text

itchat.auto_login()
itchat.run()

一些进阶应用可以在下面的开源机器人的源码和进阶应用中看到,或者你也可以阅览文档

试一试

这是一个基于这一项目的开源小机器人,百闻不如一见,有兴趣可以尝试一下。

QRCode

截屏

file-autoreply login-page

进阶应用

特殊的字典使用方式

通过打印itchat的用户以及注册消息的参数,可以发现这些值都是字典。

但实际上itchat精心构造了相应的消息、用户、群聊、公众号类。

其所有的键值都可以通过这一方式访问:

@itchat.msg_register(TEXT)
def _(msg):
    # equals to print(msg['FromUserName'])
    print(msg.fromUserName)

属性名为键值首字母小写后的内容。

author = itchat.search_friends(nickName='LittleCoder')[0]
author.send('greeting, littlecoder!')

各类型消息的注册

通过如下代码,微信已经可以就日常的各种信息进行获取与回复。

import itchat, time
from itchat.content import *

@itchat.msg_register([TEXT, MAP, CARD, NOTE, SHARING])
def text_reply(msg):
    msg.user.send('%s: %s' % (msg.type, msg.text))

@itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO])
def download_files(msg):
    msg.download(msg.fileName)
    typeSymbol = {
        PICTURE: 'img',
        VIDEO: 'vid', }.get(msg.type, 'fil')
    return '@%s@%s' % (typeSymbol, msg.fileName)

@itchat.msg_register(FRIENDS)
def add_friend(msg):
    msg.user.verify()
    msg.user.send('Nice to meet you!')

@itchat.msg_register(TEXT, isGroupChat=True)
def text_reply(msg):
    if msg.isAt:
        msg.user.send(u'@%s\u2005I received: %s' % (
            msg.actualNickName, msg.text))

itchat.auto_login(True)
itchat.run(True)

命令行二维码

通过以下命令可以在登陆的时候使用命令行显示二维码:

itchat.auto_login(enableCmdQR=True)

部分系统可能字幅宽度有出入,可以通过将enableCmdQR赋值为特定的倍数进行调整:

# 如部分的linux系统,块字符的宽度为一个字符(正常应为两字符),故赋值为2
itchat.auto_login(enableCmdQR=2)

默认控制台背景色为暗色(黑色),若背景色为浅色(白色),可以将enableCmdQR赋值为负值:

itchat.auto_login(enableCmdQR=-1)

退出程序后暂存登陆状态

通过如下命令登陆,即使程序关闭,一定时间内重新开启也可以不用重新扫码。

itchat.auto_login(hotReload=True)

用户搜索

使用search_friends方法可以搜索用户,有四种搜索方式:

  1. 仅获取自己的用户信息
  2. 获取特定UserName的用户信息
  3. 获取备注、微信号、昵称中的任何一项等于name键值的用户
  4. 获取备注、微信号、昵称分别等于相应键值的用户

其中三、四项可以一同使用,下面是示例程序:

# 获取自己的用户信息,返回自己的属性字典
itchat.search_friends()
# 获取特定UserName的用户信息
itchat.search_friends(userName='@abcdefg1234567')
# 获取任何一项等于name键值的用户
itchat.search_friends(name='littlecodersh')
# 获取分别对应相应键值的用户
itchat.search_friends(wechatAccount='littlecodersh')
# 三、四项功能可以一同使用
itchat.search_friends(name='LittleCoder机器人', wechatAccount='littlecodersh')

关于公众号、群聊的获取与搜索在文档中有更加详细的介绍。

附件的下载与发送

itchat的附件下载方法存储在msg的Text键中。

发送的文件的文件名(图片给出的默认文件名)都存储在msg的FileName键中。

下载方法接受一个可用的位置参数(包括文件名),并将文件相应的存储。

@itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO])
def download_files(msg):
    msg.download(msg.fileName)
    itchat.send('@%s@%s' % (
        'img' if msg['Type'] == 'Picture' else 'fil', msg['FileName']),
        msg['FromUserName'])
    return '%s received' % msg['Type']

如果你不需要下载到本地,仅想要读取二进制串进行进一步处理可以不传入参数,方法将会返回图片的二进制串。

@itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO])
def download_files(msg):
    with open(msg.fileName, 'wb') as f:
        f.write(msg.download())

用户多开

使用如下命令可以完成多开的操作:

import itchat

newInstance = itchat.new_instance()
newInstance.auto_login(hotReload=True, statusStorageDir='newInstance.pkl')

@newInstance.msg_register(TEXT)
def reply(msg):
    return msg.text

newInstance.run()

退出及登陆完成后调用特定方法

登陆完成后的方法需要赋值在loginCallback中。

而退出后的方法需要赋值在exitCallback中。

import time

import itchat

def lc():
    print('finish login')
def ec():
    print('exit')

itchat.auto_login(loginCallback=lc, exitCallback=ec)
time.sleep(3)
itchat.logout()

若不设置loginCallback的值,则将会自动删除二维码图片并清空命令行显示。

常见问题与解答

Q: 为什么中文的文件没有办法上传?

A: 这是由于requests的编码问题导致的。若需要支持中文文件传输,将fields.py(py3版本见这里)文件放入requests包的packages/urllib3下即可

Q: 如何通过这个包将自己的微信号变为控制器?

A: 有两种方式:发送、接受自己UserName的消息;发送接收文件传输助手(filehelper)的消息

Q: 为什么我发送信息的时候部分信息没有成功发出来?

A: 有些账号是天生无法给自己的账号发送信息的,建议使用filehelper代替。

作者

LittleCoder: 构架及维护Python2 Python3版本。

tempdban: 协议、构架及日常维护。

Chyroc: 完成第一版本的Python3构架。

类似项目

youfou/wxpy: 优秀的api包装和配套插件,微信机器人/优雅的微信个人号API

liuwons/wxBot: 类似的基于Python的微信机器人

zixia/wechaty: 基于Javascript(ES6)的微信个人账号机器人NodeJS框架/库

sjdy521/Mojo-Weixin: 使用Perl语言编写的微信客户端框架,可通过插件提供基于HTTP协议的api接口供其他语言调用

HanSon/vbot: 基于PHP7的微信个人号机器人,通过实现匿名函数可以方便地实现各种自定义的功能

问题和建议

如果有什么问题或者建议都可以在这个Issue和我讨论

或者也可以在gitter上交流:Gitter

当然也可以加入我们新建的QQ群讨论:549762872