傳送第一條訊息

10 分鐘、只用 curl，從註冊賬號走到“bob 在網頁裡收到 alice 的訊息”：

你會做的事	用到的介面
拿到應用的接入憑證	控制檯“概覽”
換取 App Token	POST /{org}/{app}/token
建立使用者 alice 和 bob	POST /{org}/{app}/users
以 alice 的身份給 bob 發訊息	POST /{org}/{app}/messages
檢視 bob 的會話和未讀數	GET /{org}/{app}/users/bob/conversations

準備：一個郵箱或手機號（註冊控制檯賬號），一個裝了 curl 的終端。

第 1 步：註冊並取得接入憑證

開啟控制檯，用郵箱或手機號註冊（詳見控制檯指南）。註冊後系統為你建立租戶和一個名為 demo 的應用，並直接開啟它的“概覽”。“接入憑證”裡有後面要用的全部資訊：

專案	例子	用途
app_key	1100250925#demo	客戶端登入用，# 前是 org_name，後是 app_name
REST 接入地址	https://api.example.com	所有介面的地址
client_id	YXA6MVMEOd4c…	換取 App Token
client_secret	點“檢視”，重新驗證身份後顯示	換取 App Token，只能放在服務端

測試和生產分開

建議測試、生產各用一個應用：點控制檯頂部的“建立應用”再建一個，見建立應用，再用它的憑證替換下面的變數。

第 2 步：設定環境變數

export IM_API="https://api.example.com"   # 概览中的 REST 接入地址
export ORG="1100250925"                   # 你的 org_name
export APP="demo"                         # 你的 app_name
export CLIENT_ID="YXA6MVMEOd4cqtAvTUnGUUCnTw"
export CLIENT_SECRET="YXA6sMvoBP0HiVoT-69b1BWXzip5_-Ii2ea8u0ph9ijVgck"

第 3 步：換取 App Token

curl -X POST "$IM_API/$ORG/$APP/token" \
  -H "Content-Type: application/json" \
  -d "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"$CLIENT_ID\",
    \"client_secret\": \"$CLIENT_SECRET\"
  }"

{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImsxIiwidHlwIjoiSldUIn0.eyJpc3Mi...",
  "expires_in": 604800,
  "application": "99579846509723648"
}

儲存下來，後面的請求都帶上它：

export APP_TOKEN="eyJhbGciOiJFZERTQSIsImtpZCI6ImsxIiwidHlwIjoiSldUIn0.eyJpc3Mi..."

App Token 7 天有效，有效期內請複用，見鑑權與 App Token。

第 4 步：建立 alice 和 bob

curl -X POST "$IM_API/$ORG/$APP/users" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "Alice#2026x", "nickname": "Alice"}'

curl -X POST "$IM_API/$ORG/$APP/users" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "password": "Bob#2026xx", "nickname": "Bob"}'

每個請求返回 201 Created 和使用者資料（username、nickname、status 等），欄位見使用者管理。

第 5 步：以 alice 的身份給 bob 發訊息

client_msg_id 由你生成，重試時帶同一個值，訊息不會重複：

curl -X POST "$IM_API/$ORG/$APP/messages" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "alice",
    "to_user": "bob",
    "type": "text",
    "body": { "text": "你好，Bob！" },
    "client_msg_id": "qs-0001"
  }'

{
  "conversation_id": "99582298709557248",
  "conversation_type": "single",
  "seq": 1,
  "message_id": "99582298747305984",
  "client_msg_id": "qs-0001",
  "sender": "alice",
  "recipient": "bob",
  "type": "text",
  "body": { "text": "你好，Bob！" },
  "created_at": "2026-10-02T19:04:30.171Z"
}

bob 線上時，他的所有裝置立即收到；不線上時，下次登入後同步到。訊息的全部欄位見訊息格式。

第 6 步：檢視 bob 的會話

curl "$IM_API/$ORG/$APP/users/bob/conversations" \
  -H "Authorization: Bearer $APP_TOKEN"

bob 有了一個與 alice 的單聊，未讀數為 1：

{
  "items": [
    {
      "conversation_id": "99582298709557248",
      "conversation_type": "single",
      "peer": "alice",
      "max_seq": 1,
      "unread_count": 1,
      "last_message_at": "2026-10-02T19:04:30.171Z"
    }
  ],
  "next_cursor": null
}

第 7 步：在網頁裡看到這條訊息

下載 Web Demo，填入 app_key、接入地址，用 bob 和他的密碼登入，就能看到本頁開頭截圖中的會話。在你自己的網頁中接入，見 Web SDK 快速整合；其他平臺見客戶端 SDK。

下一步

想做的事	去哪裡
用 Go、Python、Node.js 或 Java 開發服務端，省去管理 App Token、重試和分頁	服務端 SDK
讓你的使用者在 App 中登入（密碼或一次性登入憑證）	登入與登入裝置
介面的通用約定	接入概述、錯誤碼、限流與應用狀態
好友和群組	好友、群組管理
發圖片和檔案	上傳檔案、訊息格式
收到 IM 事件、發訊息前做業務校驗	事件回撥
給不線上的使用者發通知	離線推送
調整撤回時限、多端登入等行為	執行策略
會議、語音房（不建群）	加入第一個 RTC 頻道
接入 AI 機器人	AI 對話