接口对接文档规范说明（v0.18）

updated @ 2022.06.09

[TOC]

<div style="page-break-after: always;"></div>

一、提交聊天信息到对话后台的协议

1. NLU 语义请求参数

服务提供方提供一对 app_key/app_secret 以供接入方证明调用的技能和表明身份

2. NLU 语义请求示例

样例中的app_key为 testSkill，appSecret为 123456
md5(123456token1602687452461) 为 95b106504b59f7dfc7e45585b5f75657

{
    "app_key": "testSkill",
    "session_id": "QQ群ID",
    "timestamp": 1602687452461,
    "user_nick": "用户昵称",
    "user_token": "token",
    "user_ask": "用户问句内容",
    "message_id": "95b106504b59f7dfc7e45585b5f75657"
}

<div style="page-break-after: always;"></div>

3. NLU 语义响应参数

<div style="page-break-after: always;"></div>

4. NLU 语义响应示例

{
    "ret_code": 0,
    "message_id": "95b106504b59f7dfc7e45585b5f75657",
    "elapsed": 0,
    "timestamp": 1602728692078,
    "answers": [
        {
            "type": "text",
            "content": "文字回复内容"
        },
        {
            "type": "image",
            "content": "http://图片回复地址.jpg"
        },
        {
            "type": "ark",
            "content": "0"
        }
    ],
    "arks": [
        {
            "type": "ARK_DRAW",
            "contents": "...."
        }
    ],
    "task_confidence": 1.0,
    "task_finished": 10,
    "service": "ASK_AND_ANSWER",
    "stats": {
        "question_id": "5fbe53faadcdd3cec5224579",
        "quit_reason": "CMD",
        "answer_status": false
    },
    "reward_state": 10,
    "settlement": {
        "started_at": 1610329665,
        "rounds": 10,
        "user_answer_stat": [
            {
                "user_token": "token",
                "user_nick": "用户昵称",
                "correct_count": 1,
                ""
            }
        ]
    }
}

<div style="page-break-after: always;"></div>

5. NLU 语义响应打点上报数据

根据响应中的 service 字段不同，stats返回的数据点位也不一样，详细参见以下说明。

公共信息

1. session_id 请求中传过来的会话ID
2. user_token 请求中的QQ用户TOKEN（基本等价于OPENID
3. timestamp 响应中的响应时间戳

ASK_AND_ANSWER 你问我答

GUESS_IDIOM 成语接龙

EVERYDAY_DRAW 普通每日签到

待定

CHANNEL_DRAW QQ频道问答签到

待定

<div style="page-break-after: always;"></div>

6. 结算统计数据

当一轮游戏结束时，会返回结算数据。

settlement 字段结构

<div style="page-break-after: always;"></div>

7. ARK 种类及详细结构

公共字段：
type，代表该 ark 的结构类型。
contents，代表该 ark 的实际数据。

ARK_DRAW

contents中的数据

ARK_ASSISTANT_ATTRIBUTE

contents中的数据

<div style="page-break-after: always;"></div>

8. NLU 语义响应错误码

对于所有发生的异常，响应中会多message 和 payload 字段，协助开发调试，不需要回复给用户

二、各个技能返回值说明

1. 群聊服务：问答

2. 群聊服务：成语接龙

3. 群聊服务：抽签签到

4. 频道服务：频道普通/问答签到

5. 私人助手：C2C签到

三、AMS奖励下发状态回调

1. AMS奖励下发状态回调请求参数

2. AMS奖励下发状态回调请求示例

{
    "service": "kpl.channel.lottery",
    "results": [
        {
            "appid": "xxxxxx",
            "guildid": "xxxxxx",
            "openid": "xxxxxx",
            "nounce": "xxxxxx",
            "retcode": "0",
            "msg": "SUCCESS"
        }
    ]
}

3. AMS奖励下发状态回调响应参数

4. AMS奖励下发状态回调响应示例

{
    "ret_code": 0
}