发送消息

POST

/im/v2/conversations/{conversation_id}/messages

请求参数

Path 参数

conversation_id

string

必需

会话 ID。会话 ID 需要用户自行拼装，拼装规则：
sender_id|conversation_type|receiver_id
sender_id：会话消息发送者的账号 ID，String 类型
conversation_type：会话类型，1：单聊会话；2：高级群会话；3：超大群会话
receiver_id：接收会话消息的账号 ID 或群组 ID
单聊会话时为消息接收者的账号 ID；高级群会话时为接收消息的高级群 ID；超大群会话时为超大群 ID。

示例值:

apifoxtest1|1|accid4

Header 参数

AppKey

string

必需

默认值:

X-custom-traceid

string

可选

默认值:

{% mock 'uuid' %}

Nonce

string

必需

默认值:

CurTime

string

必需

默认值:

CheckSum

string

必需

默认值:

Body 参数application/json

sender_no_sense

boolean

发送方无感知

可选

发送方是否无感知，默认为 false。若设置为无感知（true），则消息发送者无该消息的多端、漫游、历史记录等信息。查询历史消息时可设置是否在历史记录查询结果中包含无感知消息，具体参见分页查询历史消息。发送者和接收者必须有一方感知，即不能将两者都设置为无感知。

默认值:

false

receiver_no_sense

boolean

接收方无感知

可选

接收方是否无感知，默认为 false。若设置为无感知（true），则消息接收者无该消息的多端、漫游、历史记录等信息。查询历史消息时可设置是否在历史记录查询结果中包含无感知消息，具体参见分页查询历史消息。

默认值:

false

extension

string

开发者扩展字段

可选

开发者扩展字段，JSON 格式，长度上限为 1024 位字符。例如："{"k":"v"}"

message

object

消息体

必需

消息体。

message_type

integer

消息类型

必需

消息类型。 0：文本消息 1：图片消息 2：语音消息 3：视频消息 4：地理位置消息 6：文件消息 10：提示消息 100：自定义消息对于未开通安全通（即易盾反垃圾）功能的应用，自定义消息不会过内容审核。

sub_type

integer

自定义消息子类型

可选

自定义消息子类型，大于 0。message_type = 100 时该字段才有效。

> 0

text

string

文本消息

可选

对于文本消息和提示消息，该字段必填，值为消息内容，长度上限 5000 位字符。对于非文本/提示消息，该字段非必填，值为描述信息，可用于全文关键字搜索历史消息，长度上限 500 位字符。

<= 500 字符

attachment

object

多媒体消息内容

可选

非文本消息/提示消息的属性或自定义消息内容，长度上限 5000 位字符。对于非文本消息/提示消息，该字段必填，每种消息的属性参数见：消息格式示例。

message_client_id

string

客户端消息id（不传则自动生成）

可选

客户端消息id（不传则自动生成）

message_config

object

消息配置

可选

消息配置项。

unread_enabled

boolean

未读数

可选

该消息是否需要计入未读数。默认为 true（计入）。

默认值:

true

mutil_sync_enabled

boolean

多端同步

可选

该消息是否需要发送方多端同步。默认为 true（同步）。

默认值:

true

offline_enabled

boolean

存离线

可选

是否需要存离线消息，默认为 true（存储）。离线消息指不在线时其他用户发来的消息。如果存离线，在用户下次登录时，IM 服务端会自动将离线期间暂存的离线消息自动下发到客户端 SDK。单聊场景下发最近 30 天内的最新的 5000 条离线消息，且每个会话最多 100 条最新的离线消息。群聊场景下发最近 30 天内的离线消息，且每个群聊会话最多下发 100 条最新的离线消息。

默认值:

true

history_enabled

boolean

云端历史

可选

该消息是否存云端历史。默认为 true（存储）。

默认值:

true

roaming_enabled

boolean

漫游

可选

该消息是否需要漫游。默认为 true（漫游）。

默认值:

true

conversation_update_enabled

boolean

更新会话

可选

是否将该消息更新至会话列表服务中本会话的最后一条消息。默认为 true（更新）。

默认值:

true

route_config

object

抄送配置

可选

抄送相关配置项。

route_enabled

boolean

是否抄送

可选

该消息是否需要抄送至指定的应用服务器（需要为应用开通消息抄送功能），默认为 true（抄送）。

默认值:

true

route_environment

string

抄送环境

可选

抄送相关配置项。

push_config

object

推送配置

可选

推送相关配置项。

push_enabled

boolean

是否推送

可选

该消息是否需要 APNs 推送或 Android 系统通知栏推送，默认为 true（推送）。只有该字段为 true 时，推送相关参数才会生效。

默认值:

true

push_nick_enabled

boolean

推送是否带昵称

可选

推送文案是否需要带上昵称，默认为 true（带昵称）。

