@google/rcsbusinessmessaging

中文文档
1.0.10发布于 2024/08/14Apache-2.0CommonJS近 30 天下载 13.3万

Node.js helper library for the RCS Business Messages API

原始使用文档
文档目录17 节
  1. Documentation
  2. Quickstart
  3. Before you begin
  4. Adding a dependency
  5. Sample usage
  6. Initialisation
  7. Sending a text message with suggested replies and actions
  8. Sending a rich card
  9. Sending a carousel
  10. Sending a message with a Time to Live
  11. Sending a message with an expiry time
  12. Uploading a file to the RBM Content Store
  13. Sending a previously uploaded file
  14. Versioning
  15. Contributing
  16. License
  17. Known issues

Google's RCS Business Messaging: Node.js Client

RCS Business Messaging upgrades SMS with branding, rich media, interactivity, and analytics. With RCS, businesses can bring branded, interactive mobile experiences, right to the native Android messaging app.

This document contains an API reference, samples, and other resources useful to developing Node.js applications. For additional help developing RCS Business Messaging applications, in Node.js and other languages, see our RCS Business Messages quickstart guide.

Documentation

The documentation for the RCS Business Messaging API can be found here.

Quickstart

Before you begin

  1. Register with RCS Business Messaging.

Adding a dependency

Add the following to the dependencies section in your package.json :

"dependencies": {
  ...
  "@google/rcsbusinessmessaging": "^1.0.10"
  ...
},

We recommend you use the latest version available in the npm repository.

Sample usage

Samples below assume a similar library initialization as shown in the Using the client library section.

Initialisation

You initialise the library by providing your service account key and agentId.

const SERVICE_ACCOUNT_PUBLIC_KEY = 'REPLACE_ME';

// Get the RCS Business Messaging client library helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

rbmApiHelper.initRbmApi(SERVICE_ACCOUNT_PUBLIC_KEY);
rbmApiHelper.setAgentId('myrbmagent'); // my agent id was [email protected]

Since release 1.0.8, you can optionally initialise the library to use a specific regional endpoint. This may provide improved performance depending on the geographic location of your code.

rbmApiHelper.initRbmApi(privateKey);

// The RBM API can now be initialised to use a specific regional
// entry point.
// rbmApiHelper.initRbmApi(privateKey, rbmApiHelper.REGION_APAC);
// rbmApiHelper.initRbmApi(privateKey, rbmApiHelper.REGION_EU);
// rbmApiHelper.initRbmApi(privateKey, rbmApiHelper.REGION_US);

Sending a text message with suggested replies and actions

// Create the payload for sending a message of "Hello, World!" along with
// a suggested reply and two suggested actions
rbmApiHelper.sendMessage({
  messageText: 'Hello, World!',
  msisdn: phoneNumber,
  suggestions: [
      {
        reply: {
          text: 'Sample Chip',
          postbackData: 'sample_chip',
        },
      },
      {
        action: {
          text: 'URL Action',
          postbackData: 'url_action',
          openUrlAction: {
            url: 'https://www.google.com',
          },
        },
      },
      {
        action: {
          text: 'Dial Action',
          postbackData: 'dial_action',
          dialAction: {
            phoneNumber: '+12223334444',
          },
        },
      },
    ]
  }
);

Sending a rich card

