Well-known keys for the first Message_Part of a message, which contains metadata about the message as a whole, along with the corresponding value types. Some keys make sense for both incoming and outgoing messages, while others are only meaningful for one or the other.

message-token (s)

An opaque, globally-unique identifier for the entire message. This MAY be treated as if it were a MIME Message-ID, e.g. for the mid: and cid: URI schemes. If omitted, there is no suitable token; the protocol-token key SHOULD be provided if the protocol identifies messages in some less unique way.

protocol-token (s - Protocol_Message_Token)

An opaque token for the entire message, with whatever uniqueness guarantee is provided by the underlying protocol. As described for the Protocol_Message_Token type, this token is not guaranteed to be unique between contacts, or even within the scope of a Channel.

Rationale:

In practice, in most protocols there is no token with the uniqueness guarantees demanded for message-token; the definition of message-token was inappropriate, but must now be preserved for the benefit of clients that rely on it, at least until Telepathy breaks backwards compatibility.

The message-token and protocol-token SHOULD NOT both be present; clients requiring an identifier with the semantics of the protocol-token SHOULD look for the message-token first, falling back to the protocol-token.

Rationale:

This is for compatibility with CMs older than the protocol-token key.

message-sent (x - Unix_Timestamp64)

The time the message was sent (if unavailable, the time it arrived at a central server MAY be used). Omitted if no reasonable approximation is available; SHOULD always be present on outgoing messages.

message-received (x - Unix_Timestamp64)

The time the message was received locally. SHOULD always be present.

message-sender (u - Contact_Handle)

The contact who sent the message. If 0 or omitted, the contact who sent the message could not be determined.

sender-nickname (s)

The nickname chosen by the sender of the message, which can be different for each message in a conversation.

message-type (u - Channel_Text_Message_Type)

The type of message; if omitted, Channel_Text_Message_Type_Normal MUST be assumed. MAY be omitted for normal chat messages.

supersedes (s – Protocol_Message_Token)

If present, this message supersedes a previous message, identified by its protocol-token or message-token header. The user interface MAY, for example, choose to replace the superseded message with this message, or grey out the superseded message.

Rationale:

Skype, for example, allows the user to amend messages they have already sent (to correct typos, etc.).

pending-message-id (u - Message_ID)

The incoming message ID. This MUST NOT be present on outgoing messages. Clients SHOULD NOT store this key - it is only valid for as long as the message remains unacknowledged.

interface (s - DBus_Interface)

This message is specific to the given interface, which is neither Text nor Messages. It SHOULD be ignored if that interface is not supported. (Note that an 'interface' key can also appear on the second and subsequent parts, where it indicates that that part (only) should be ignored if unsupported.)

scrollback (b)

If present and true, the incoming message was part of a replay of message history (this matches the Scrollback flag in Channel_Text_Message_Flags). This flag does not make sense on outgoing messages and SHOULD NOT appear there.

rescued (b)

If present and true, the incoming message has been seen in a previous channel during the lifetime of the Connection, but had not been acknowledged when that channel closed, causing an identical channel (in which the message now appears) to open. This matches the Rescued flag in Channel_Text_Message_Flags; it does not make sense on outgoing messages, and SHOULD NOT appear there.

Well-known keys for the second and subsequent Message_Parts of a message, which contain the message content, along with the corresponding value types.

identifier (s — Protocol_Content_Identifier)

An opaque identifier for this part. Parts of a message MAY reference other parts by treating this identifier as if it were a MIME Content-ID and using the cid: URI scheme.

alternative (s)

If present, this part of the message is an alternative for all other parts with the same value for "alternative". Clients SHOULD only display one of them (this is expected to be used for XHTML messages in a future version of this specification).

If omitted, this part is not an alternative for any other part.

Parts of a message MAY reference the group of alternatives as a whole (i.e. a reference to whichever of them is chosen) by treating this identifier as if it were the MIME Content-ID of a multipart/alternative part, and using the cid: URI scheme.

content-type (s)

The MIME type of this part. See the documentation for MessageReceived and MessageSent for notes on the special status of "text/plain" parts.

Connection managers MUST NOT signal parts without a 'content-type' key; if a protocol provides no way to determine the MIME type, the connection manager is responsible for guessing it, but MAY fall back to "text/plain" for text and "application/octet-stream" for non-text.

Clients MUST ignore parts without a 'content-type' key, which are reserved for future expansion.

