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)

完整的第一個程式見快速整合。下圖是倉庫自帶的 Go Demo：Go 程序登入 IM，內嵌網頁顯示會話和訊息。

專案	說明
當前版本	v1.0.2，MIT 許可證（版本與支援狀態）
安裝	`go get github.com/DeepRespond-AI/deeprespond-im-go-sdk@v1.0.2`
環境	Go 1.26.5 以上，只依賴標準庫
原始碼	GitHub

選擇客戶端還是服務端 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）只作為開發測試的捷徑。

下載與安裝

GitHub 倉庫

當前釋出版本為 v1.0.2（MIT 許可證），Go 1.26.5 或以上，僅依賴標準庫。在業務 Go 工程中安裝：

bash

go get github.com/DeepRespond-AI/deeprespond-im-go-sdk@v1.0.2

模組路徑為 github.com/DeepRespond-AI/deeprespond-im-go-sdk，包名為 im。完整接入示例見快速整合。

需要執行 Demo 或離線檢視原始碼時：下載 Go 客戶端 SDK + Demo（1.0.2） · SHA256 校驗檔案。解壓後進入 deeprespond-im-go-sdk-1.0.2，執行 go run ./demo。

從早期版本升級時，先刪掉本地的 replace，把匯入路徑改為上面的公開模組路徑，再執行 go mod tidy。各版本的變化見 GitHub 上的 CHANGELOG。

與其他客戶端 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 的關係 ​

錯誤處理 ​

下一步 ​