短消息接口

首页 > 资料库 > UCenter相关 > 接口开发标签：阅读：

短消息接口

此部分接口负责用户间的短消息传输，可以跨应用间互相发送短消息。“短消息中心”的界面接口可以让应用只需一个函数接口即拥有短消息功能，对于高级用户 UCenter 也提供了丰富的收发接口函数供用户自己开发短消息系统。

进入短消息中心

uc_pm_location(integer uid , bool newpm)

函数参数

参数	含义
integer uid	用户 ID
bool newpm	是否直接查看未读短消息 1:是 0:(默认值) 否

本接口函数运行后会发送一个 header 的 location 请求，使当前页面跳转到短消息中心。所以请不要在这个函数运行前后有任何的输出性的代码。如果 newpm 为 1 则进入短消息中心后，会默认打开新件箱。

进入短消息中心示例 (PHP)

<?php
	uc_pm_location($uid);
?>

检查新的短消息

bool/array uc_pm_checknew(integer uid [, bool more])

函数参数

参数	含义
integer uid	用户 ID
bool more	是否显示更多信息 2:返回短消息数、最后消息时间, 最后消息内容 1:返回短消息数、最后消息时间 0:(默认值) 只返回短消息数

返回值 (当 more = 0 时)

值	含义
integer	未读消息数

返回值 (当 more = 1 时)

值		含义
array	integer ['newpm']	未读消息数
array	integer ['newprivatepm']	私人消息数

返回值 (当 more = 2 时)

值		含义
array	integer ['newpm']	未读消息数
	integer ['newprivatepm']	私人消息数
	integer ['newchatpm']	群聊消息数

返回值 (当 more = 3 时)

值		含义
array	integer [newpm]	未读消息数
	integer ['newprivatepm']	私人消息数
	integer ['newchatpm']	群聊消息数
	integer ['lastdate']	最后消息时间
	integer ['lastmsgfromid']	最后消息发件人 ID
	string ['lastmsgfrom']	最后消息发件人用户名
	string ['lastmsg']	最后消息内容

本接口函数会检查指定用户是否有新的短消息。

检查新短消息示例 (PHP)

if(uc_pm_checknew($uid)) {
	echo "您有新短消息";
}

发送短消息

integer uc_pm_send(integer fromuid , string msgto , string subject , string message [, bool instantly , integer replypmid , bool isusername , integer type])

函数参数

参数	含义
integer fromuid	发件人用户 ID
string msgto	收件人用户名 / 用户 ID，多个用逗号分割
string subject	消息标题
string message	消息内容
bool instantly	是否直接发送 1:(默认值) 直接发送消息 0:进入发送短消息的界面
integer replypid	回复的消息 ID 大于 0:回复指定的短消息 0:(默认值) 发送新的短消息
bool isusername	msgto 参数是否为用户名 1:msgto 参数为用户名 0:(默认值) msgto 参数为用户 ID
integer type	消息类别 1:群聊消息 0:(默认值)私人消息

返回值

值	含义
integer	大于 0:发送成功的最后一条消息 ID 0:发送失败 -1:超过两人会话的最大上限 -2:超过两次发送短消息时间间隔 -3:不能给非好友批量发送短消息(已废弃) -4:目前还不能使用发送短消息功能（注册多少日后才可以使用发短消息限制） -5:超过群聊会话的最大上限 -6:在忽略列表中 -7:超过群聊人数上限 -8:不能给自己发短消息 -9:收件人为空 -10:发起群聊人数小于两人

值

含义

integer

大于 0:发送成功的最后一条消息 ID
0:发送失败
-1:超过两人会话的最大上限
-2:超过两次发送短消息时间间隔
-3:不能给非好友批量发送短消息(已废弃)
-4:目前还不能使用发送短消息功能（注册多少日后才可以使用发短消息限制）
-5:超过群聊会话的最大上限
-6:在忽略列表中
-7:超过群聊人数上限
-8:不能给自己发短消息
-9:收件人为空
-10:发起群聊人数小于两人

本接口函数用于发送短消息。当 instantly 为 1 时，短消息会直接发送出去，否则本函数会发送一个 header 的 location 请求，使当前页面跳转到短消息中心的发送短消息页面。因此，当 instantly 为 0 时请不要在这个函数运行前后有任何的输出性的代码。type 为 1 时为发送群聊消息。msgto 默认为用户 ID，如果要让用户名作为参数，可让 isusername 为 1。replypid 为 0 表示发送的短消息为短消息话题的发起者，如果 replypid 为指定的消息 ID 则表示发送的短消息为回复指定短消息话题的回复信息。如果 instantly 为 1，那么发送成功后函数返回发送成功的最后一条消息 ID，返回 0 表示发送失败。

发送短消息示例 (PHP)

if(uc_pm_send($uid, $_POST['msgto'], $_POST['subject'], $_POST['message'])) {
	echo "短消息发送成功";
}

删除短消息

integer uc_pm_delete(integer uid , string folder , array pmids)

函数参数

参数	含义
integer uid	用户 ID
string folder	短消息所在的文件夹 inbox:收件箱 outbox:发件箱
array pmids	消息 ID 数组

