用户标签管理

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

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

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

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

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

以下将分别详述。

字段释义

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

给用户打标

此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" : [
        ]
    }
}

错误码列表