// Create the payload for sending a rich card
rbmApiHelper.sendRichCard({
  messageText: 'Hello, world!',
  messageDescription: 'RBM is awesome!',
  msisdn: phoneNumber,
  suggestions: [
    {
      reply: {
         'text': 'Suggestion #1',
         'postbackData': 'suggestion_1',
      },
    },
    {
      reply: {
         'text': 'Suggestion #2',
         'postbackData': 'suggestion_2',
      },
    },
  ],
  imageUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
  height: 'TALL',
});
// Create the payload for sending a carousel
rbmApiHelper.sendCarouselCard({
  msisdn: phoneNumber,
  cardContents: [
    {
      title: 'Card #1',
      description: 'The description for card #1',
      suggestions: [
         {
            reply: {
               text: 'Card #1',
               postbackData: 'card_1',
            }
         }
      ],
      media: {
         height: 'MEDIUM',
         contentInfo: {
            fileUrl: 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
            forceRefresh: false,
         },
      },
    },
    {
      title: 'Card #2',
      description: 'The description for card #2',
      suggestions: [
         {
            reply: {
               text: 'Card #2',
               postbackData: 'card_2',
            }
         }
      ],
      media: {
         height: 'MEDIUM',
         contentInfo: {
            fileUrl: 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
            forceRefresh: false,
         },
      },
    },
});

Sending a message with a Time to Live

Sending an RBM message which will be cancelled if the time to live is reached before it is delivered. Added in release 1.0.3.

const params = {
  messageText: 'This message will expire!',
  msisdn: config.phoneNumber,
  // allow 10 seconds for message delivery
  timeToLive: '10s',
};

rbmApiHelper.sendMessage(params,
  function(response, err) {
    if (err !== undefined) {
      console.log(
        util.inspect(err, {showHidden: false, depth: null, colors: true}));
    }
    if (response !== undefined) {
      console.log(
        util.inspect(response, {showHidden: false, depth: null, colors: true}));
    }
  }
);

Sending a message with an expiry time

Sending an RBM message which will be cancelled if the expiry time is reached before it is delivered. Added in release 1.0.3.

// Calculate UTC time in zulu format 20 seconds from now
const d = new Date();

d.setSeconds(d.getSeconds()+20);

const params = {
  messageText: 'This message will expire!',
  msisdn: config.phoneNumber,
  expireTime: d.toISOString()
};

rbmApiHelper.sendMessage(params,
  function(response, err) {
    if (err !== undefined) {
      console.log(
        util.inspect(err, {showHidden: false, depth: null, colors: true}));
    }
    if (response !== undefined) {
      console.log(
        util.inspect(response, {showHidden: false, depth: null, colors: true}));
    }
  }
);

Uploading a file to the RBM Content Store

Support for file uploading added in release 1.0.6.

const params = {
  fileUrl: 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
  thumbnailUrl: 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
  // contentDescription: string
};

rbmApiHelper.uploadFile(params,
  function(response, err) {
    if (err !== undefined) {
      console.log(
        util.inspect(err, {showHidden: false, depth: null, colors: true}));
    }
    if (response !== undefined) {
      console.log(
        util.inspect(response, {showHidden: false, depth: null, colors: true}));
    }
  }
);

Sending a previously uploaded file

Support added in release 1.0.6.

const params = {
  // Uploaded file id. If this uplod also contains a thumbnail, it will be used
  uploadedFileName: 'files/lpcg6f1tnYg1ryaQNho6hjka',
  // Uploaded thumbnail id. If this upload contains a thumbnail then it will be
  // used in preference to the one above.
  // uploadedThumbnailName: "files/lpchblt9boYTjT8ck6UGQ8uK",
  msisdn: config.phoneNumber,
};

rbmApiHelper.sendMessage(params,
  function(response, err) {
    if (err !== undefined) {
      console.log(
        util.inspect(err, {showHidden: false, depth: null, colors: true}));
    }
    if (response !== undefined) {
      console.log(
      util.inspect(response, {showHidden: false, depth: null, colors: true}));
    }
  }
);

Versioning

This library follows Semantic Versioning.

This library is considered to be General Availability (GA). This means it is stable; the code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against GA libraries are addressed with the highest priority.

Contributing

Contributions welcome! See the Contributing Guide.

License

Apache Version 2.0

See LICENSE

Known issues

On recent versions of node.js you may see this deprecation warning:

(node:23043) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)

This is due to a dependency in the underlying googleapis library. This will be resolved when the team responsible for this library ship an updated release.

版本与发布记录

@google/rcsbusinessmessaging 共发布 8 个版本,首次发布于 2023/12/06;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.0.10latest2024/08/142 年前
1.0.92024/07/302 年前
1.0.82024/06/042 年前
1.0.72023/12/092 年前
1.0.62023/12/082 年前
1.0.52023/12/082 年前

关于 @google/rcsbusinessmessaging 的常见问题

@google/rcsbusinessmessaging 是什么?

Node.js helper library for the RCS Business Messages API

如何安装 @google/rcsbusinessmessaging?

在项目目录运行 npm install @google/rcsbusinessmessaging,或使用 pnpm add / yarn add / bun add。

@google/rcsbusinessmessaging 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/google__rcsbusinessmessaging 是否存在。

@google/rcsbusinessmessaging 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@google/rcsbusinessmessaging 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.18.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@google/rcsbusinessmessaging 可以商用吗?

@google/rcsbusinessmessaging 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@google/rcsbusinessmessaging 的下载量有多少?

根据 npm 官方下载统计,@google/rcsbusinessmessaging 在 2026/10/17 – 2026/11/15 这 30 天内被下载 133,337 次,日均约 4,445 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@google/rcsbusinessmessaging 还在维护吗?

最新版本 1.0.10 发布于 2024/08/14(2 年前);至今共发布 8 个版本,其中过去 12 个月发布了 0 个;首次发布于 2023/12/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。