Mixin Messenger 机器人接入指南

关于 Mixin Messenger

Mixin Messenger 是一个开源的端对端加密聊天软件，并且集成了基于 Mixin Network 的多链钱包。

• 安全：端对端加密保障消息安全，去中心化、可信代码保障钱包安全
• 免费：免费收发消息，免费转账
• 易用：手机号注册即可使用，6 位 PIN 码即可享受数字加密货币
• 快速：实时收发消息，实时享受转账服务
• 丰富：支持文字、贴纸、图片、语音、视频等消息；支持 21 条主链，超过 10 万种代币

注意 Mixin Messenger 没有专门推荐机器人的界面，现在和以后都也不会有，机器人开发好后需要开发者自己想办法推广。早期在 Mixin Messenger 里推广自己的机器人是很容易的，做好了往群机器人一发大家都知道了，能帮你获得珍贵的种子用户，Exin（7000101276）就是一个很好的例子

准备

• 下载 Mixin Messenger https://mixin.one/messenger，体验设置 PIN、充值、转账、提现流程
• 阅读官方开发指南：https://developers.mixin.one/guides

1、注册成为 Mixin 的开发者

注册登录 Mixin Messenger ，点首页底部 ⭕️打开摄像头界面扫码登录 https://developers.mixin.one （点右上角）

2、创建机器人

点 Create New App 按提示创建就行， 创建完即可在 Mixin Messenger 首页顶部输入机器人的 ID 搜索找到你创建的机器人

机器人的 Identity Number

创建机器人参数说明：

• The home uri
  机器人入口，Mixin Messenger 里打开机器人实际上打开一个内置 WebView 的弹窗，WebView 会默认加载你设置的 home uri。
• The OAuth redirect uri
  OAuth 授权回调，必填项。

推荐上传 512x512 像素图标作为机器人的图标

3、生成机器人相关的 Session

点 Click to generate a new session 生成 PIN、Session Id 、Pin Token、Private Key，这些都要记下来后面要用，服务器和浏览器都不会保存这些敏感信息（注意刷新再次点又会生成一个新的，会覆盖旧的）。

4、OAuth 授权

要访问用户个人资料、资产列表、联系人列表、禁言列表和手机号码，你需要通过 Mixin Messenger 向用户申请授权
https://developers.mixin.one/api/beta-mixin-message/oauth-scopes/

4.1 权限列表

权限	说明
PROFILE:READ	获取用户基本信息，例如 UserID、Mixin ID、名称、头像
ASSETS:READ	读取用户资产列表，资产余额，充值、提现和转账数据
PHONE:READ	读取用户手机号
CONTACTS:READ	读取用户联系人列表，禁言列表

4.2 申请授权

当机器人检测到用户没有授权时跳转页面至 https://mixin.one/oauth/authorize?client_id=b7347ca4-186e-4e54-9db6-755a4ab0b5d4&scope=PROFILE:READ+ASSETS:READ&response_type=code 引导用户授权，在浏览器里打开这个链接会显示一个二维码，在 Mixin Messenger 中打开就会直接唤起请求授权弹窗。

• client_id 参数是步骤 3 图中的 User Id
• response_type 固定写 code 就行

4.3 授权成功回调

Mixin Messenger 授权成功后会回调步骤 2 填写的 redirect uri ，并且返回一个 authorization code ，通过 https://api.mixin.one/oauth/token 验证成功后会返回 access token 存起来，后续可以用 access token 通过 API 访问用户数据，据此可以判断当前用户是否已经授权过了。参考官方开发者指南里 Request Access Token 章节： https://developers.mixin.one/guides

5、通过 API 访问授权用户的数据

访问授权用户的个人资料、资产列表等 API 都需要设置 Authorization Token， 直接用上面取到的 access_token 即可。

GET -H "Authorization: Bearer ACCESS_TOKEN" https://api.mixin.one/me 
{
  "data": {
    "type": "user",
    "user_id": "773e5e77-4107-45c2-b648-8fc722ed77f5",
    "name": "Team Mixin",
    "identity_number": "7000"
  }
}

访问以下 API 都需要相应的授权，需要在步骤 4 申请授权时设置，常用 API ：

• /me 获取授权用户的个人信息，例如 user_id、name 等，如果后续需要和用户交互可以把用户信息保存到你服务端的数据库里，例如给用户发消息，记录用户的支付信息等。参考 API：https://developers.mixin.one/api/beta-mixin-message/read-profile/
• /assets 获取授权用户的资产列表，包含余额信息，其中 asset id 是 Mixin Network 中的数字资产的唯一标识，参考 API ：https://developers.mixin.one/api/alpha-mixin-network/read-assets/
• /friends 获取授权用户的好友列表，参考 API ：https://developers.mixin.one/api/beta-mixin-message/friends/
• /blocking_users 获取授权用户的禁言列表，可实现屏蔽大群机器人被禁用户的消息

当 API 返回 401 时你需要清理旧的 access_token 然后重新请求授权

6、Schema 支持

