update_session_meta,收一个 session_meta_updated用户想给会话改个名字时,前端往已连接的 WebSocket 发一条消息,后端写库后回一条确认。下面是请求/回包的真实格式、所有错误码、和能直接 copy 的代码。
同一条 WebSocket 上,你发上行、后端回下行。connection_id 不用你管,服务端自己注入。
WebSocket 上 send 一段 JSON 文本。外层 type 固定,业务数据放 data 里。
{
"type": "update_session_meta",
"data": {
"session_id": "sess_3f9a...", // 当前 canvas 绑定的 session
"meta": {
"session_name": "Q3 出海短视频脚本" // 会自动 trim 首尾空格
}
}
}
| 字段 | 必填 | 规则 |
|---|---|---|
| type | 是 | 固定 "update_session_meta" |
| data.session_id | 是 | 要改的会话 id;连接必须已 bind 过它(见下方前提) |
| data.meta | 是 | 非空对象;键只能是白名单字段,目前只有 session_name |
| data.meta.session_name | 是 | 非空字符串,自动 trim,trim 后长度 ≤ 200 |
meta 里放任何非 session_name 的键(比如 user_email、session_id)会被直接拒,不会静默忽略。目前白名单只开了 session_name 一个字段。
成功和失败是两种 type,都在同一条连接上推回来。
{
"type": "session_meta_updated",
"data": {
"session_id": "sess_3f9a...",
"meta": { "session_name": "Q3 出海短视频脚本" } // 已是 trim 后的最终值
}
}
{
"type": "error",
"data": {
"error": "session_name too long (max 200)",
"timestamp": "2026-06-05T12:00:00.000000"
}
}
注意:回包里只回发起的那条连接(不广播给同会话的其它 tab)。如果你开了多 tab,需要本地自己同步显示。
失败一律 type="error",data.error 是下面这些原文串,可据此提示用户。
| data.error 原文 | 什么时候 |
|---|---|
| session_id is required | 没传 data.session_id |
| meta must be a non-empty object | 没传 meta,或 meta 是 {} / 非对象 |
| uneditable fields: [...] | meta 里有 session_name 之外的键 |
| session_name must be a non-empty string | 名字为空 / 全空格 / 非字符串 |
| session_name too long (max 200) | trim 后超过 200 字 |
| Connection has no access to session ... | 这条连接没 bind 过该 session(见前提) |
| Invalid JSON | send 的不是合法 JSON 文本 |
改名前,这条 WebSocket 连接必须已经「持有」这个 session,否则报 no access。
create_session —— 建完这条连接自动持有它。session_bind + {session_id} —— 持有后才能改名。封装一个 Promise,发出去后用 type 匹配回包;成功 resolve、error reject。
function updateSessionName(ws, sessionId, name) { return new Promise((resolve, reject) => { const onMsg = (ev) => { const msg = JSON.parse(ev.data); if (msg.type === "session_meta_updated" && msg.data?.session_id === sessionId) { ws.removeEventListener("message", onMsg); resolve(msg.data.meta.session_name); // trim 后的最终名字 } else if (msg.type === "error") { ws.removeEventListener("message", onMsg); reject(new Error(msg.data?.error || "update failed")); } }; ws.addEventListener("message", onMsg); ws.send(JSON.stringify({ type: "update_session_meta", data: { session_id: sessionId, meta: { session_name: name } }, })); }); } // 用法 try { const finalName = await updateSessionName(ws, currentSessionId, inputValue); showToast(`已改名:${finalName}`); } catch (e) { showToast(e.message); // 直接拿后端错误串提示 }
生产里建议给 onMsg 加个超时兜底(比如 8s 没等到对应回包就 reject),并注意上面用 session_id 匹配回包——多个并发改名请求时靠它区分。