默认值:

true

push_content

string

推送文案

可选

推送文案，长度上限 500 位字符。如果不填，则使用默认推送文案。推送文案的显示规则如下： push_content 不为空且 push_nick_enabled = true，最终推送文案为：推送者昵称+ push_content push_content 不为空且 push_nick_enabled = false，最终推送文案为：push_content push_content 为空且 push_nick_enabled = true，最终推送文案为：推送者昵称+默认文案 push_content 为空且 push_nick_enabled = false，最终推送文案为：默认文案其中，根据消息类型，默认文案分为以下几种：文本消息默认文案：发来了一条消息图片消息默认文案：发来了一张图片语音消息默认文案：发来了一段语音视频消息默认文案：发来了一段视频地理位置默认文案：发来了一个地理位置文件消息默认文案：发来了一个文件语音聊天邀请消息默认文案：发来了语音聊天邀请视频聊天邀请消息默认文案：发来了视频聊天邀请

<= 500 字符

push_payload

string

推送payload

可选

推送对应的 payload，必须是 JSON 格式，长度上限 2048 位字符。详情请参见推送 payload 配置。

<= 2048 字符

push_forcepush_all

boolean

是否强制推送

可选

该消息（群消息）是否强制推送（@操作），默认为 false。只有该字段为 true 时强制推送相关参数才会生效。

默认值:

false

push_forcepush_ids

array[string]

强推列表

可选

该消息（群消息）的强推（@操作）账号列表，格式为 JSONArray，如["account1","account2"]。若 push_forcepush_all 为 true，则该字段无效，该消息会强制推送（@操作）给群组中所有有效成员（除消息发送者）。最多可强推 100 个用户。

push_forcepush_content

string

强推文案

可选

强制推送的文案，仅针对强推列表 push_forcepush_ids 中的账号，长度上限 500 位字符。

<= 500 字符

antispam_config

object

安全通配置

可选

安全通相关配置项。

antispam_enabled

boolean

安全通开关

可选

该消息（除自定义消息）是否需要过审核。若已在控制台开通安全通，该字段默认为 true（过审核），若需要设置单条消息不经过审核，则设置为 fasle。若未开通安全通，该字段无效。

默认值:

true

antispam_business_id

string

安全通业务ID

可选

安全通业务 ID，可以指定当前消息过安全通某个检测策略。默认情况下云信控制后台会生成默认业务，开通安全通后，客户端不需要配置业务 ID 就能默认走该策略，若需要自定义检测策略，请联系技术支持进行配置，配置好后传入对应的安全通业务 ID，表示当前消息过安全通的指定检测策略。

antispam_extension

string

安全通增强参数

可选

透传给易盾的反垃圾增强版的检测参数，格式为 JSON，长度限制 1024 位字符（具体请参见易盾的反垃圾增强版用户可扩展参数）。反作弊相关的 email、phone、token、extension，抄送到 antispam_cheating 字段中。其他用户增值信息，抄送到 antispam_extension 字段。

antispam_custom_message_enabled

boolean

自定义内容审核开关

可选

是否对自定义消息的指定内容（antispam_custom_message）进行审核。若已在控制台开通安全通，该字段默认为 false（不过审核），若需要设置该条自定义消息经过审核，则设置为 true。若未开通安全通，该字段无效。

默认值:

false

antispam_custom_message

string

自定义安全通检测内容

可选