返回值

值	含义
integer	1: 删除成功，0: 删除失败

本接口函数将删除指定文件夹中的指定消息 ID 的短消息。pmids 参数是一个自由 Key 数组类型，如“ array(1, 2, 3, 4, 5 ...) ”，数组的每一个值均为消息 ID。删除的每一条短消息 UCenter 会进行对方删除状态的检测，如果短消息对方也是删除状态，那么当前消息将在数据库中删除，否则只记录一个删除标记。

删除短消息示例 (PHP)

$if(!empty($_POST['delete']) && is_array($_POST['delete'])) {
	uc_pm_delete($uid, 'inbox',  $_POST['delete']);
}

integer uc_pm_deleteuser(integer uid , array touids)

函数参数

参数	含义
integer uid	用户 ID
array touids	对方用户 ID 数组

返回值

值	含义
integer	1: 删除成功, 0: 删除失败

本接口函数将删除和 uid 对话的 touids 中的所有短消息。

uc_pm_deletechat(integer uid , array plids [, bool type])

函数参数

参数	含义
integer uid	用户 ID
array plids	要删除的消息会话 ID 数组
bool type	类别 0:(默认值) 退出群聊 1:删除群聊

本接口函数用于群聊短消息的退出和删除。plids 参数是一个自由 Key 数组类型，如“ array(1, 2, 3, 4, 5 ...) ”，数组的每一个值均为 ID。

标记短消息已读/未读状态

uc_pm_readstatus(integer uid , array uids [, array plids, bool status])

函数参数

参数	含义
integer uid	用户 ID
array uids	要标记的对方用户 ID 数组
array pmids	要标记的会话 ID 数组，默认值空数组
bool status	要标记的状态 0:(默认值) 标记为已读 1:标记为未读

本接口函数用于标记短消息的已读/未读状态。uids 和 plids 参数是一个自由 Key 数组类型，如“ array(1, 2, 3, 4, 5 ...) ”，数组的每一个值均为 ID。

标记短消息状态示例 (PHP)

uc_pm_readstatus($uid, $uids);
echo "短消息已标记为已读";

获取短消息列表

array uc_pm_list(integer uid [, integer page , integer pagesize , string folder , string filter, integer msglen])

函数参数

参数	含义
integer uid	用户 ID
integer page	当前页编号，默认值 1
integer pagesize	每页最大条目数，默认值 10
string folder	短消息所在的文件夹 newbox:新件箱 inbox:(默认值) 收件箱 outbox:发件箱
string filter	过滤方式 newpm:(默认值) 未读消息，folder 为 inbox 和 outbox 时使用
integer msglen	截取短消息内容文字的长度，0 为不截取，默认值 0

返回值

值		含义
array	integer ['count']	消息总数
array	array ['data']	短消息列表数据，其中单条消息数组结构请参看附表。

本接口函数用于获取指定文件夹的短消息列表。函数已内置分页，直接通过 page 和 pagesize 即可实现翻页。

忽略未读消息提示

uc_pm_ignore(integer uid)

函数参数

参数	含义
integer uid	用户 ID

本接口函数用于直接忽略未读短消息的提示状态。

获取短消息内容

array uc_pm_view(integer uid , integer pmid [, integer touid , integer daterange , integer page , integer pagesize , integer type , integer isplid])

函数参数

参数	含义
integer uid	用户 ID
integer pmid	消息 ID
integer touid	消息对方用户 ID
integer daterange	日期范围 1:(默认值) 今天 2:昨天 3:前天 4:上周 5:更早
integer page	当前页码
integer pagesize	每页最大条数
integer type	消息类型 1: 私人消息, 2: 群聊消息
integer isplid	touid参数是会话id还是用户id

返回值

值	含义
array	短消息内容数据，其中单条消息数组结构请参看附表

本接口函数用于返回指定用户的指定消息 ID 的消息，返回的数据中包含针对这个消息的回复。如果指定 touid 参数，那么短消息将列出所有 uid 和 touid 之间的短消息，daterange 可以指定返回消息的日期范围, page 和 pagesize 可以指定返回消息的页码和页面大小。

查找会话消息数量

integer uc_pm_view_num(integer uid , integer touid , bool isplid)

函数参数

参数	含义
integer uid	用户 ID
integer touid	查找的会话 ID 或者用户 ID
bool isplid	touid参数是会话 ID 还是用户 ID

返回值

值	含义
integer	指定会话的消息数量

查找会话消息数量示例 (PHP)

uc_pm_view_num($uid, $plid, 1);

获取单条短消息内容

integer uc_pm_viewnode(integer uid , integer type , integer pmid)

函数参数

参数	含义
integer uid	用户 ID
integer type	消息的类型 0: 获取指定单条消息
integer pmid	消息 ID

返回值

值	含义
array	短消息内容数据，其中单条消息数组结构请参看附表

查找群聊成员列表

integer uc_pm_chatpmmemberlist(integer uid , integer plid)

函数参数

参数	含义
integer uid	用户 ID
integer plid	群聊会话 ID

