Go SDK 概述

Go SDK 让你在 Go 程序中接入 IM 服务：登录与令牌续期、REST API、WebSocket 长连接与断线重连、事件订阅、登录后同步与内存缓存，全部封装在一个包里，只依赖 Go 标准库。它不提供界面，适合把 IM 能力嵌进你自己的程序：

聊天机器人：订阅新消息事件，自动回复，或把消息转发到其他系统；
业务服务端集成：以某个用户的身份收发消息，如客服号、通知号，或在业务流程中代用户发消息；
桌面与无人值守客户端：跑在服务器、网关或工控机上的常驻程序，靠长连接实时收发；
运维与通知工具：脚本化的消息通知、群管理和例行检查。

cli, err := im.New(im.Config{
	AppKey: "1575529652#demo",        // 组织#应用
	APIURL: "https://im.example.com", // IM 服务端 REST 地址
})
if err != nil {
	return err
}
if _, err := cli.Login(ctx, im.LoginTicket, "alice", ticket); err != nil {
	return err // 用业务服务端签发的凭证登录
}
cli.OnEvent(func(e im.Event) { /* 处理 message.received 等事件 */ })
if err := cli.ConnectWait(ctx); err != nil {
	return err // 建立长连接并等待认证完成
}
_, err = cli.SendText(ctx, im.ToUser("bob"), "你好", nil)

完整的第一个程序见快速集成。

选择客户端还是服务端 SDK

需求	SDK	身份与实时入口
以用户身份登录、收发消息、同步会话	本页的 Go 客户端 SDK（包名 `im`）	用户票据或开发密码登录，通过 WebSocket 收事件
管理应用用户和群组、签发票据、接收签名回调	Go 服务端 SDK（包名 `drim`）	Client ID / Client Secret 换取 App Token，通过 HTTP 接收回调

两套 SDK 的 Demo 分别见客户端 Demo和服务端 Demo，配置不能混用。

能做什么

Client 的方法按功能分组，与文档页一一对应：

能力	主要方法（`Client` 上）	文档
用户	`Me` `UpdateProfile` `SetPassword` `GetUser` `LookupUsers` `Sessions` `RevokeSession`	用户、好友与在线状态
好友与黑名单	`Friends` `SendFriendRequest` `AcceptFriendRequest` `RemoveFriend` `Blacklist` `BlockUser`	用户、好友与在线状态
在线状态	`QueryPresence` `SubscribePresence` `UnsubscribePresence`	用户、好友与在线状态
群组	`CreateGroup` `Group` `GroupMembers` `AddGroupMembers` `ApplyJoinGroup` `JoinByLink`	群组
会话	`RecentConversations` `SingleConversation` `Read` `UnreadCount` `SetConversationPinned` `SetConversationDraft`	会话
消息	`SendText` `Send` `SendMedia` `SendReply` `Recall` `AddReaction` `Typing` `MessageLookup`	消息
媒体	`Upload`（预签名直传）、`DownloadURLs`、`Download`	文件与图片
长连接	`Connect` `ConnectWait` `Disconnect` `State` `OnState`	初始化、登录与连接
事件与同步	`OnEvent` `SyncAll` `FetchMessages` `History`	事件与同步
内存 Store	`Store()`：`Conversations` `Messages` `LastMessages` `Typing`	事件与同步

REST 方法在未连接时也可以直接调用；建立长连接后才能接收事件。发消息在连接可用时自动优先走长连接（低延迟），连接不可用时自动改走 REST。

核心概念

概念	说明
`im.Config` / `im.New`	创建客户端，只检查参数、不做网络请求，见初始化、登录与连接
`Session`	登录成功后的凭据：访问令牌、续期令牌、会话 ID、本人资料，SDK 自动续期
`Target`	消息的发送目标：`im.ToUser("bob")` 发给用户，`im.ToGroup("群 ID")` 发给群
`Event`	长连接推送的服务端事件，用 `OnEvent` 订阅，见事件与同步
`Store`	进程内存中的会话与消息缓存，由同步和事件自动维护，见事件与同步
`APIError`	服务端返回的业务错误，用 `im.IsCode(err, im.CodeXxx)` 判断错误码