自定义的安全通检测内容, JSON 格式，长度限制同 text 字段。格式如下： {"type":1,"data":"custom content"} 字段说明： type: 1 为文本；2 为图片；3 为视频；(TODO 音频） data: 文本内容或图片地址。该参数只对自定义消息（message_type = 100 ）且 ntispam_custom_message_enabled = true 时才生效。

antispam_cheating

string

反作弊检测参数

可选

透传给易盾的反作弊检测参数，格式为 JSON，长度限制 1024 位字符（具体请参见易盾的反垃圾防刷版专属参数）。反作弊相关的 email、phone、token、extension，抄送到antispam_cheating 字段中。其他用户增值信息，抄送到 antispam_extension 字段。 antispam_extension 传入的值默认覆盖 extension。

p2p_option

object

单聊消息配置

可选

单聊消息功能配置项。

check_friend

boolean

是否校验好友关系

必需

该消息是否只发给好友（与消息发送者为好友关系的账号），默认为 false。若需要设置为好友关系才能发送消息，需先在云信控制台完成配置，再将该字段设置为 true。

team_option

object

高级群消息配置

可选

高级群消息功能配置项。

mark_as_read

boolean

是否需要已读功能

可选

是否需要已读功能（仅对高级群消息有效），默认为 false（不需要）。

默认值:

false

check_team_member_valid

boolean

是否需要验证群成员身份

可选

是否需要验证群成员身份，true：需要；false：不需要，默认为 true

默认值:

true

superteam_option

object

超大群消息配置

可选

超大群消息功能配置项。

ignore_chat_banned

boolean

是否忽略成员禁言

可选

发送超大群消息时，是否忽略成员禁言。默认为 false（不忽略）。若设置为 true（忽略），那么超大群内被禁言的用户也可以发送消息。

默认值:

false

check_team_member_valid

boolean

是否需要验证群成员身份

可选

是否需要验证群成员身份，true：需要；false：不需要，默认为 true

默认值:

true

robot_config

object

机器人功能配置

可选

机器人功能配置项。

robot_account_id

string

机器人账号 ID

可选

机器人账号 ID，对应控制台提前设置好的机器人账号。仅在高级群中有效，其他会话类型中该字段无效。

robot_topic

string

机器人消息话题

可选

机器人消息话题，长度上限为 128 位字符。

<= 128 字符

robot_function

string

机器人具体功能

可选

机器人具体功能，长度上限为 128 位字符。

<= 128 字符

robot_custom_content

string

机器人自定义内容

可选

机器人自定义内容，长度上限为 8192 位字符。

<= 8192 字符

ai_params

object

数字人配置项

可选

数字人功能配置项。

account

string

必需

数字人账号 ID，对应控制台提前设置好的数字人账号。

content

object

可选

发起给数字人的查询请求的内容，结构体为：
{ "msg": "xxx",//内容 "type": 0//类型，当前仅支持 0 表示文本 }

如果为空且消息为文本消息，则提取消息中的 text 字段。
如果为空且不是文本消息，则返回 107336 错误。

messages

array [object]

可选

数字人回溯的消息列表，结构体类似为：
[ { "msg": "hello", "type": 0, "role": "user" }, { "msg": "hello, I am your AI assistant", "type": 0, "role": "assistant" } ]

prompt_variables

object

可选

用于填充提示词中的变量，如果提示词中定义了变量，则该字段必填，结构体类似为：
{ "career"："chef" }

config

object

可选

模型相关的配置参数，不同模型配置类型不同。结构体类似为：
{"maxTokens":1,"temperature":1,"prompt":"我是一个${{career}}，请回答我的问题：","topP":0.5}

target_option

object

群定向消息配置项。

可选

该功能需要单独开通。

receiver_account_ids

array[string]

群定向消息成员列表，即指定接收群消息的群成员列表。

可选

当 inclusive 为 true，当前列表为可见（接收）列表。
当 inclusive 为 false，当前列表为不可见（不接收）列表。
列表中不能包含消息发送者，消息发送者默认为可见。
列表中不能包含非法账号、非群成员账号。
列表中最多可以传入 100 个用户账号。

inclusive

boolean

是否为可见列表

可选

群定向消息成员列表是否为可见列表。默认为 true，即 receiver_account_ids 为可见（接收）列表。
发送超大群消息时，不能将 inclusive 设置为 false。

默认值:

true

visible_to_new_member

boolean

新进群成员是否可见该消息

可选

新进群成员是否可见该消息。默认为 false，即新进群成员不可以查看该定向消息。若设置为 true，则新进群成员若可以查询该定向消息，可以通过云端历史相关接口查询到该消息。
当 inclusive 为 true 时，不能同时设置 visible_to_new_member 为 true。即发送定向列表为可见的定向消息时，只能由定向列表中成员接收和查看。
发送超大群消息时，不能将 visible_to_new_member 设置为 true。

默认值:

false

check_team_member_valid

boolean

是否校验定向成员合法性

必需

发送群定向消息时，是否需要验证定向成员的群成员身份。默认为 true，即需要验证群成员身份。

thread_config

object (thread_config)

可选

Thread 消息配置项。

thread_root

object

可选

Thread 根消息对象。

thread_reply

object

被回复的消息对象。

可选

示例

{
  "sender_no_sense": false,
  "receiver_no_sense": false,
  "extension": "dolore dolor sint qui voluptate",
  "message": {
    "message_type": 0,
    "sub_type": 26357002,
    "text": "Lorem laboris cillum ut exercitation",
    "attachment": {
      "name": "器年众际根开以",
      "md5": "esse Excepteur do",
      "url": "http://zpcuedkr.nc/yjy",
      "ext": "Excepteur consequat",
      "width": 83,
      "height": 56,
      "size": 18
    }
  },
  "message_config": {
    "unread_enabled": false,
    "mutil_sync_enabled": true,
    "offline_enabled": true,
    "history_enabled": false,
    "roaming_enabled": true,
    "conversation_update_enabled": true
  },
  "route_config": {
    "route_enabled": true,
    "route_environment": "Lorem anim quis"
  },
  "push_config": {
    "push_enabled": true,
    "push_nick_enabled": false,
    "push_content": "id do in velit",
    "push_payload": null,
    "push_forcepush_all": true,
    "push_forcepush_ids": [
      "22"
    ],
    "push_forcepush_content": "nostrud veniam dolore esse"
  },
  "antispam_config": {
    "antispam_enabled": false,
    "antispam_business_id": "44",
    "antispam_extension": null,
    "antispam_custom_message_enabled": true,
    "antispam_custom_message": "laborum non irure et",
    "antispam_cheating": "{\"email\":\"123@126.com\"}"
  },
  "p2p_option": {
    "check_friend": true
  },
  "team_option": {
    "mark_as_read": true,
    "ignore_chat_banned": false
  },
  "superteam_option": {
    "ignore_chat_banned": false
  },
  "robot_config": {
    "robot_account_id": null,
    "robot_topic": "http://dummyimage.com/400x400",
    "robot_function": "ex nisi pariatur qui do",
    "robot_custom_content": "quis Lorem"
  }
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://open.yunxinapi.com/im/v2/conversations/apifoxtest1|1|accid4/messages?members&reference&Type&_postman_listIndexKey=key&_postman_listAllowsMultipleValues' \
--data-raw '{
    "sender_no_sense": false,
    "receiver_no_sense": false,
    "extension": "dolore dolor sint qui voluptate",
    "message": {
        "message_type": 0,
        "sub_type": 26357002,
        "text": "Lorem laboris cillum ut exercitation",
        "attachment": {
            "name": "器年众际根开以",
            "md5": "esse Excepteur do",
            "url": "http://zpcuedkr.nc/yjy",
            "ext": "Excepteur consequat",
            "width": 83,
            "height": 56,
            "size": 18
        }
    },
    "message_config": {
        "unread_enabled": false,
        "mutil_sync_enabled": true,
        "offline_enabled": true,
        "history_enabled": false,
        "roaming_enabled": true,
        "conversation_update_enabled": true
    },
    "route_config": {
        "route_enabled": true,
        "route_environment": "Lorem anim quis"
    },
    "push_config": {
        "push_enabled": true,
        "push_nick_enabled": false,
        "push_content": "id do in velit",
        "push_payload": null,
        "push_forcepush_all": true,
        "push_forcepush_ids": [
            "22"
        ],
        "push_forcepush_content": "nostrud veniam dolore esse"
    },
    "antispam_config": {
        "antispam_enabled": false,
        "antispam_business_id": "44",
        "antispam_extension": null,
        "antispam_custom_message_enabled": true,
        "antispam_custom_message": "laborum non irure et",
        "antispam_cheating": "{\"email\":\"123@126.com\"}"
    },
    "p2p_option": {
        "check_friend": true
    },
    "team_option": {
        "mark_as_read": true,
        "ignore_chat_banned": false
    },
    "superteam_option": {
        "ignore_chat_banned": false
    },
    "robot_config": {
        "robot_account_id": null,
        "robot_topic": "http://dummyimage.com/400x400",
        "robot_function": "ex nisi pariatur qui do",
        "robot_custom_content": "quis Lorem"
    }
}'

返回响应

🟢200成功

application/json

Body

code

integer

必需

状态码，200 表示请求成功。

msg

string

必需

提示信息。请求失败时返回错误信息，请求成功时返回 "success"。

data

object

必需

返回的 JSON 数据对象，请求失败则返回空对象。

message_server_id

integer

可选

服务端消息 ID。

message_client_id

string

可选

客户端消息id（不传则自动生成）

message_type

integer

消息类型。

必需

text

string

可选

文本/提示消息内容或多媒体消息的描述文本（该描述信息可用于云端历史消息关键词检索）。

attachment

object

可选

多媒体消息的属性或自定义消息内容。

sub_type

integer

可选

自定义消息子类型。

sender_id

string

可选

消息发送方帐号 ID。

conversation_type

integer

消息会话类型。

可选

receiver_id

string

可选

消息接收者账号 ID。

create_time

integer <long>

消息发送时间戳。

可选

thread_config

object

可选

示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "text": "Lorem laboris cillum ut exercitation",
    "attachment": {
      "ext": "Excepteur consequat",
      "size": 18,
      "name": "器年众际根开以",
      "width": 83,
      "url": "http://zpcuedkr.nc/yjy",
      "md5": "esse Excepteur do",
      "height": 56
    },
    "message_server_id": 9899821270208,
    "sender_id": "apifoxtest1",
    "conversation_type": 1,
    "receiver_id": "accid4",
    "create_time": 1707035841692,
    "message_type": 0,
    "sub_type": 26357002
  }
}

🟢200请求参数错误

🟢200服务器错误

修改于 2025-03-17 03:27:49

分页查询黑名单列表

批量发送单聊消息