DirectMessage

DirectMessage Service

Web service endpoints for direct messages. See DirectMessage for more information on the fields of a direct message.

Examples:
Create a Direct Message

POST to /dms to create a DirectMessage (dm). Here is an example using curl.

curl -u joe:password -H "Content-Type: application/json" --data '{ "content": { "text": "Did you arrange catering for the holiday party?"}, "participants": [ "http://example.jiveon.com/api/core/v3/people/1234" ] }' http://example.jiveon.com/api/core/v3/dms

Providing the recipients of a Direct Message

The participants field corresponds to the recipients of the direct message. Notice that you must provide an array of URIs to Jive users. However, the JSON returned in the response will have a list of fully populated Person objects. This is for convenience to reduce the number of requests required by your application and is a common pattern throughout the API. Note you can get the URI of a person via the myPerson.resources.self.ref resource field.

Create Participants

POST /dms/{dmID}/participants

Add a list of new participants to an existing direct message.

Path Parameters:
NameTypeRequiredDescription
dmIDStringtrueThe ID of the direct message to be updated
Query Parameters:
NameTypeRequiredDescription
sendEmailsBooleanfalseboolean indicating if participants should be notified by email. Default is true. Since 3.4.
fieldsStringfalseThe fields to be returned in the response
Takes:
  • JSON array containing the URI of people to add as participants. Limit the number of URIs per call to 200.
  • Retrieves:
  • DirectMessage describing the updated message
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to perform this operation
    404 (Not Found)The specified direct message is not found or one of the specified participants cannot be found

    Create Comment

    POST /dms/{dmID}/comments

    Create a new comment as a reply to the specified direct message. The parent field (if any) in the incoming entity will be ignored. Instead, it will be set to the URI of the specified direct message.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the directMessage this comment replies to
    Query Parameters:
    NameTypeRequiredDescription
    sendEmailsBooleanfalseFlag indicating that email notification should be sent if also selected in the user profile; a false value here overrides a true value in the profile. since 3.4
    authorIDIntegerfalseID of an author to override current user. Only set this field when importing content as an admin with full access.
    publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content as an admin with full access.
    updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content as an admin with full access.
    fieldsStringfalseFields to include in the returned Comment
    Takes:
  • Comment describing the comment to be created
  • Retrieves:
  • Comment describing the newly created comment
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)You attempt to add a comment to a directMessage for which comments have been closed
    403 (Forbidden)You are not allowed to perform this operation
    404 (Not Found)The specified parent direct message (or comment) cannot be found

    Create Direct Message

    POST /dms

    Create a new direct message based on the specified fields. This endpoint accepts a JSON representation like this:

         {
             "content" : {
                 "type" : "text/html",
                 "text" : "{text}"
             },
             "subject" : "{subject}",
             "participants" : [
                 "{participantURI}", ...
             ],
             "type" : "dm",
             "attachments":[
               {
                  "doUpload":true,
                  "url":"http://www.mysite.com/images/cat.jpg"
               }
              ]
         }
     

    where:

    • {text} - Text of the direct message.
    • {participantURI} - Absolute or partial (/people/####) URI for a Jive person that this message will be sent to.

    Attachments can only be images. Those images will be accessible through the images resource.

    Query Parameters:
    NameTypeRequiredDescription
    sendEmailsBooleanfalseboolean indicating if participants should be notified by email. Default is true. Since 3.4.
    authorIDIntegerfalseID of an author to override current user. Only set this field when importing content as an admin with full access.
    publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content as an admin with full access.
    updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content as an admin with full access.
    fieldsStringfalseThe fields to be returned in the response
    Takes:
  • JSON entity containing the fields describing the direct message to be created
  • Retrieves:
  • DirectMessage describing the newly created message
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to create this direct message
    404 (Not Found)One of the specified participants cannot be found

    Upload New Direct Message

    POST /dms

    Create a new direct message based on the specified fields. Uploaded files will be added to the new direct message as attachments. Attachments can only be images. Those images will be accessible through the images resource.

    Query Parameters:
    NameTypeRequiredDescription
    sendEmailsBooleanfalseboolean indicating if participants should be notified by email. Default is true. Since 3.4.
    authorIDIntegerfalseID of an author to override current user. Only set this field when importing content as an admin with full access.
    publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content as an admin with full access.
    updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content as an admin with full access.
    fieldsStringfalseThe fields to be returned in the response
    Takes:
  • A multipart of subtype form-data that will include a section with a DirectMessage describing the direct message to be created and another section for each image file being uploaded.
  • Retrieves:
  • DirectMessage describing the newly created message
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to create this direct message
    404 (Not Found)One of the specified participants cannot be found

    Destroy Direct Message

    DELETE /dms/{dmID}

    Delete the specified direct message.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueThe ID of the direct message to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to delete the specified direct message
    404 (Not Found)The specified direct message is not found

    Get Comments

    GET /dms/{dmID}/comments

    Return a paginated list of comments to the specified directMessage, optionally limiting the returned results to direct replies only.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the directMessage for which to return comments
    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falsethe filters to be applied on comments
    excludeRepliesBooleanfalseFlag indicating whether to exclude replies (and therefore return direct comments only)
    hierarchicalBooleanfalseFlag indicating that comments should be returned in hierarchical order instead of chronological order
    startIndexIntegerfalseZero-relative index of the first comment to be returned
    countIntegerfalseMaximum number of comments to be returned
    anchorStringfalseoptional URI for a comment to anchor at. Specifying a anchor will try to return the page containing the anchor. If the anchor could not be found then the first page of comments will be returned.
    fieldsStringfalseFields to be returned in the selected comments
    Retrieves:
  • Comment[] listing comments to the specified direct message
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified directMessage or comments
    404 (Not Found)The specified directMessage does not exist

    Get Content Images

    GET /dms/{dmID}/images

    Return metadata about the images associated with an DirectMessage.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the direct message for which to return image metadata
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Image[]
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the specified direct message
    404 (Not Found)The specified direct message is not found

    Get Direct Message

    GET /dms/{dmID}

    Retrieve and return the specified direct message.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the direct message to be retrieved
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be included in the returned
    Retrieves:
  • DirectMessage describing the specified directMessage
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the specified directMessage
    404 (Not Found)The specified directMessage is not found

    Mark Read

    POST /dms/{dmID}/read

    Mark the specified direct message as having been read.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the direct message to be marked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field was malformed
    403 (Forbidden)You are not allowed to access this direct message
    404 (Not Found)The specified direct message does not exist

    Mark Unread

    DELETE /dms/{dmID}/read

    Mark the specified direct message as having not been read.

    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the direct message to be marked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field was malformed
    403 (Forbidden)You are not allowed to access this direct message
    404 (Not Found)The specified direct message does not exist

    Create Subject

    POST /dms/{dmID}/subject

    Changes the subject (text) of the specified direct message. This endpoint accepts a JSON representation like this:

         {
             "subject" : "{subject}"
         }
     

    where:

    • {subject} - New subject (text) of the direct message.
    Path Parameters:
    NameTypeRequiredDescription
    dmIDStringtrueID of the direct message to have its subject (text) changed
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to be returned in the response
    Takes:
  • JSON entity containing the fields describing the modified subject (text) of the direct message
  • Retrieves:
  • DirectMessage describing the modified directMessage
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to modify the specified directMessage
    404 (Not Found)The specified directMessage is not found