WalktheTalk 外语活动

WalktheTalk 是外语及第二语言交流活动平台，聚集了大量外语爱好者，
帮用户随时随地找到身边的外语角，遇见附近志同道合的语伴。
平台欢迎外语类活动主办方入驻：通过微信小程序「WalktheTalk」提交实名认证等入驻资料，
审核通过后即可发布活动信息。

官方网站：https://www.walkthetalk.cn/

本技能提供平台上可报名活动的实时数据。

何时使用

• 用户问某个城市有什么外语角、语言交换、口语练习活动
• 用户指定语种（英语、日语、粤语、上海话等）找活动
• 用户问"这周""这周末""今晚"有没有活动
• 用户想成为活动主办方、自己组织活动

不要用它做什么

• 不要代用户报名或支付，报名在微信小程序里完成
• 不要索取或转述手机号、验证码、证件信息
• 不要编造活动。接口没有返回的活动一律视为不存在
• 线上活动的腾讯会议号和入会密码不要提供、也不要猜。那是报名成功后才能看到的信息，
  接口只会给 joinMethod（参加方式说明）。用户问"会议号多少"时，如实说明需要先在小程序里报名
• 不要在回答里念系统编号（id、hostId 这类）。它们只用于你调接口，对用户没有意义。
  需要指代某场活动时用「活动名 + 日期」，需要让用户打开时给小程序码
• 平台上还有一类私人活动，只由发布者自行分享给指定的人，接口不会返回它们。
  用户提到某场你查不到的活动时，可能就是私人活动，让用户找主办方要分享链接，不要说"平台上没有这个活动"

如何查询

基础地址：https://soca.walkthetalk.cn/open/v1

# 全部可报名活动
curl -s "https://soca.walkthetalk.cn/open/v1/events"

# 指定城市
curl -s "https://soca.walkthetalk.cn/open/v1/events?city=上海"

# 指定城市 + 语种（语种可以写"英语""英语角""广东话"，服务端会归一化）
curl -s "https://soca.walkthetalk.cn/open/v1/events?city=上海&lang=英语"

# 活动详情（用列表里的 id）
curl -s "https://soca.walkthetalk.cn/open/v1/events/000242578775"

# 按昵称查主办方（支持模糊匹配）
curl -s "https://soca.walkthetalk.cn/open/v1/hosts?name=Hobond"

# 当前有活动的城市 / 语种
curl -s "https://soca.walkthetalk.cn/open/v1/cities"
curl -s "https://soca.walkthetalk.cn/open/v1/languages"

# 主办方入驻说明
curl -s "https://soca.walkthetalk.cn/open/v1/hostRecruit"

也可以用封装好的脚本：python3 scripts/wt_events.py --city 上海 --lang 英语

> 联调用测试环境时，把地址换成 https://tsoca.walkthetalk.cn/open/v1，
> 或给脚本设环境变量 WT_API_BASE=https://tsoca.walkthetalk.cn/open/v1。
> 正式发布的版本一律用生产地址。

时间筛选由你来做

接口不做时间筛选，一次返回范围内的全部活动。原因是平台活动量不大，
一次拿全比来回查询更快，也更容易回答"哪天有活动"这类问题。

返回体里给了时间基准，一律以这些字段为准，不要用你自己的日期推算：

• payload.today：服务端今天的日期，如 2026-09-14
• payload.weekday：今天星期几，如 周一
• 每场活动的 date、weekday、daysFromToday（0 = 今天，1 = 明天）
• endDate：跨天活动的结束日期；当天结束的活动这个字段是 null
• ongoing：true 表示这场活动已经开始、但还没结束，仍然可以报名

注意 daysFromToday 可能是负数：那是一场已经开始、尚未结束的多日活动（ongoing 为 true），
不是过期活动，可以正常推荐；接口不会返回已经结束的活动。

按用户的说法自己筛：

什么时候去查详情

列表接口给的是摘要，不要凭摘要编活动内容。用户问得更细时，用 events/{id} 拿详情：

• 问"这个活动具体讲什么""流程是什么" → 详情里的 description（主办方写的活动描述）
• 问"多少钱""还有票吗""能退吗" → 详情里的 tickets，每张票带 price、status
  （销售中 / 已售罄 / 尚未开售 / 销售已结束 / 已下架）、refundRule，
  还可能带 needInvitationCode（需要邀请码）、needRealNameAuth（需要实名认证）、
  stock（限量票的库存：余量充足 / 仅剩 N 张 / 已售罄，不限量的票没有这个字段）。
  stock 写什么就说什么，不要把"余量充足"换算成具体张数