lang (s)

The natural language of this part, identified by a RFC 3066 language tag.

Rationale:

XMPP allows alternative-selection by language as well as by content-type.

size (u)

The size in bytes (if needs-retrieval is true, this MAY be an estimated or approximate size). SHOULD be omitted if 'content' is provided.

Rationale:

There's no point in providing the size if you're already providing all the content.

thumbnail (b)

This part is a thumbnail. To represent an image together with its thumbnail in a single message, there should be one part for the full image followed by a part for the thumbnail (following the “more complete versions first” requirement), with the same 'alternative' value. For example:

[ ... ,
  { 'alternative': 'catphoto',
    'content-type': 'image/jpeg',
    'size': 150000,
    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
  },
  { 'alternative': 'catphoto',
    'content-type': 'image/jpeg'
    'size': 1024,
    'thumbnail': True,
    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
  },
  ...
]

needs-retrieval (b)

If false or omitted, the connection manager already holds this part in memory. If present and true, this part will be retrieved on demand (like MIME's message/external-body), so clients should expect retrieval to take time; if this specification is later extended to provide a streaming version of GetPendingMessageContent, clients should use it for parts with this flag.

truncated (b)

The content available via the 'content' key or GetPendingMessageContent has been truncated by the server or connection manager (equivalent to Channel_Text_Message_Flag_Truncated in the Text interface).

content (s or ay)

The part's content, if it is available and sufficiently small to include here (implies that 'needs-retrieval' is false or omitted). Otherwise, omitted. If the part is human-readable text or HTML, the value for this key MUST be a UTF-8 string (D-Bus signature 's'). If the part is not text, the value MUST be a byte-array (D-Bus signature 'ay'). If the part is a text-based format that is not the main body of the message (e.g. an iCalendar or an attached XML document), the value SHOULD be a UTF-8 string, transcoding from another charset to UTF-8 if necessary, but MAY be a byte-array (of unspecified character set) if transcoding fails or the source charset is not known.

interface (s - DBus_Interface)

This part is specific to the given interface, which is neither Text nor Messages. It SHOULD be ignored if that interface is not supported. (Note that an 'interface' key can also appear on the first part, where it indicates that the entire message should be ignored if unsupported.)

Well-known keys for the first Message_Part of a delivery report, along with the corresponding value types. Some of these are special-cases of headers defined by Message_Header_Key.

message-sender (u - Contact_Handle, as defined by Message_Header_Key)

MUST be the intended recipient of the original message, if available (zero or omitted if the intended recipient is unavailable or is not a contact, e.g. a chatroom), even if the delivery report actually came from an intermediate server.

message-type (u - Channel_Text_Message_Type, as defined by Message_Header_Key)

MUST be Channel_Text_Message_Type_Delivery_Report.

delivery-status (u - Delivery_Status)

The status of the message. All delivery reports MUST contain this key in the first Message_Part.

delivery-token (s - Protocol_Message_Token)

An identifier for the message to which this delivery report refers. MUST NOT be an empty string. Omitted if not available.

Clients may match this against the token produced by the SendMessage method and MessageSent signal. A status report with no token could match any sent message, and a sent message with an empty token could match any status report. If multiple sent messages match, clients SHOULD use some reasonable heuristic.

Rationale:

In an ideal world, we could unambiguously match reports against messages; however, deployed protocols are not ideal, and not all reports and messages can be matched.

delivery-error (u - Channel_Text_Send_Error)

The reason for the failure. MUST be omitted if this was a successful delivery; SHOULD be omitted if it would be Channel_Text_Send_Error_Unknown.

delivery-dbus-error (s - DBus_Error_Name)

The reason for the failure, specified as a (possibly implementation-specific) D-Bus error. MUST be omitted if this was a successful delivery. If set, the 'delivery-error' key SHOULD be set to the closest available value.

delivery-error-message (s)

Debugging information on why the message could not be delivered. MUST be omitted if this was a successful delivery; MAY always be omitted.

delivery-echo (aa{sv} - Message_Part[])

The message content, as defined by the Messages interface. Omitted if no content is available. Content MAY have been truncated, message parts MAY have been removed, and message parts MAY have had their content removed (i.e. the message part metadata is present, but the 'content' key is not).

Rationale:

Some protocols, like XMPP, echo the failing message back to the sender. This is sometimes the only way to match it against the sent message, so we include it here.

Unlike in the Messages interface, content not visible in the value for this key cannot be retrieved by another means, so the connection manager SHOULD be more aggressive about including (possibly truncated) message content in the 'content' key.

Rationale:

The Messages interface needs to allow all content to be retrieved, but in this interface, the content we provide is merely a hint; so some is better than none, and it doesn't seem worth providing an API as complex as Messages' GetPendingMessageContent for the echoed message.

An opaque token used to identify messages in the underlying. protocol. As a special case, the empty string indicates that there is no particular identification for a message.

CM implementations SHOULD use an identifier expected to be unique, such as a UUID, if possible.

Some protocols can only track a limited number of messages in a small message-ID space (SMS messages are identified by a single byte), and some implementations send non-unique identifiers (some XMPP clients use very simple message IDs, such as an incrementing integer that resets to 1 at the beginning of each connection). As a result, clients MUST NOT assume that protocol tokens will not be re-used.

In particular, clients SHOULD use a heuristic to assign delivery reports to messages, such as matching on message content or timestamp (if available), or assuming that the delivery report refers to the most recent message with that ID.

A protocol-specific identifier for a blob of content, as used for the identifier key in a Message_Part. The same identifier MAY be re-used if the same content, byte-for-byte, appears as a part of several messages.

The status of a message as indicated by a delivery report.

If this enum is extended in future specifications, this should only be to add new, non-overlapping conditions (i.e. all failures should still be signalled as either Temporarily_Failed or Permanently_Failed). If additional detail is required (e.g. distinguishing between the various types of permanent failure) this will be done using additional Delivery_Report_Header_Keys.

Flags indicating the level of support for message parts on this channel. They are designed such that setting more flags always implies that the channel has more capabilities.

If no flags are set, this indicates that messages may contain a single message part whose content-type is any of the types from SupportedContentTypes, possibly with some alternatives.

There is no flag indicating support for alternatives. This is because the SendMessage implementation can always accept messages containing alternatives, even if the underlying protocol does not, by deleting all alternatives except the first (most preferred) that is supported.

See SupportedContentTypes for some examples.

Part of a message's content. In practice, this mapping never appears in isolation: incoming messages are represented by a list of Message_Part mappings in the MessageReceived signal, and outgoing messages are passed to SendMessage as a list of these mappings.

The first part of the message contains "headers", which refer to the entire message. The second and subsequent parts contain the message's content, including plain text, formatted text and/or attached files. Well-known keys for the header and body parts are defined by the Message_Header_Key and Message_Body_Key types, respectively. It is an error for a connection manager to put keys referring to the message as a whole in the second or subsequent Message_Part, or keys intended for body parts in the first Message_Part; clients MUST recover from this error by ignoring these mis-placed keys.

In any group of parts with the same non-empty value for the alternative key (which represent alternative versions of the same content), more faithful versions of the intended message MUST come before less faithful versions (note that this order is the opposite of MIME multipart/alternative parts). Clients SHOULD display the first alternative that they understand.

Clients SHOULD present all parts that are not redundant alternatives in the order they appear in this array, possibly excluding parts that are referenced by another displayed part. It is implementation-specific how the parts are presented to the user.

Example messages

A rich-text message, with an embedded image, might be represented as:

[
  {
    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
    'message-sender': 42,
    'message-sent': 1210067943,
    'message-received': 1210067947,
    'message-type': 0,              # = Channel_Text_Message_Type_Normal
    'pending-message-id': 437,
  },
  { 'alternative': 'main',
    'content-type': 'text/html',
    'content': 'Here is a photo of my cat:<br />' +
               '<img src="cid:catphoto" alt="lol!" />' +
               '<br />Isn't it cute?',
  },
  { 'alternative': 'main',
    'content-type': 'text/plain',
    'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
  },
  { 'identifier': 'catphoto',
    'content-type': 'image/jpeg',
    'size': 101000,
    'needs-retrieval': True,
  },
]

telepathy-ring, Nokia's GSM connection manager, represents vCards sent via SMS as:

[
  {
    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
    'message-sender': 42,
    'message-sent': 1210067943,
    'message-received': 1210067947,
    'message-type': 0,              # = Channel_Text_Message_Type_Normal
    'pending-message-id': 437,
  },
  { 'content-type': 'text/x-vcard',
    'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
  },
]

Delivery reports