用户标签管理

Bothub支持商户自行管理用户标签,方便商户给自己的用户打标签,进行分组管理。 Bothub采用广告中的受众概念来维护用户标签。受众和标签是一一对应的标签。当用户被打上标签时,实质上是加入了同名受众。标签被移除时,实质上是从该受众中被移除。给具有某个标签的所有用户群发消息,其实也就是给同名受众中的所有用户发消息。

受众(标签)的管理是在Bothub后台中直接操作,包含下列操作:

  • 查看受众信息,以及受众人数
  • 新建 / 删除受众
  • 给对应的受众设置消息群发
  • 查看受众信息,下载受众具体信息 关于受众的管理,详见此文档

而用户的标签管理则通过三个API来实现

  • 给用户打标
  • 移除用户标签
  • 获取用户标签

以下将分别详述。

字段释义

您可以用任意一个已经启用的API Key(怎样申请APIKey) 向Bothub发起请求,向一个手机号或一个官网账号发送一条消息。这个请求的说明如下:

请求属性 属性名 说明
地址 https://api.bothub.ai/api
请求方式 POST
Header APIKEY 您的API KEY
Form Data request.method 需要调用的api。此处设置为add_customer_label(给用户打标), remove_customer_label(移除用户标签), get_customer_labels(获取用户标签)
Form Data request.id 用来唯一标识此发送请求的id。由调用方生成
Form Data request.meta 预留字段,可以填写例如为何为用户打此标签等信息
Form Data recipient 要发送消息的用户信息,只能指定一个用户。下列四种方式任取一种
Form Data recipient.id 以PSID方式指定用户
Form Data recipient.email 指定已绑定email的账号
Form Data recipient.username 指定已绑定username的账号
Form Data recipient.phone_number 指定已绑定phone number的账号

给用户打标

此API可以给用户添加一个或多个标签。商户必须事先在Bothub后台添加过同名受众。

样例 - 给指定PSID的用户打标"VIP"和"TOP_CONSUMER"
{
    "recipient": {
        "id": "3034506346629419"
    },
    "labels" : [
        ["name" : "VIP"],
        ["name" : "TOP_CONSUMER"]
    ],
    "request": {
        "method": "add_customer_label",
        "id" : "F4js0Za1",
        "meta": "This user purchased SKU1 with price 11235 USD"
    }
}

此API调用后:

  • 调用在VIP和TOP_CONSUMER受众皆存在时调用成功。
  • 如果3034506346629419是商户主页的合法PSID,则该用户被创建。如果之前就存在同ID用户,则不再新建
  • 用户3034506346629419加入VIP和TOP_CONSUMER受众

以下情况下,调用将失败。API会返回相应提示

  • 如果VIP或TOP_CONSUMER受众不存在,则调用失败,用户不会被加入任何受众。
  • 如果提供的PSID不是该主页的真实的PSID,则这个用户不会被创建,此API调用将会失败。

本API同样支持以PSID对应的已绑定账号的方式来指定用户。账号绑定的详情请见(这里)[account-link.md]

样例 - 给做过Account Linking的用户打标"VIP"和"TOP_CONSUMER"
{
    "recipient": {
        "email": "user@example.com"
    },
    "labels" : [
        ["name" : "VIP"],
        ["name" : "TOP_CONSUMER"]
    ],
    "request": {
        "method": "add_customer_label",
        "id" : "F4js0Za1",
        "meta": "This user purchased SKU1 with price 11235 USD"
    }
}

此API调用后:

  • 调用在VIP和TOP_CONSUMER受众皆存在,且user@example.com被绑定过的情况下调用成功。
  • user@example.com所对应的用户将被加入VIP和TOP_CONSUMER受众

以下情况下,调用将失败。API会返回相应提示

  • 如果VIP或TOP_CONSUMER受众不存在,则调用失败,用户不会被加入任何受众。
  • 如果user@example.com没有和任何PSID绑定,则调用失败。

移除用户标签

此API可以移除用户标签。

样例 - 将指定PSID的用户的标签"NEW_USERS"和"SILVER_LEVEL"移除
{
    "recipient": {
        "id": "3034506346629419"
    },
    "labels" : [
        ["name" : "NEW_USERS"],
        ["name" : "SILVER_LEVEL"]
    ],
    "request": {
        "method": "remove_customer_label",
        "id" : "F4js0Za1",
        "meta": "This user made the first-time purchase"
    }
}

当此API被调用后:

  • 用户3034506346629419将从NEW_USERS和SILVER_LEVEL受众中被移除。
  • 如果用户3034506346629419不存在,则调用结束。用户所在受众不会有任何影响
  • 该API会尽可能从指定的受众中移除用户。例如,如果NEW_USERS受众不存在,但SILVER_LEVEL存在,且用户已在SILVER_LEVEL受众中,则该用户将从SILVER_LEVEL受众中被移除。

此API同样也支持以已绑定账号的方式来指定用户。具体请详见给用户打标一节。

获取用户标签

此API可以获取一个用户所在的所有受众。

样例 - 获取指定PSID的用户之标签
{
    "recipient": {
        "id": "3034506346629419"
    },
    "request": {
        "method": "get_customer_labels",
        "id" : "F4js0Za1",
        "meta": ""
    }
}

当此API被调用后,将同步返回该用户所在的受众,格式如下:

{
    "result" : true,
    "data" : {
        "labels" : [
            {"name" : "VIP"},
            {"name" : "TOP_CONSUMERS"}
        ]
    }
}

当用户不存在,或者该用户没有所在受众时,返回

{
    "result" : true,
    "data" : {
        "labels" : [
        ]
    }
}

错误码列表

返回值 内容
10000 内部错误
10001 未指定API KEY
10002 无效的API KEY
10003 未指定Request id
10007 未指定recipient字段
10008 recipient结构不正确
10009 无效的用户指定方式
10010 用户不存在
10011 Request id与之前的重复
10100 参数无效
18000 内部错误
41041 Label字段结构错误
41042 给用户打标时,指定的标签不存在

用户指定

请参见 用户指南

results matching ""

    No results matching ""