#########
消息格式
#########

本节定义了在 :doc:`api_msg` 一节中，收/发消息的消息接口所涉及的消息格式。

消息类型
*********

全媒体系统支持的消息类型有：

* 系统命令消息
* 文本消息
* 图片消息
* 声音消息
* 文件消息

消息类型在 ``MsgType`` 属性中指定:

=========== ========================
类型标识符  说明
=========== ========================
event       事件通知消息
text        文本消息
image       图片消息
voice       声音消息
file        文件消息
=========== ========================

消息内容
*********

消息的内容在 ``Content`` 属性中指定。

.. attention:: 坐席的IM界面完全按照本文定义的消息格式，对坐席展示客户输入的消息，以及生成坐席输入的消息。请APP开发者不要自行扩展消息格式。

以下定义不同消息类型下， ``Content`` 属性的不同格式：

事件通知消息
============
该类型的消息用于APP客户端向全媒体系统发送特殊的事件或者命令

这些请求不会被当作聊天文字，而是被当作命令。如 **请求人工服务** ::

    {
        "MsgType": "event.CLICK.RG",
    }

当 ``MsgType`` 属性值为 ``event.CLICK.RG`` 时，全媒体系统会进行人工服务的排队。

文本消息
========

文本消息应被原样的展现给坐席与客户，除了 `HTML标签`_ 与 `表情转义符`_ 。

如::

    {
        "MsgType": "text",
        "Content": "[微笑] 亲，你好！"
    }

APP 开发者请注意HTML标签、特殊字符以及JSON转义字符的问题。

HTML标签
--------
``<a>`` 标签，可用于在文本中插入超链接

如：

.. code-block:: html

    你好，<a href="http://baidu.com">戳这里访问百度</a> ，呵呵

此时，应向用户呈现的效果是：

----

.. raw:: html

    你好，<a href="http://baidu.com">戳这里访问百度</a> ，呵呵

----

表情转义符
----------

方括号内具有表情关键字的文本，被视作表情转义符。

例如::

    [微笑]

被视作微笑表情转义符，此时应向客户端显示：

----

.. raw:: html
    
    <img src="_static/qqemoji/0.png"/>

----

同理，以下文本::

    我[晕]，这下[糗大了]！

应该被显示为：

----

.. raw:: html
    
    我<img src="_static/qqemoji/34.png"/>，这下<img src="_static/qqemoji/43.png"/>！

----

APP开发者可在此下载我们采用的默认表情素材：`下载地址 <_static/qqemoji.zip>`_ ）

该压缩包中，每个表情图片都是一个png文件，文件名是数字。

表情与文件名的对应关系如下表所示：

.. literalinclude:: _static/qqemoji_map.txt
    :language: js

APP开发者也可以选择其他素材作为表情，但是必须遵守转义规则，且表情转义符必须按照上表的定义。

图片消息
==========

消息内容是图片文件的超链接地址。

如::

    {
        "MsgType": "image",
        "Content": "xxxx/xxxx.jpg"
    }

消息发送程序必须保证该地址可被访问。

文件大小: <120KB

文件格式：JPG

声音消息
========

消息内容是声音文件的超链接地址。

如::

    {
        "MsgType": "voice",
        "Content": "xxxx/xxxx.amr"
    }

消息发送程序必须保证该地址可被访问。

文件大小: <2M

播放长度: <60s

文件格式：AMR, MP3

文件消息
========

消息内容是文件的超链接地址。

如::

    {
        "MsgType": "voice",
        "Content": "xxxx/xxxx.zip"
    }

消息发送程序必须保证该地址可被访问。

消息附件
*********

当消息类型是图片、文件、声音时，发送一方需要将附件 **预先** 通过 **FTP 上传** 到全媒体系统的文件服务器，并在消息中填写文件路径，为了避免名称冲突，应使用UUID作为文件名。

为了方便备份和文件见管理，请 IM 的接入服务使用如下的文件格式::

    <appid>/<YYYY>/<MM>/<DD>/<uuid-file-name>.<ext>

例如，APPID为1003的接入服务要发送一个JPEG图片，它应该将该图片上传到FTP服务器，上传后的文件名形如 ``1001/2014/12/25/01b626e8-a10f-11e4-97d6-a424f507d784.jpg`` ，这个文件路径名同时也是消息体中 ``Content`` 字段填写的内容。坐席将通过HTTP协议从文件服务器下载该路径所对应的文件。

同理，在接收附件时，APP通过HTTP协议从文件服务器下载 ``Content`` 对应的附件。

.. attention:: APP服务器通过 **FTP** 协议向文件服务器上传文件。为了便于客户端/浏览器访问附件，文件服务器同时也提供了 **HTTP** 访问功能。

.. tip:: 文件服务器的 FTP 与 HTTP 访问地址可能存在前缀， APP 应可设置这些地址的前缀，以及 FTP 的地址、端口、用户、密码。

.. warning:: 文件服务器上的附件必须保留其真实的后缀名。