批量发送单聊消息

POST

/im/v2/conversations/messages

请求参数

Header 参数

AppKey

string

必需

默认值:

X-custom-traceid

string

可选

默认值:

{% mock 'uuid' %}

Nonce

string

必需

默认值:

CurTime

string

必需

默认值:

CheckSum

string

必需

默认值:

Body 参数application/json

receiver_no_sense

boolean

接收方无感知

必需

接收者是否无感知。若为true，则无感知，若无感知，则消息接收者无该消息的多端、漫游、历史记录等。

need_message_detail

boolean

是否需要返回消息内容体

可选

是否需要返回消息内容体

sender_no_sense

boolean

发送方无感知

可选

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

默认值:

false

sender_id

string

发送者

必需

发送者的云信账号 ID。

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 位字符。对于非文本消息/提示消息，该字段必填，每种消息的属性参数见：消息格式示例。

route_config

object

抄送配置

可选

抄送相关配置项。

route_enabled

boolean

可选

默认值:

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 字符

p2p_option

object

单聊消息配置

可选

单聊消息功能配置项。

check_friend

boolean

是否校验好友关系

必需

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

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_cheating

string

反作弊检测参数

可选

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

receiver_ids

array[string]

接收者

必需

接收者账号 ID 列表，JSON 格式。最多传入 500 个云信账号。

示例

{
    "sender_no_sense": false,
    "extension": "officia labore ex sit ut",
    "message": {
        "message_type": 0,
        "sub_type": 30164486,
        "text": "laborum irure",
        "attachment": {
            "name": "型用四这却认",
            "md5": "amet sit Excepteur officia",
            "url": "http://xkjotf.cq/ckp",
            "ext": "in qui",
            "width": 10,
            "height": 95,
            "size": 89
        }
    },
    "route_config": {
        "route_enabled": false,
        "route_environment": "incididunt eiusmod esse magna"
    },
    "push_config": {
        "push_enabled": true,
        "push_nick_enabled": false,
        "push_content": "proident reprehenderit",
        "push_payload":null,
        "push_forcepush_all": true,
        "push_forcepush_ids": [
            "30"
        ],
        "push_forcepush_content": "irure"
    },
    "antispam_config": {
        "antispam_enabled": false,
        "antispam_business_id": "31",
        "antispam_extension": null,
        "antispam_cheating":null
    },
    "p2p_option": {
        "check_friend": true
    },
    "sender_id": "apifoxtest1",
    "receiver_ids": [
        "apifoxtest2"
    ]
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://open.yunxinapi.com/im/v2/conversations/messages' \
--header 'AppKey;' \
--header 'X-custom-traceid: {% mock '\''uuid'\'' %}' \
--header 'Nonce;' \
--header 'CurTime;' \
--header 'CheckSum;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender_no_sense": false,
    "extension": "officia labore ex sit ut",
    "message": {
        "message_type": 0,
        "sub_type": 30164486,
        "text": "laborum irure",
        "attachment": {
            "name": "型用四这却认",
            "md5": "amet sit Excepteur officia",
            "url": "http://xkjotf.cq/ckp",
            "ext": "in qui",
            "width": 10,
            "height": 95,
            "size": 89
        }
    },
    "route_config": {
        "route_enabled": false,
        "route_environment": "incididunt eiusmod esse magna"
    },
    "push_config": {
        "push_enabled": true,
        "push_nick_enabled": false,
        "push_content": "proident reprehenderit",
        "push_payload":null,
        "push_forcepush_all": true,
        "push_forcepush_ids": [
            "30"
        ],
        "push_forcepush_content": "irure"
    },
    "antispam_config": {
        "antispam_enabled": false,
        "antispam_business_id": "31",
        "antispam_extension": null,
        "antispam_cheating":null
    },
    "p2p_option": {
        "check_friend": true
    },
    "sender_id": "apifoxtest1",
    "receiver_ids": [
        "apifoxtest2"
    ]
}'

返回响应

🟢200成功

application/json

Body

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

code

integer

必需

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

msg

string

必需

data

object

必需

示例

{
    "code": 200,
    "msg": "success",
    "data": {
        "success_list": [
            {
                "text": "laborum irure",
                "attachment": {
                    "ext": "in qui",
                    "size": 89,
                    "name": "型用四这却认",
                    "width": 10,
                    "url": "http://xkjotf.cq/ckp",
                    "md5": "amet sit Excepteur officia",
                    "height": 95
                },
                "message_server_id": 9897543190303,
                "sender_id": "apifoxtest1",
                "conversation_type": 1,
                "receiver_id": "apifoxtest2",
                "create_time": 1707017423142,
                "message_type": 0,
                "sub_type": 30164486
            }
        ]
    }
}

🟢200成功

🟢200请求参数错误

🟢200服务器错误

发送消息

撤回/删除消息