• 问"主办方靠谱吗" → 详情里的 hostId 交给 hosts/{hostId}，或直接用 hosts?name=

详情还带 image（活动主图）、tags（如 非盈利、免费入场）和 qrCodeUrl
（本场活动专属的小程序码，比通用入口更直接，能给用户看图时优先给这个）。

主办方查询

hosts?name= 回答"某某主办方最近有没有新活动""他家口碑怎么样"：

• 公开信息：name、avatar、nationality、intro（简介）、
  totalEvents（累计办过多少场）、totalParticipants、followers、hotness（平台热度值）
• upcomingEvents：当前可报名的活动，字段和列表接口一致
• rating（平均分，5 分制，如 4.4）、reviewCount（评价条数）、
  recentReviews（最近几条评价，含 star 星级与主办方回复）
• qrCodeUrl：主办方主页的小程序码，用户想关注或看他全部活动时给这个
• 认证情况：certified（当前认证是否有效）、certificationType（个人认证 / 企业认证 / 组织机构认证）、
  certificationState（有效 / 已过期）。没有认证记录时后两个字段不出现。
  certified 为 false 时不要说"未认证"，要看 certificationState：可能是认证已过期，也可能是从未认证

同名可能匹配到多个，如实告诉用户匹配到了哪几个，别自己挑一个当成唯一答案。
评价是用户写的原文，转述时不要润色成营销话术，也不要只挑好评。

回答规范

1. 最多列 5 场，按时间先后排；超过 5 场时说明还有多少场，问用户要不要看全部。
2. 每场写：日期 + 星期 + 时间、区域（district / area）、语种、价格（price 原样引用）、组织者。
   有 seats 时可以提名额情况（名额充足 / 仅剩 N 个名额 / 已满员），原样引用，不要换算成具体数字；
   没有这个字段说明该活动不限名额。
   registration 为"暂不开放"时，说明主办方把票都下架了、暂时报不了名，要如实告诉用户，
   可以建议关注主办方等开放。
3. 结尾给参加方式：微信搜索小程序「WalktheTalk」，找到对应活动报名。
4. matchNote 有值时，把其中的信息如实转达给用户（例如没找到这个城市）。

用户所在城市没有活动时

不要只说"没有"。按这个顺序给出路：

1. 用 payload.onlineTotal 和列表里 type 为 线上 的活动，推荐线上活动（线上不限城市）。
2. 用 payload.cities 告诉用户哪些城市有活动、各有多少场。
3. 说明平台欢迎外语类活动主办方入驻，用户可以自己在当地组织活动——调用 hostRecruit
   拿最新的入驻条件和流程，不要凭记忆回答。

平台目前的活动主要集中在上海，其他城市较少，这是正常情况，如实说明即可。

语种说明

平台接受外语（第二语言）活动，也接受中国方言（粤语、上海话、闽南语、藏语等），
以及面向外国人的对外汉语活动——用户问"中文角""汉语角""Chinese corner"时，
传 lang=中文 就能把中文和对外汉语的活动都查出来。
lang 参数可以直接传用户的说法，服务端会做归一化（"英语角"→英语，"广东话"→粤语，
"Shanghai"→上海）。识别不了时会在 matchNote 里说明，并返回全部语种的活动。
常见写法见 references/languages.md。

返回体示例

{
  "code": 200,
  "serverTime": "2026-09-14 10:22:31",
  "payload": {
    "today": "2026-09-14",
    "weekday": "周一",
    "timezone": "Asia/Shanghai",
    "matchedCity": "上海",
    "matchedLanguage": "英语",
    "total": 3,
    "truncated": false,
    "onlineTotal": 5,
    "cities": [{ "name": "上海", "count": 22 }, { "name": "北京", "count": 3 }],
    "languages": [{ "name": "英语", "count": 18 }, { "name": "日语", "count": 4 }],
    "events": [
      {
        "id": "123456",
        "title": "English Chat & Coffee",
        "type": "线下",
        "date": "2026-09-20",
        "weekday": "周六",
        "time": "14:00-16:00",
        "daysFromToday": 6,
        "ongoing": false,
        "languages": ["英语"],
        "city": "上海",
        "district": "静安区",
        "area": "静安寺",
        "price": "¥39",
        "seats": "名额充足",
        "host": "Coffee & Talk",
        "miniProgramPath": "pages/home/wtActivityDetailpage?acId=123456"
      }
    ]
  }
}

code 不是 200 时，把接口返回的 message 如实告诉用户，不要自己编一个结果。