DirectMessage

DirectMessage Service

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

Examples:

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:

Name	Type	Required	Description
dmID	String	true	The ID of the direct message to be updated

Query Parameters:

Name	Type	Required	Description
sendEmails	Boolean	false	boolean indicating if participants should be notified by email. Default is true. Since 3.4.
fields	String	false	The fields to be returned in the response

Takes:

JSON array containing the URI of people to add as participants

Retrieves:

DirectMessage describing the updated message

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
dmID	String	true	ID of the directMessage this comment replies to

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields 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 Code	Description
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}"
         },
         "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:

Name	Type	Required	Description
sendEmails	Boolean	false	boolean indicating if participants should be notified by email. Default is true. Since 3.4.
fields	String	false	The 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 Code	Description
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:

Name	Type	Required	Description
sendEmails	Boolean	false	boolean indicating if participants should be notified by email. Default is true. Since 3.4.
fields	String	false	The 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 Code	Description
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:

Name	Type	Required	Description
dmID	String	true	The ID of the direct message to be deleted

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
dmID	String	true	ID of the directMessage for which to return comments

Query Parameters:

Name	Type	Required	Description
excludeReplies	Boolean	false	Flag indicating whether to exclude replies (and therefore return direct comments only)
hierarchical	Boolean	false	Flag indicating that comments should be returned in hierarchical order instead of chronological order
startIndex	Integer	false	Zero-relative index of the first comment to be returned
count	Integer	false	Maximum number of comments to be returned
anchor	String	false	optional 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.
fields	String	false	Fields to be returned in the selected comments

Retrieves:

Comment[] listing comments to the specified direct message

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
dmID	String	true	ID of the direct message for which to return image metadata

Query Parameters:

Name	Type	Required	Description
fields	String	false	Names of the fields to be returned

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
dmID	String	true	ID of the direct message to be retrieved

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields to be included in the returned
abridged	Boolean	false	Flag indicating that if `content.text` is requested, it will be abridged (length shortened, HTML tags removed)

Retrieves:

DirectMessage describing the specified directMessage

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
dmID	String	true	ID of the direct message to be marked

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
dmID	String	true	ID of the direct message to be marked

Return Status:

HTTP Status Code	Description
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

DirectMessage

DirectMessage Service

Examples:

Jump to

Create Participants

Path Parameters:

Query Parameters:

Takes:

Retrieves:

Return Status:

Create Comment

Path Parameters:

Query Parameters:

Takes:

Retrieves:

Return Status:

Create Direct Message

Query Parameters:

Takes:

Retrieves:

Return Status:

Upload New Direct Message

Query Parameters:

Takes:

Retrieves:

Return Status:

Destroy Direct Message

Path Parameters:

Return Status:

Get Comments

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Get Content Images

Path Parameters:

Query Parameters:

Return Status:

Get Direct Message

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Mark Read

Path Parameters:

Return Status:

Mark Unread

Path Parameters:

Return Status: