Message Resource

A message is generic container for content shared between people, a group or a network.

Changelog

1.0.7

  • Support for an array of recipients (write-context).

1.0.8

  • Application EID (write-context).
  • Localizable body for multi-language messages.

1.0.10

  • Added appData property.

1.0.11

  • Added bubble property.

1.0.16

  • Added numAttachments and numLikes properties.
  • Added _user.hasLiked and _user.hasRecentlyCommented properties.
  • Added like and likes relation.

1.0.17

  • Added embeds property.

1.0.18

  • Added announcement message type.
  • Added data property.
  • Added event property.

1.0.19

  • Added mentions property.

1.0.24

  • Added file.hasSubfolders and file.path properties.

1.0.26

  • Added numRecipients property.
  • Added _user.permissions property.

1.1.14

  • Added lastEditor relation, lastModified, lastEdited and status fields.
  • Added htmlBody
  • Added headerBackground

1.3

  • Added superseeded property.

1.3.1

  • Added _user.subscribed property.

1.3.6

  • Added dimensions object for image files.

1.4

  • Deprecated attachments relation for update type messages.
  • Added numFiles property.
  • Added files relation for update type messages.
  • Added numImages property.
  • Added images relation for update type messages.
  • Added numVideos property.
  • Added videos relation for update type messages.

1.5

  • Renamed event property to annoucement.
  • Added event message type.
  • Added event property.
  • Added responderCounts property.

1.5.1

  • Added cancel relation for event type messages.
  • Added reinstate relation for event type messages.
  • Added rsvp relation for event type messages.

1.5.6

  • Added reason property to Bubble object.

1.6.6

  • Added numVideoViews for file message type

Representations

JSON

Properties

Name Type Description
announcement
(before 1.5 named event)
string Since 1.0.18 Announcement event type: participant_joined, participant_left, title_changed or icon_changed
appData string Since 1.0.10 Optional data provided by the app that generated the message
body string Message body
bubble object Since 1.0.11 Bubbled message properties
bubble. bubbled datetime Read-only Last time bubbling took place
bubble. numRecentCommenters boolean Read-only Number of commenters since message was last bubbled
bubble. reason string Since 1.5.6 Read-only Reason why the message bubbled: new_comment, date_time_changed, location_changed or details_changed
commentable boolean Whether or not comments may be posted on the message
created datetime Read-only Date the message was created (ISO 8601 compliant)
data datetime Since 1.0.18 Read-only Data relevant to the announcement
deletedBy string Since 1.0 Read-only If applicable, information on the user that deleted the message
EID EID Unique entity identifier
embeds array Since 1.0.17 List of embedded URLs
event object Since 1.5 Event details event
file object Read-only Optional file information (in case of messageType ``file`) <file>`
headerBackgroundUrl string Since 1.1.14 Read-only URL of the header background
htmlBody string Since 1.1.14 HTML5 body (only for news messageType). Note that the body and htmlBody fields are mutually exclusive in a write context. When retrieving, the HTML body is converted to plain text in the body field for backward compatibility
lastModified datetime Since 1.1.14 Read-only When the message was last modified (only for messageType news and update)
lastEdited datetime Since 1.1.14 Read-only When content of the message was last edited (only for messageType news and update)
localizableBody object Since 1.0.8 Localizable message body
localizableBody. <locale> string Body in the language of the RFC 5646/4647 <locale>
mentions array Since 1.0.17 List of mentions
messageType string Read-only Message type: update, comment, file, news, private event, app_update or announcement
numRecipients number Since 1.0.26 Read-only Number of recipients
numAttachments number Since 1.0.16 Read-only Number of attachments
numComments number Read-only Number of comments
numFiles number Since 1.4 Read-only Number of attached files
numImages number Since 1.4 Read-only Number of attached images
numLikes number Since 1.0.16 Read-only Number of likes
numVideos number Since 1.4 Read-only Number of attached videos
numVideoViews number Since 1.6.6 Read-only Number of video views
status string Since 1.1.14 For news messages, this can be draft or published
superseeded boolean Since 1.3 Read-only This only applies in the context of an edit-history and signifies that this is not the latest version
teaserThumbnailUrl URI File URL to news teaser image thumbnail
title string News message title
type string “message”

Event properties (since 1.5)

Name Type Description
allDay boolean Whether or not the event lasts all day
end object Exclusive! end date/time of an event
end. date string End date (ISO 8601 YYYY-MM-DD)
end. time string End time (ISO 8601 hh:mm) of non-all-day event
end. timeZone string End time zone (IANA zone name) of non-all-day event
end. timeZoneOffset string Read-only Time zone offset at end date/time (±hh:mm)
start object Start date/time of an event
start. date string Start date (ISO 8601 YYYY-MM-DD)
start. time string Start time (ISO 8601 hh:mm) of non-all-day event
start. timeZone string Start time zone (IANA zone name) of non-all-day event
start. timeZoneOffset string Read-only Time zone offset at start date/time (±hh:mm)
location object Location
location. description string Human-readable description of the location
responderCounts object Users that RSVP’ed (counts per answer option)
responderCounts. yes number Number of users that responded they will attend the event
responderCounts. maybe number Number of users that said they might attend the event
responderCounts. no number Number of users that said they won’t attend the event
responderCounts. unspecified number Number of users that did not yet respond to the event

Embedded URL properties (since 1.0.17)

Name Type Description
desktopThumbnailUrl URI File URL to thumbnail
metadata string Meta-data to describe the embed
url URI URL used for linking the embed

Mention properties (since 1.0.19)

Name Type Description
EID EID Unique entity identifier of the mentioned user
length integer String length of the mention
offset integer Offset of the mention in the message body
type string Mentioned type ('user')

File Properties

Name Type Description
file. displayUrls object URLs for different file formats
file.displayUrls. profileImage string Preview for use on profile page (Retina)
file.displayUrls. thumbnail string Generic web thumbnail (Retina)
file.displayUrls. timelinePreviewSmall string Preview for use with timeline (small, non-Retina)
file.displayUrls. timelinePreviewLarge string Preview for use with timeline (large, non-Retina)
file. extension string The file’s extension (without leading dot)
file. filename string Filename
file. hasSubfolders boolean Since 1.0.24 Whether there are subfolders in this folder
file. mimeType string MIME type ("inode/directory" for folders)
file. name string Name of the file (typically, but not necessarily, this is the same as the filename without extension)
file. numChildren integer Number of direct children
file. path array Since 1.0.24 List of folders.
file. size integer File size in bytes
file. trashed boolean Whether or not the file has been removed
file. type string File type: avatar, background_image, document, emblem, file, folder, icon, image, inline_image, news_background_image, profile_background_image, teaser_image or video
file. url URI URL to the (original) attachment
file. dimensions object Dimensions (only for image files uploaded since API version 1.3.6)
file.dimensions. width integer Since 1.3.6 Width in pixels
file.dimensions. height integer Since 1.3.6 Height in pixels
file.dimensions. aspectRatio string Since 1.3.6 Aspect ratio of the image (not guaranteed)

End-user Metadata (read-only)

Name Type Description
hasLiked boolean Since 1.0.16 Whether the logged in user has liked the message
hasRecentlyCommented boolean Since 1.0.16 Whether the logged in user has recently commented on the message. A comment is considered recent when it caused or is placed after the most recent bubble event of the message.
permissions string Since 1.0.26 Comma-separated list of permissions the logged in user has
read boolean Whether a message has been read or not (only for news items)
rsvp string Since 1.5 RSVP response to an event by the logged in user: yes, maybe, no or unspecified
subscribed boolean Since 1.3.1 Whether the logged in is subscribed to the message c.q. receives notifications

Example - update message

{
    "_links": {
        "self": {
            "href": "/networks/fedcba0987654321/messages/1234567890abcdef/"
        },
        "author": {
            "href": "/networks/fedcba0987654321/users/abcdef0123456789/"
        },
        "comments": {
            "href": "/networks/fedcba0987654321/messages/?parent=1234567890ABCDEF"
        },
        "videos": {
            "href": "/networks/fedcba0987654321/messages/0123456789fedcba/"
        },
        "files": [
            { "href": "/networks/fedcba0987654321/messages/a1b2c3d4e5f67890/" },
            { "href": "/networks/fedcba0987654321/messages/09876f5e4d3c2b1a/" }
        ],
        "recipient": {
            "type": "network",
            "href": "/networks/fedcba0987654321/"
        }
    },
    "_user": {
        "hasRecentlyCommented": true,
        "hasLiked": false
    },
    "EID": "1234567890abcdef",
    "body": "Hello world!",
    "created": "2013-04-12T17:10:10.123+01:00",
    "commentable": true,
    "messageType": "update",
    "numFiles": 2,
    "numVideos": 1
}

Example - non-all-day event

{
    "_links": {
        "self": {
            "href": "/networks/fedcba0987654321/messages/1234567890abcdef/"
        }
    },
    "EID": "1234567890abcdef",
    "messageType": "event",
    "title": "Friday drinks",
    "htmlBody": "Cheers!",
    "event": {
        "allDay": false,
        "location": {
            "description": "Spiazzo"
        },
        "start": {
            "date": "2017-07-07",
            "time": "18:00",
            "timeZone": "Europe/Amsterdam",
            "timeZoneOffset": "+02:00"
        },
        "end": {
            "date": "2017-07-08",
            "time": "00:00",
            "timeZone": "Europe/Amsterdam",
            "timeZoneOffset": "+02:00"
        }
    }
    "created": "2017-06-27T13:03:51.123+02:00",
    "commentable": false
}

Example - comment with attachment

{
    "_links": {
        "self": {
            "href": "/networks/fedcba0987654321/messages/1234567890abcdef/"
        },
        "attachments": [{
            "href": "/networks/fedcba0987654321/messages/a1b2c3d4e5f67890/"
        }],
        "author": {
            "href": "/networks/fedcba0987654321/users/abcdef0123456789/"
        },
        "parent": {
            "href": "/networks/fedcba0987654321/messages/0123456789fedcba/"
        },
        "recipient": {
            "type": "group",
            "href": "/networks/fedcba0987654321/groups/1234567890abcdef/"
        }
    },
    "_user": {
        "hasLiked": false
    },
    "EID": "1234567890abcdef",
    "body": "Check out my curriculum vitae",
    "created": "2013-04-12T17:10:10.123+01:00",
    "messageType": "comment",
    "numAttachments": 1
}

Example - file message

{
    "_links": {
        "self": {
            "href": "/networks/fedcba0987654321/messages/a1b2c3d4e5f67890/"
        },
        "author": {
            "href": "/networks/fedcba0987654321/users/abcdef0123456789/"
        }
    },
    "EID": "a1b2c3d4e5f67890",
    "commentable": false,
    "created": "2013-04-12T21:41:15.123+01:00",
    "file": {
        "extension": "doc",
        "filename": "cv.doc",
        "mimeType": "application/msword",
        "name": "cv",
        "path": [
            { "name": "HR", "EID": "9876543210abcdef" },
            { "name": "Résumés", "EID": "abcdef0987654321" }
        ],
        "type": "document",
        "url": "http://vault.speakap.com/file/1234567890abcdef"
    },
    "messageType": "file",
    "type": "message"
}

Example - announcement

{
    "_links": {
        "originator": {
            "href": "/networks/fedcba0987654321/users/a1b2c3d4e5f67890/"
        },
        "conversation": {
            "href": "/networks/fedcba0987654321/conversations/abcdef0123456789/"
        },
        "participants":  [{
            "href": "/networks/fedcba0987654321/users/1234567890abcdef/",
            "href": "/networks/fedcba0987654321/users/4567890abcdef123/"
        }]
    },
    "EID": "1234567890abcdef",
    "created": "2013-04-12T17:10:10.123+01:00",
    "event": "participant_joined",
    "messageType": "announcement"
}