npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

wechaty-puppet-wxkf

v0.0.17

Published

A wechaty puppet for Wechat Customer Service, or WXKF (Weixin Ke Fu).

Downloads

80

Readme

WECHATY PUPPET WXKF

A wechaty puppet for Wechat Customer Service, or WXKF (Weixin Ke Fu).

中文

NPM Version

Powered by Wechaty TypeScript

Structure

Work isolated

image

Work with Wxkf-Manager

image

Why do we need this manager?

Either In-house development app and Authorize custom app can take many responsibilities, and WXKF might be just one of them. Also you might create multiple WXKF accounts. So it is almost a must for there to be a manager to listen and dispatch callbacks. That's why we need WXKF-Manager.

To use WXKF-Manager, you need to set up two more envs, PUPPET_WXKF_MANAGER_CENTER_ENDPOINT and PUPPET_WXKF_SELF_ENDPOINT.

export PUPPET_WXKF_MANAGER_CENTER_ENDPOINT=http://127.0.0.1:7777
export PUPPET_WXKF_SELF_ENDPOINT=http://127.0.0.1:8080

PUPPET_WXKF_MANAGER_CENTER_ENDPOINT is the endpoint of WXKF-Manager, puppet will register to this manager with kfId and PUPPET_WXKF_SELF_ENDPOINT so that the manager will callback to puppet when receiving new events.

For more detail about WXKF-Manager, please look into WXKF-Introduction. This intro will focus on the direct approach.

How to use

Install dependencies

npm install wechaty
npm install wechaty-puppet-wxkf

Note: wechaty-puppet-wxkf cannot run with wechaty < 1.0

Set up Env or PuppetOptions

Unlike most of other wechaty puppet, wechaty-puppet-wxkf cannot login by scanning QRcode. You have to set up via ENV or PuppetOptions. If both were set for the same field, PuppetOptions will take priority.

This will be further discussed in later sections.

Start ding-dong bot

import { WechatyBuilder  } from "wechaty";
import { PuppetWxkf } from "wechaty-puppet-wxkf";

const bot = WechatyBuilder.build({
  puppet: new PuppetWxkf()
})

bot.on('message', async message => {
  if (message.text === 'ding') {
    await message.say('dong')
  }
})

bot.start()

Authentication

How to get your keys

You may notice that we did not listen to 'scan' event when creating the ding-dong bot example. This is not a mistake.

The authentication for WXKF is done by 'WeChat Customer Service ' app of Wecom Company Ecosystem. You can manage app in your Wecom company backend.

App-manage

Pull down to the bottom of this pages, you can see Wechat Customer Service can be managed by APIs in 3 methods, In-house development, Authorize third-party app or Authorize custom app. So far wechaty-puppet-wxkf supports In-house development or Authorize custom app.

App-type

If you want to manage a new WXKF account, here's what you gonna do.

  • Create a new Customer Service Account in the Wechat Customer Service app page. Give it a name and avatar.

    Note: You can use name or kfId to identify your Wechat Customer Service account. However you cannot get ID in this webpage but only in apis. So if you want to identify by name, remember to give unique names to your account.

  • Allocate the Customer Service account to the app you are developing. You can do this by clicking the 'In-house development' link or the 'Authorize custom app' link in the above image.

  • Get your token and encodingAESKey. These keys will be used to decrypt callbacks from wecom so you can receive messages.

    If you are developing In-house development app, you can find in the WeChat Customer Service app page, click API and then settings.

    App-key

    If you are developing Authorize custom app, you should find these keys in your custom app page.

  • Setup callback url. You can put this puppet in a server and set the url to this puppet, however that is not recommended. In that case you can only manage one Wechat Customer Service account. You should setup a service to dispense these messages based on ID. You can use this project, wxkf-manager, or you can always build your own service.

  • Get your secret and corpId. These keys will be used when sending messages.

    If you are developing In-house development app, you can click the 'view' button in above image, and the secret will be sent to your mobile wecom app. Your CorpId, or Company Id, can be found in the 'My Company' tab of wecom admin backend.

    If you are developing Authorize custom app, these info will be sent to your callback service when the user install your app. Please dig into Tencent official API references for further information. (Seems there is only Chinese version available.)

  • You should also assign a port, a web server will listen to this port for callbacks.

How to setup keys

  • Via PuppetOptions

    const bot = WechatyBuilder.build({
      puppet: new PuppetWxkf({
        callbackPort: `${port}`,
        wxkfAuth: {
          token: `${token}`,
          encodingAESKey: `${encodingAESKey}`,
          corpId: `${corpId}`,
          corpSecret: `${secret}`,
          kfOpenId: `${kfId}`, // either of these two keys
          kfName: `${kfName}`, // is good enough
        },
      })
    })
  • Via Environment Variable

    export PUPPET_WXKF_WECOM_APP_TOKEN=${token}
    export PUPPET_WXKF_WECOM_APP_AES_KEY=${encodingAESKey}
    export PUPPET_WXKF_WECOM_CORP_ID=${corpId}
    export PUPPET_WXKF_WECOM_CORP_SECRET=${secret}
    
    export PUPPET_WXKF_WECOM_KF_NAME=${name}
    export PUPPET_WXKF_WECOM_KF_OPEN_ID=${kfId}
    export PUPPET_WXKF_CALLBACK_PORT=8080

Setup OSS

OSS(Object Storage Service) is an optional configuration for wechaty-puppet-wxkf. You can still use most of the features, but the ability of receiving Mini Programs will be impacted.

Here's the Mini Program payload of wechaty puppet:

export interface MiniProgramPayload {
    appid?       : string,   // optional, appid, get from wechat (mp.weixin.qq.com)
    description? : string,   // optional, mini program title
    pagePath?    : string,   // optional, mini program page path
    iconUrl?     : string,   // optional, mini program icon url
    shareId?     : string,   // optional, the unique userId for who share this mini program
    thumbUrl?    : string,   // optional, default picture, convert to thumbnail
    title?       : string,   // optional, mini program title
    username?    : string,   // original ID, get from wechat (mp.weixin.qq.com)
    thumbKey?    : string,   // original, thumbnailurl and thumbkey will make the headphoto of mini-program better
}

Note that icon and thumbnail are passed as url, instead of a filebox json string. For other payloads like message image and message file, we can pass a filebox of local file when we don't have any OSS files configured. However that is not the case for mini programs.

Wecom will give us direct url to link thumbnails, so link messages is fine.

The OSS we support so far includes S3, Ali, Minio, Tos and Cos. Please look into src/util/env.ts to find more info. Detailed document may be appended later.