• 支付
  https://mixin.one/pay?recipient=&asset=&amount=&memo=&trace=
  recipient 是收款人的 User Id，asset 是具体支付资产 id，amount 支付金额，memo 支付备注（可以不传），trace 支付唯一编号 UUID

trace 可以用来防止重复支付，每一笔交易都应该生成一个新的 trace。可以用轮询的方式根据 trace 调用 https://api.mixin.one/transfers/trace/[trace_id] 来检测是否已经完成支付，参加 js 代码 里的 handleOrderCreate 方法。

• 用户或机器人信息弹窗
  https://mixin.one/users/b26b9a74-40dd-4e8d-8e41-94d9fce0b5c0
  可以在 Mixin Messenger 直接弹窗显示某个用户

• 分享文字
  https://mixin.one/users?text=
  可以分享文字内容到 Mixin Messenger 里，客户端这边会唤起转发的界面

• 提现
  mixin://withdrawal?address=&asset=&amount=&memo=&trace=
  主要用于支持网页版钱包，需要先添加提现地址

• 新增或修改提现地址
  mixin://address?public_key=&label=
  mixin://address?account_name=&account_tag=
  注意没有单独的新增和修改，如果地址已经存在

• 删除提现地址
  mixin://address?action=delete&address=

7、给用户发消息

知道用户 ID 就可以给用户直接发消息，可以通过用户授权、用户主动发消息或用户主动添加机器人为联系人三种方式来获取用户 ID。

当用户添加机器人为联系人时 Mixin 的消息服务器会给机器人发一个 hi ，也可以通过这种方式获取用户的 ID。

消息类型

具体参数参考官方文档 https://developers.mixin.one/api/beta-mixin-message/websocket-messages

消息类型	说明
PLAIN_TEXT	文字
PLAIN_IMAGE	图片
PLAIN_VIDEO	视频
PLAIN_DATA	文件
PLAIN_STICKER	贴纸
PLAIN_CONTACT	联系人（名片）
APP_BUTTON_GROUP	按钮
APP_CARD	卡片，抢红包就是用的这种样式
PLAIN_LIVE	直播，样式和视频一样，左上角显示一个 LIVE 标识

APP_BUTTON_GROUP、APP_CARD 和 PLAIN_LIVE 都是 Mixin Messenger 为机器人特别支持的样式

消息发送

需要有 Conversation ID 才能发消息， 1 对 1 会话使用 message.go 的 UniqueConversationId 方法生成

• 通过 WebSocket 发消息
  连接 WebSocket 后通过 blaze.go 的 SendPlainText、SendContact 等方法发消息

• 通过 HTTP 批量发消息
  调用 message.go 的 PostMessage 方法发送消息

机器人只能发 PLAIN_ 开头的不加密消息，representative_id 参数主要用于大群机器人用来标识当前发消息的用户

8、接收用户发给机器人的消息

使用 WebSocket 监听消息机器人的消息，参考文档 https://developers.mixin.one/api/beta-mixin-message/authentication/ ，参考源码 https://github.com/crossle/hacker-news-mixin-bot 的 blaze.go 和 message.go 。

• 即使将机器人添加到多人群组，机器人也收不到群组产生的消息，群组的消息都是加密的，机器人只能处理未加密的消息。
• 注意收到消息处理完以后一定要发 ACKNOWLEDGE_MESSAGE_RECEIPT 类型的消息告诉 Mixin Messenger 服务器你已经收到了消息，否则每次给服务器发 LIST_PENDING_MESSAGES 都会再次发给你的小程序。（Go 的 SDK 已经默认处理了）

9、大群机器人

Mixin Messenger 的无上限大群是通过机器人中转消息来实现的，具体参考文章：

• 欢迎来 Mixin 建服务群
  https://www.jianshu.com/p/76e534125176)
• Mixin 大群部署完全教程
  https://blog.exin.one/2019/05/25/mixin-super-group

10、优化小程序

强烈推荐学习使用 PWA 来改善您小程序的体验（https://developers.google.com/web/ilt/pwa/）

11、资源

• Golang SDK：https://github.com/MixinNetwork/bot-api-go-client
• Mixin Messager Android 源码：https://github.com/MixinNetwork/android-app
• Mixin Messager iOS 源码：https://github.com/MixinNetwork/ios-app
• Nodejs Demo （非官方）: https://github.com/virushuo/mixin-node
• Python Demo（非官方）: https://github.com/myrual/mixin_client_demo
• Java Demo（非官方）: https://github.com/qige-one/mixin_java_sdk
• Go 开源小程序 Hacker News (Mixin ID: 7000100124) ： https://github.com/crossle/hacker-news-mixin-bot
• Mixin 官方开发者群：https://mixin.one/codes/0f2a743d-d86b-4a6c-b26c-14e320799311

---

Exin 团队基于 Mixin Messenger 开发的各种交易工具已经实实在在的获取到几万真实用户并且已经赚到钱！欢迎加入与 Mixin 共同成长，获取你宝贵的种子用户！