返回值

值	含义
array	返回群聊的成员列表附表

踢出群聊成员

integer uc_pm_kickchatpm(integer plid , integer uid , integer touid)

函数参数

参数	含义
integer plid	会话 ID
integer uid	用户 ID
integer touid	踢出的用户 ID

返回值

值	含义
integer	1: 踢出成功, 2: 踢出失败

添加群聊成员

integer uc_pm_appendchatpm(integer plid , integer uid , integer touid)

函数参数

参数	含义
integer plid	会话 ID
integer uid	用户 ID
integer touid	添加的用户 ID

返回值

值	含义
integer	1: 添加成功, 2: 添加失败

获取黑名单

string uc_pm_blackls_get(integer uid)

函数参数

参数	含义
integer uid	用户 ID

返回值

值	含义
string	黑名单内容数据

本接口函数返回用户的黑名单设置的内容。

获取黑名单示例 (PHP)

$blackls = uc_pm_blackls_get($uid);
echo '<form method="post"><textarea name="blackls">'.htmlspecialchars($blackls).'</textarea>';
echo '<input type="submit" value="保存" /></form>';

更新黑名单

bool uc_pm_blackls_set(integer uid , string blackls)

函数参数

参数	含义
integer uid	用户 ID
string blackls	黑名单内容

返回值

值	含义
bool	1:更新成功 0:更新失败

本接口函数用于更新用户的黑名单列表数据。设置黑名单后，黑名单中的人员将无法发送短消息给 uid 指定的用户。黑名单中被忽略的人员用用户名表示，多个忽略人员名单时用逗号 "," 隔开(如:张三,李四,王五)，如需禁止所有用户发来的短消息，请用 "{ALL}" 表示。

更新黑名单示例 (PHP)

if(uc_pm_blackls_set($uid, $_POST['blackls'])) {
	echo '黑名单更新成功';
}

添加黑名单项目

bool uc_pm_blackls_add(integer uid , array username)

函数参数

参数	含义
integer uid	用户 ID
array username	用户名数组

返回值

值	含义
bool	1:添加成功 0:添加失败

本接口函数用于添加用户的黑名单项目。如需添加屏蔽所有用户的设置，请让 username 数组中包含 "{ALL}"

添加黑名单项目示例 (PHP)

uc_pm_blackls_add(1, array('username1', ''username2'));

删除黑名单项目

uc_pm_blackls_delete(integer uid , array username)

函数参数

参数	含义
integer uid	用户 ID
array username	用户名数组

本接口函数用于删除用户的黑名单项目。如需删除屏蔽所有用户的设置，请让 username 数组中包含 "{ALL}"

添加黑名单项目示例 (PHP)

uc_pm_blackls_delete(1, array('username1', ''username2'));

附表：消息列表单条数组结构

integer ['plid']	会话 ID
integer ['uid']	当前用户 ID
bool ['isnew']	是否未读标记
integer ['pmnum']	该会话相对于当前用户的消息数量
integer ['lastupdate']	当前用户的最后更新时间
integer ['lastdateline']	会话最后更新时间
integer ['authorid']	会话发起者 ID
integer ['pmtype']	会话类别 1: 私人消息, 2: 群聊消息
string ['subject']	标题
integer ['members']	会话参与人数
integer ['touid']	pmtype参数为1时,该返回值表示对方用户 ID
string ['tousername']	pmtype参数为1时,该返回值表示对方用户名
integer ['founddateline']	会话发起时间
integer ['lastauthorid']	会话最后一条的发送人 ID
string ['lastauthor']	会话最后一条的发送人用户名
string ['lastsummary']	会话最后一条的发送的内容截取
integer ['pmid'][兼容]	消息 ID
integer ['msgfromid'][兼容]	发件人用户 ID
string ['msgfrom'][兼容]	发件人用户名
integer ['msgtoid'][兼容]	收件人用户 ID
integer ['new'][兼容]	1:未读短消息 0:已读短消息
string ['message'][兼容]	内容
integer ['dateline'][兼容]	发送时间的时间戳
integer ['daterange'][兼容]	1:今天 2:昨天 3:前天 4:上周 5:更早

附表：消息详细内容单条数组结构

integer ['pmid']	消息 ID
integer ['plid']	所属会话 ID
integer ['authorid']	消息发起者 ID
string ['author']	消息发起者用户名
integer ['pmtype']	会话类别 1: 私人消息, 2: 群聊消息
string ['subject']	标题
integer ['members']	会话参与人数
integer ['dateline']	消息发起时间
string ['message']	消息内容
integer ['founderuid']	发起会话的用户 ID
integer ['founddateline']	会话发起时间
integer ['touid']	pmtype参数为1时,该返回值表示对方用户 ID
integer ['msgfromid'][兼容]	发件人用户 ID
string ['msgfrom'][兼容]	发件人用户名
integer ['msgtoid'][兼容]	收件人用户 ID

附表：群聊成员列表单个数组结构

integer ['author']	群聊发起者 ID
array ['member']	所有成员用户 ID 列表如: “ array(1, 2, 3, ...) ”