能力边界

没有的功能：聊天室、音视频通话、独立 RTC 频道、离线推送都不在 Go SDK 的范围内，需要它们时使用 Web SDK 或 Flutter SDK。Go 程序通常常驻在线，断线期间错过的消息在下次连接后通过同步补齐，不依赖系统推送。
数据缓存是进程内存：Store() 是线程安全的内存缓存，不是本地数据库。进程重启后缓存清空，重新登录并做一次全量同步（SyncAll）后从服务端恢复。需要离线保存历史时，由你自行落库。
一个 Client 对应一个登录用户：一条长连接对应一次登录。同一进程要操作多个账号时创建多个 Client 实例，它们互不相干。

不要在客户端程序中保存服务端凭据

App Token 和 Client Secret 只能保存在你的业务服务端。Go 程序应当用业务服务端签发的登录凭证登录（im.LoginTicket），密码登录（im.LoginPassword）只作为开发测试的捷径。

下载与安装

下载 Go 客户端 SDK + Demo（1.0.0-alpha） · 下载 SHA256 校验文件

Go 1.26.5 或以上，仅依赖标准库；
包中包含 SDK、浏览器 Demo、文档和校验清单，解压后进入 deeprespond-im-go-sdk-1.0.0-alpha；
在 sdk/go 运行 Demo；业务工程通过本地 replace 接入，见快速集成；
模块标识 github.com/deeprespond/im/sdk/go，包名 im。该标识用于 Go 导入，本地替换从压缩包加载代码；
完整解压目录需要保留，移动后同步更新业务工程的 replace 路径。

当前为 Alpha 源码版本 1.0.0-alpha。本地引用使用的 v0.0.0 不是发布版本；升级时重新下载并核对文件校验值。

与其他客户端 SDK 的关系

Go SDK 与 Web、Flutter SDK 面向同一套客户端接口（REST + WebSocket），数据模型和事件一致，但它是一个薄封装：只包含 REST、长连接、同步引擎和内存 Store，界面与本地持久化完全由你自己实现。

	Web / Flutter SDK	Go SDK
定位	完整的客户端：界面、本地数据库、发送队列	薄封装：REST + WS + 同步引擎 + 内存 Store
数据存储	IndexedDB（Web）/ SQLite（Flutter）本地数据库	进程内存 `Store`，重启后靠 `SyncAll` 恢复
消息发送	进入本地发送队列，失败自动重试	调用返回即最终结果，失败由你决定是否重试
读取数据	订阅列表，变化时收到新快照	直接读 `Store`，或订阅事件维护自己的数据结构
界面	Flutter 组件、浏览器页面	无，适合机器人与服务端程序

第一次接入请先看快速集成；Client 的全部初始化选项、登录与长连接行为见初始化、登录与连接。

错误处理

REST 与 WS 返回的业务错误统一为 *im.APIError（Code 机器可读、Message 人类可读、RequestID 服务端排障 ID），用 im.IsCode 按错误码判断：

if _, err := cli.SendText(ctx, im.ToUser("bob"), "你好", nil); err != nil {
	if im.IsCode(err, im.CodeRateLimited) {
		time.Sleep(time.Second) // 限流，稍后重试
	}
}

常见错误码有 unauthenticated（未登录或令牌失效）、forbidden、permission_denied、not_found、invalid_argument、version_conflict、rate_limited、unavailable、internal，完整说明见错误处理。

下一步

快速集成：从零写一个能登录、收发消息的最小程序；
初始化、登录与连接：全部配置项、令牌持久化、连接状态与断线重连；
事件与同步：事件列表、SyncAll 全量同步与 Store 的读法。

Go SDK 概述 ​

选择客户端还是服务端 SDK ​

能做什么 ​

核心概念 ​

能力边界 ​

下载与安装 ​

与其他客户端 SDK 的关系 ​

错误处理 ​

下一步 ​