微信小程序 騰訊IM 單發單聊消息

  • 管理員向帳號發消息,接收方看到消息發送者是管理員。
  • 管理員指定某一帳號向其他帳號發消息,接收方看到發送者不是管理員,而是管理員指定的帳號。
  • 該接口不會檢查發送者和接收者的好友關係(包括黑名單),同時不會檢查接收者是否被禁言。
  • 使用服務端集成 REST API 發送單聊消息時,存在是否將消息同步至發送方(管理員帳號或者由管理員指定的某帳號)問題,同步方式包括在線終端和漫遊,REST API 提供 SyncOtherMachine 參數用於說明是否進行同步,詳細使用方式參見下文請求包示例。
  • https://console.tim.qq.com/v4/openim/sendmsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
  • 請求參數說明

    下表僅列出調用本接口時涉及修改的參數及其說明,更多參數詳情請參考 REST API 簡介

    參數 說明
    v4/openim/sendmsg 請求接口
    sdkappid 創建應用時即時通信 IM 控制檯分配的 SDKAppID
    identifier 必須爲 App 管理員帳號,更多詳情請參見 App 管理員
    usersig App 管理員帳號生成的簽名,具體操作請參見 生成 UserSig
    random 請輸入隨機的32位無符號整數,取值範圍0 - 4294967295

    最高調用頻率

    200次/秒。

    請求包示例

    本文以發送文本消息爲例,如需發送其他類型的消息,只需將 MsgBody 字段改成相應消息類型即可,更多詳情請參見 消息格式描述

    管理員向其它帳號發消息

    !若不希望將消息同步至 From_Account,則 SyncOtherMachine 填寫2。 若希望將消息同步至 From_Account,則 SyncOtherMachine 填寫1。

    {
        "SyncOtherMachine": 2, // 消息不同步至發送方
        "To_Account": "lumotuwe2",
        "MsgLifeTime":60, // 消息保存60秒
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
    }
    

    管理員指定某一帳號向其它帳號發送消息,同時設置離線推送信息,並且不將消息同步至 From_Account

    !若不希望將消息同步至 From_Account,則 SyncOtherMachine 填寫2。

    {
        "SyncOtherMachine": 2,
        "From_Account": "lumotuwe1",
        "To_Account": "lumotuwe2",
        "MsgLifeTime":3600, // 消息保存一小時
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ],
        "OfflinePushInfo": {
            "PushFlag": 0,
            "Desc": "離線推送內容",
            "Ext": "這是透傳的內容",
            "AndroidInfo": {
                "Sound": "android.mp3"
            },
            "ApnsInfo": {
                "Sound": "apns.mp3",
                "BadgeMode": 1, // 這個字段缺省或者爲 0 表示需要計數,爲 1 表示本條消息不需要計數,即右上角圖標數字不增加
                "Title":"apns title", // apns title
                "SubTitle":"apns subtitle", // apns subtitle
                "Image":"www.image.com" // image url
            }
        }
    }
    

    管理員指定某一帳號向另一帳號發送消息,同時將消息同步到 From_Account 發送方終端

    !若希望將消息同步至 From_Account,則 SyncOtherMachine 填寫1。

    {
        "SyncOtherMachine": 1, // 消息同步至發送方
        "From_Account": "lumotuwe1",
        "To_Account": "lumotuwe2",
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
    }
    

    請求包字段說明

    字段 類型 屬性 說明
    SyncOtherMachine Integer 選填 1:把消息同步到 From_Account 在線終端和漫遊上;
    2:消息不同步至 From_Account;
    若不填寫默認情況下會將消息存 From_Account 漫遊
    From_Account String 選填 消息發送方 UserID(用於指定發送消息方帳號)
    To_Account String 必填 消息接收方 UserID
    MsgLifeTime Integer 選填 消息離線保存時長(單位:秒),最長爲7天(604800秒)
    • 若設置該字段爲0,則消息只發在線用戶,不保存離線
    • 若設置該字段超過7天(604800秒),仍只保存7天
    • 若不設置該字段,則默認保存7天
    MsgRandom Integer 必填 消息隨機數,由隨機函數產生,用於後臺定位問題
    MsgTimeStamp Integer 選填 消息時間戳,UNIX 時間戳(單位:秒)
    MsgBody Object 必填 消息內容,具體格式請參考 消息格式描述(注意,一條消息可包括多種消息元素,MsgBody 爲 Array 類型)
    MsgType String 必填 TIM 消息對象類型,目前支持的消息對象包括:TIMTextElem(文本消息),TIMFaceElem(表情消息),TIMLocationElem(位置消息),TIMCustomElem(自定義消息)
    MsgContent Object 必填 對於每種 MsgType 用不同的 MsgContent 格式,具體可參考 消息格式描述
    OfflinePushInfo Object 選填 離線推送信息配置,具體可參考 消息格式描述

    應答包體示例

  • 正常應答
  • {
        "ActionStatus": "OK", 
        "ErrorInfo": "", 
        "ErrorCode": 0, 
        "MsgTime": 1497238162,
        "MsgKey": "89541_2574206_1572870301"
    }
    
  • 異常應答
  • {
        "ActionStatus": "FAIL", 
        "ErrorInfo": "Fail to Parse json data of body, Please check it", 
        "ErrorCode": 90001
    }
    

    應答包字段說明

    字段 類型 說明
    ActionStatus String 請求處理的結果,OK 表示處理成功,FAIL 表示失敗
    ErrorCode Integer 錯誤碼,0表示成功,非0表示失敗
    ErrorInfo String 錯誤信息
    MsgTime Integer 消息時間戳,UNIX 時間戳
    MsgKey String 消息唯一標識,用於撤回。長度不超過50個字符

    錯誤碼說明

    除非發生網絡錯誤(例如502錯誤),否則該接口的 HTTP 返回碼均爲200。真正的錯誤碼,錯誤信息是通過應答包體中的 ErrorCode、ErrorInfo 來表示的。 公共錯誤碼(60000到79999)參見 錯誤碼 文檔。 本 API 私有錯誤碼如下:

    錯誤碼 描述
    20001 請求包非法
    20002 UserSig 或 A2 失效
    20003 消息發送方或接收方 UserID 無效或不存在,請檢查 UserID 是否已導入即時通信 IM
    20004 網絡異常,請重試
    20005 服務器內部錯誤,請重試
    20006 觸發發送單聊消息之前回調,App 後臺返回禁止下發該消息
    90001 JSON 格式解析失敗,請檢查請求包是否符合 JSON 規範
    90002 JSON 格式請求包中 MsgBody 不符合消息格式描述,或者 MsgBody 不是 Array 類型,請參考 TIMMsgElement 對象 的定義
    90003 JSON 格式請求包體中缺少 To_Account 字段或者 To_Account 字段不是 String 類型
    90005 JSON 格式請求包體中缺少 MsgRandom 字段或者 MsgRandom 字段不是 Integer 類型
    90006 JSON 格式請求包體中 MsgTimeStamp 字段不是 Integer 類型
    90007 JSON 格式請求包體中 MsgBody 類型不是 Array 類型,請將其修改爲 Array 類型
    90009 請求需要 App 管理員權限
    90010 JSON 格式請求包不符合消息格式描述,請參考 TIMMsgElement 對象 的定義
    90012 To_Account 沒有註冊或不存在,請確認 To_Account 是否導入即時通信 IM 或者是否拼寫錯誤
    90026 消息離線存儲時間錯誤(最多不能超過7天)
    90031 JSON 格式請求包體中 SyncOtherMachine 字段不是 Integer 類型
    90044 JSON 格式請求包體中 MsgLifeTime 字段不是 Integer 類型
    91000 服務內部錯誤,請重試
    90992 服務內部錯誤,請重試;如果所有請求都返回該錯誤碼,且 App 配置了第三方回調,請檢查 App 服務器是否正常向即時通信 IM 後臺服務器返回回調結果
    93000 JSON 數據包超長,消息包體請不要超過 8k
    90048 請求的用戶帳號不存在

    接口調試工具

    通過 REST API 在線調試工具 調試本接口。

    參考

    批量發單聊消息(v4/openim/batchsendmsg) 查詢單聊消息(v4/openim/admin_getroammsg) 撤回單聊消息(v4/openim/admin_msgwithdraw

    可能觸發的回調

  • 發單聊消息之前回調
  • 發單聊消息之後回調
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章