Skip to content

wechaty/puppet-official-account

Repository files navigation

PUPPET-OFFICIAL-ACCOUNT

NPM Version npm (tag) NPM ES Modules

WeChat Official Account Puppet for Wechaty

Powered by Wechaty TypeScript

Wechaty Puppet for WeChat Official Accounts helps you use Wechaty to manage your Official Account from https://mp.weixin.qq.com.

FEATURES

  1. Provide webhook proxy out-of-the-box (powered by localtunnel)

USAGE

This documentation assumes that you are familiar with Wechaty already.

If you are a newbie to Wechaty, please read the following two links first:

  1. Wechaty WebSite
  2. Wechaty Getting Started

To use wechaty-puppet-official-account with Wechaty, just like other puppets as well:

import { Wechaty }  from 'wechaty'
import { PuppetOA } from 'wechaty-puppet-official-account'

const oa = new PuppetOA({
  appId           : OA_APP_ID,
  appSecret       : OA_APP_SECRET,
  token           : OA_TOKEN,
  webhookProxyUrl : 'https://aeb082b9-14da-4c91-bdef-90a6d17a4z98.localtunnel.me',
})

const bot = new Wechaty({
  name: 'oa-bot',
  puppet: oa,
})

bot.on('message', msg => {
  if (!msg.self() && msg.type() === bot.Message.Type.Text && /ding/i.test(msg.text())) {
    await msg.say('dong')
  }
})
await bot.start()

For the full source code, see: <examples/ding-dong-bot.ts>

That's it!

ENVIRONMENTS VARIABLES

You can use environment variables to configure all of the WeChat Official Account Development Information.

WECHATY_PUPPET_OA_APP_ID: appId

Developer ID(AppID) is the developer ID, Official Account identification code, which can call Official Account API with the developer's password.

WECHATY_PUPPET_OA_APP_SECRET: appSecret

The Developer Password(AppSecret) is the one with high security to verify the identity of the Official Account developer.

WECHATY_PUPPET_OA_TOKEN: token

The token is set by you for your server(URL) configuration.

WECHATY_PUPPET_OA_PORT

Set WECHATY_PUPPET_OA_PORT to your local HTTP Server port number if you have a public server that can be visited from the internet.

After setting ``WECHATY_PUPPET_OA_PORT`, the puppet will expose itself to the internet with this port for providing the HTTP service.

WECHATY_PUPPET_OA_WEBHOOK_PROXY_URL

Set WECHATY_PUPPET_OA_WEBHOOK_PROXY_URL to a localtunnel supported address so that you will be able to provide the Server Address(URL) for WebHook usage with this URL.

This is the most convenient way to use this puppet because you can always provide the same URL to the WeChat Official Account platform no matter where your program is running.

Currently, you can generate this URL by yourself by:

  1. Generate a UUIDv4 use a generator like UUID Online Generator
  2. Insert your $UUID to https://${UUID}.localtunnel.me

For example, if your UUID is aeb082b9-14da-4c91-bdef-90a6d17a4z98, then you can use https://aeb082b9-14da-4c91-bdef-90a6d17a4z98.localtunnel.me as WECHATY_PUPPET_OA_WEBHOOK_PROXY_URL

Learn more from localtunnel

DEVELOPMENT

When you start developing the WeChat Official Account, it will be very helpful with the following tools provided by Tencent:

  1. Apply a test Official Account with full privileges for developing
  2. Simulate the API calls in an online simulation tool.

1 Apply an Official Account for developing/testing

测试号是扫码即可获得的微信公众号,拥有所有完整高级接口权限,测试专用。

微信公众帐号测试号申请系统入口地址:

2 API calls debugging tool

允许开发者在平台上提交信息和服务器进行交互,并得到验证结果的在线 API 调试工具。

Address: https://mp.weixin.qq.com/debug/

RESOURCES

HISTORY

master v1.0 Release (Oct 29, 2021)

  1. v0.9 (Oct 2021): Puppet API v0.51
  2. v0.7 (Sep 2021): Enable ES Module support for Node.js

v0.4 (Aug 6, 2020)

  1. Support localtunnel service from any service provider (domains).

v0.2 (Aug 2, 2018)

Initial version for Official Account.

  1. receive messages from users
  2. reply message to a user (passive mode)

Maintainers

COPYRIGHT & LICENSE

  • Code & Docs © 2020-now Wechaty Organization
  • Code released under the Apache-2.0 License
  • Docs released under Creative Commons