Create a new conversation.
post
/social/api/v1/conversations
Request
Supported Media Types
- application/json
The request body defines the details of the request.
Root Schema : XV1ConversationCreateInfo
Type:
object
V1 Conversation Create Information.
Show Source
-
altitude(optional):
number(double)
The altitude. Can be null.
-
discoverableID(optional):
An object's unique identifier from a long integer representation.
-
externalID(optional):
string
The conversation primary external ID.
-
hasMembersLocked(optional):
boolean
The member is locked.
-
hierarchicalMembersUpdateInfo(optional):
object XV1HierarchicalMembersUpdateInfo
V1 Collaboration API Hierarchical Members update DTO.
-
isDisallowGuests(optional):
boolean
Allow guests.
-
isDiscoverable(optional):
boolean
Make discoverable (public).
-
isExtendedAccessControl(optional):
boolean
Enable extended access control.
-
isOwnerHidden(optional):
boolean
The new owner is a hidden member.
-
isOwnerLocked(optional):
boolean
The new owner is a locked member.
-
isOwnerNotMember(optional):
boolean
The owner should not become a member.
-
isScoping(optional):
boolean
The conversation should be scoping.
-
latitude(optional):
number(double)
The latitude. Can be null.
-
longitude(optional):
number(double)
The longitude. Can be null.
-
name(optional):
string
The conversation name. Required.
Nested Schema : XV1HierarchicalMembersUpdateInfo
Type:
object
V1 Collaboration API Hierarchical Members update DTO.
Show Source
-
addedMemberGroups(optional):
array addedMemberGroups
List of added groups. Can be empty. This can specify the group externalID, name or objectID.
-
addedMemberUserNames(optional):
array addedMemberUserNames
List of added users. Can be empty.
-
childFolderIDs(optional):
array childFolderIDs
List of child folder IDs. Can be empty. Use this to build up parent-child relationships within the member hierarchy.
-
childUpdateInfos(optional):
array childUpdateInfos
List of child XV1HierarchicalMembersUpdateInfos.
-
conversationID(optional):
integer(int64)
The conversation ID for a file. To be used with the MOVE_FILE operation.
-
EVERYONE_GROUP(optional):
string
Canonical everyone group name.
-
fileID(optional):
string
The file ID. To be used with the MOVE_FILE operation.
-
findOrCreateConversation(optional):
boolean
If set true will find an existing conversation for the CREATE_CONVERSATION operation.
-
folderID(optional):
string
The folder ID.
-
HM_ROOT(optional):
string
Hierarchical members root. Use to specify parentFolderID when parent should be the root.
-
impersonateUser(optional):
string
User to impersonate.
-
operationType(optional):
object XV1HierarchicalMembersOperationType
-
parentFolderID(optional):
string
The parent folder ID. Can be null. Will be ignored if parentUpdateInfo is set. Set parentUpdateInfo to null and parentFolderID to the folderID of the topmost folder in the ancestor hierarchy.
-
parentUpdateInfo(optional):
object XV1HierarchicalMembersUpdateInfo
V1 Collaboration API Hierarchical Members update DTO.
-
recurse(optional):
boolean
Used with the REMOVE_MEMBERS_OBJECT operation to mean remove recursively.
-
removedMemberGroups(optional):
array removedMemberGroups
List of removed groups. Can be empty. This can specify the group externalID, name or objectID.
-
removedMemberUserNames(optional):
array removedMemberUserNames
List of removed users. Can be empty.
Nested Schema : addedMemberGroups
Type:
array
List of added groups. Can be empty. This can specify the group externalID, name or objectID.
Show Source
-
Array of:
string
List of added groups. Can be empty. This can specify the group externalID, name or objectID.
Nested Schema : addedMemberUserNames
Type:
array
List of added users. Can be empty.
Show Source
-
Array of:
string
List of added users. Can be empty.
Nested Schema : childFolderIDs
Type:
array
List of child folder IDs. Can be empty. Use this to build up parent-child relationships within the member hierarchy.
Show Source
-
Array of:
string
List of child folder IDs. Can be empty. Use this to build up parent-child relationships within the member hierarchy.
Nested Schema : childUpdateInfos
Type:
array
List of child XV1HierarchicalMembersUpdateInfos.
Show Source
-
Array of:
object XV1HierarchicalMembersUpdateInfo
V1 Collaboration API Hierarchical Members update DTO.
Nested Schema : XV1HierarchicalMembersOperationType
Type:
Show Source
object
-
field(optional):
string
Allowed Values:
[ "ASSOCIATE_CONVERSATION", "CREATE_CONVERSATION", "MOVE_FILE", "MOVE_FOLDER", "MOVE_MEMBERS", "REMOVE_MEMBERS", "REMOVE_MEMBERS_OBJECT", "SHARE_FOLDER" ]
V1 Users and Groups API Operation Types on Hierarchical Members.
Nested Schema : removedMemberGroups
Type:
array
List of removed groups. Can be empty. This can specify the group externalID, name or objectID.
Show Source
-
Array of:
string
List of removed groups. Can be empty. This can specify the group externalID, name or objectID.
Nested Schema : removedMemberUserNames
Type:
array
List of removed users. Can be empty.
Show Source
-
Array of:
string
List of removed users. Can be empty.
Response
Supported Media Types
- application/json
200 Response
Successful operation.
Root Schema : XV1ConversationInfo
Type:
object
V1 Conversation Information DTO.
Show Source
-
allMembershipsURL(optional):
string(url)
A URL to the hierarchical memberships of this conversation.
-
altitude(optional):
number(double)
The object's altitude.
-
archiveURL(optional):
string(url)
A URL to the archive of this conversation.
-
collectionURL(optional):
string(url)
A URL to this object's containing collection.
-
conversationURL(optional):
string(url)
A URL to this object's containing conversation.
-
createdByID(optional):
An object's unique identifier from a long integer representation.
-
createdByURL(optional):
string(url)
A URL to the user that created this object.
-
createdByUserDisplayName(optional):
string
The display name of the user that created this object.
-
createdByUserName(optional):
string
The name of the user that created this object.
-
createdDate(optional):
string(date)
The date this object was created.
-
createdDateInISO8601Format(optional):
string
The date this object was created, in ISO 8601 format.
-
dateFormatLocale(optional):
string(locale)
The locale of the appropriate date format for this conversation.
-
discoverableID(optional):
An object's unique identifier from a long integer representation.
-
displayName(optional):
string
The display name of this object.
-
externalID(optional):
string
The primary external ID of this conversation.
-
folderID(optional):
An object's unique identifier from a long integer representation.
-
folderURL(optional):
string(url)
A URL to the root folder of this conversation.
-
gadgetsURL(optional):
string(url)
A URL to the gadgets of this conversation.
-
hasMembersLocked(optional):
boolean
True if the membership of this conversation is locked.
-
hierarchicalMembersInfo(optional):
object XV1HierarchicalMembersInfo
V1 Hierarchical Members Information DTO.
-
id(optional):
An object's unique identifier from a long integer representation.
-
isDisallowGuests(optional):
boolean
True if this conversation does not allow guest users.
-
isDisallowOutsiders(optional):
boolean
True if this conversation does not allow outsider users.
-
isDiscoverable(optional):
boolean
True if this conversation is discoverable (public).
-
isExtendedAccessControl(optional):
boolean
True if this conversation uses extended access control.
-
isMuted(optional):
boolean
True if this conversation is muted for the current user.
-
isNew(optional):
boolean
True if this conversation has not been entered by the current user.
-
isRemoved(optional):
boolean
True if this message has been removed.
-
isScoped(optional):
boolean
True if the membership of this conversation is scoped by another conversation.
-
isScoping(optional):
boolean
True if this is a scoping conversation.
-
isScopingSame(optional):
boolean
True if this conversation is scoped to have the same membership as another conversation.
-
languageLocale(optional):
string(locale)
The language locale for this conversation.
-
latitude(optional):
number(double)
The object's latitude.
-
likesURL(optional):
string(url)
A URL to the likes of this conversation.
-
longitude(optional):
number(double)
The object's longitude.
-
membershipsURL(optional):
string(url)
A URL to the memberships of this conversation.
-
membersURL(optional):
string(url)
A URL to the members of this conversation.
-
messagesURL(optional):
string(url)
A URL to the messages in this conversation.
-
modifiedByID(optional):
An object's unique identifier from a long integer representation.
-
modifiedByURL(optional):
string(url)
A URL to the user that last modified this object.
-
modifiedByUserDisplayName(optional):
string
The display name of the user that last modified this object.
-
modifiedByUserName(optional):
string
The name of the user that last modified this object.
-
modifiedDate(optional):
string(date)
The date this object was last modified.
-
modifiedDateInISO8601Format(optional):
string
The date this object was last modified, in ISO 8601 format.
-
name(optional):
string
The name of this object.
-
nChats(optional):
integer(int32)
The number of chats in this conversation. (total chats less deleted chats.)
-
nFollowups(optional):
integer(int32)
The number of followups in the conversation.
-
nMarkableChats(optional):
integer(int32)
The number of chats that could be marked read. (Total markable less deleted markable. Does not depend on the current user.)
-
nOutsiders(optional):
integer(int32)
Count of the outside users.
-
nUnread(optional):
integer(int32)
The number of chats that the current user can mark read.
-
objectType(optional):
string
The type of this object.
-
originalPictureURL(optional):
string(url)
The original picture URL.
-
profilePictureURL(optional):
string(url)
The profile picture URL (150 px by 150 px).
-
propertiesURL(optional):
string(url)
A URL to the properties of this conversation.
-
removedByID(optional):
An object's unique identifier from a long integer representation.
-
removedByURL(optional):
string(url)
A URL to the user that last removed this object.
-
removedByUserDisplayName(optional):
string
The display name of the user that last removed this object.
-
removedByUserName(optional):
string
The name of the user that last removed this object.
-
removedDate(optional):
string(date)
The date this object was removed.
-
removedDateInISO8601Format(optional):
string
The date this object was removed, in ISO 8601 format.
-
role(optional):
string
The current user's role in this conversation.
-
scaledPictureURL(optional):
string(url)
The scaled picture URL (44 px by 44 px).
-
secondaryExternalIDs(optional):
array secondaryExternalIDs
The secondary external IDs for this conversation.
-
securityContextID(optional):
string
The ID of the service that dictates the security for this conversation object.
-
socialObjectURL(optional):
string(url)
A URL to this object's containing collaboration object.
-
starsURL(optional):
string(url)
A URL to the stars of this conversation.
-
state(optional):
object XV1ConversationState
-
timeZone(optional):
string(timezone)
The time zone for this conversation.
-
url(optional):
string(url)
A URL to this object.
-
userPropertiesURL(optional):
string(url)
A URL to the user properties of this conversation.
-
wallPostControl(optional):
object XV1WallPostControlEnum
Nested Schema : XV1HierarchicalMembersInfo
Type:
object
V1 Hierarchical Members Information DTO.
Show Source
-
conversationAlreadyExists(optional):
boolean
Set to true if a conversation already exists when operationType is CREATE_CONVERSATION.
-
createdFolderIDs(optional):
object XV1FolderIDListInfo
List of folder IDs.
-
ignoredMembers(optional):
object XV1IgnoredMemberListInfo
List of ignored members.
-
ignoredUsers(optional):
object XV1IgnoredUserListInfo
List of ignored users.
-
operationType(optional):
object XV1HierarchicalMembersOperationType
-
removedFolderIDs(optional):
object XV1FolderIDListInfo
List of folder IDs.
Nested Schema : secondaryExternalIDs
Type:
array
The secondary external IDs for this conversation.
Show Source
-
Array of:
string
The secondary external IDs for this conversation.
Nested Schema : XV1ConversationState
Type:
Show Source
object
-
field(optional):
string
Allowed Values:
[ "CLOSED_CHAINED", "CLOSED_DISABLED", "CLOSED_DROPPED", "CLOSED_RESOLVED", "OPEN_ACTIVE" ]
V1 Conversation States.
Nested Schema : XV1WallPostControlEnum
Type:
Show Source
object
-
field(optional):
string
Allowed Values:
[ "ANYONE_CAN_POST", "OWNER_ONLY_POSTS", "OWNER_TOP_LEVEL" ]
V1 Wall Posting Control Enum.
Nested Schema : XV1FolderIDListInfo
Type:
object
List of folder IDs.
Show Source
-
hasMore(optional):
boolean
If true, there are more items to be returned.
-
ids(optional):
array ids
List of folder IDs.
-
nextURL(optional):
string(url)
Next page URL for the list. Null if this is the last page.
-
previousURL(optional):
string(url)
Previous page URL for the list. Null if this is the first page.
-
total(optional):
integer(int32)
If specified, this is the total number of available items. Null if the total is unknown.
Nested Schema : XV1IgnoredMemberListInfo
Type:
object
List of ignored members.
Show Source
-
groups(optional):
array groups
List of users.
-
hasMore(optional):
boolean
If true, there are more items to be returned.
-
nextURL(optional):
string(url)
Next page URL for the list. Null if this is the last page.
-
previousURL(optional):
string(url)
Previous page URL for the list. Null if this is the first page.
-
total(optional):
integer(int32)
If specified, this is the total number of available items. Null if the total is unknown.
-
users(optional):
array users
List of users.
Nested Schema : XV1IgnoredUserListInfo
Type:
object
List of ignored users.
Show Source
-
hasMore(optional):
boolean
If true, there are more items to be returned.
-
nextURL(optional):
string(url)
Next page URL for the list. Null if this is the last page.
-
previousURL(optional):
string(url)
Previous page URL for the list. Null if this is the first page.
-
total(optional):
integer(int32)
If specified, this is the total number of available items. Null if the total is unknown.
-
users(optional):
array users
List of users.
Nested Schema : XV1HierarchicalMembersOperationType
Type:
Show Source
object
-
field(optional):
string
Allowed Values:
[ "ASSOCIATE_CONVERSATION", "CREATE_CONVERSATION", "MOVE_FILE", "MOVE_FOLDER", "MOVE_MEMBERS", "REMOVE_MEMBERS", "REMOVE_MEMBERS_OBJECT", "SHARE_FOLDER" ]
V1 Users and Groups API Operation Types on Hierarchical Members.
Nested Schema : ids
Type:
array
List of folder IDs.
Show Source
-
Array of:
string
List of folder IDs.
Examples
The following example shows how to create a new conversation by submitting a POST request on the REST resource using cURL.
curl -X POST -c mycookies.jar -b mycookies.jar -H 'X-Waggle-RandomID:6ad1e16c57bdd307010f30eb132e2188' -H 'Content-Type: application/json' -d '{ "name" : "conv5 from curl exampl" ,"externalID" : "ext00055" }' https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations
Example of Request Body
The following shows an example of the request document in JSON format.
{ "altitude": decimal number, "discoverableID": Object ID, "externalID": "text", "hasMembersLocked": false, "isDisallowGuests": false, "isDiscoverable": false, "isExtendedAccessControl": false, "isOwnerHidden": false, "isOwnerLocked": false, "isOwnerNotMember": false, "isScoping": false, "latitude": decimal number, "longitude": decimal number, "name": "text" }
Example of Response Body
The following shows an example of the response JSON document.
{ "id" : "22006", "name" : "conv5 from curl exampl", "objectType" : "waggle/conversation", "createdByID" : "11001", "createdByUserName" : "jeff.pringle@example.com", "createdByUserDisplayName" : "jeff.pringle@example.com", "createdByURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/people/11001", "createdDate" : 1455325485929, "modifiedByID" : "11001", "modifiedByUserName" : "jeff.pringle@example.com", "modifiedByUserDisplayName" : "jeff.pringle@example.com", "modifiedByURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/people/11001", "modifiedDate" : 1455325485929, "isRemoved" : false, "url" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006", "externalID" : "ext00055", "secondaryExternalIDs" : ["ext00055"], "isScoping" : false, "isScopingSame" : false, "isScoped" : false, "state" : "OPEN_ACTIVE", "isDiscoverable" : false, "wallPostControl" : "ANYONE_CAN_POST", "hasMembersLocked" : false, "isDisallowGuests" : false, "isDisallowOutsiders" : false, "nOutsiders" : 0, "isExtendedAccessControl" : false, "folderID" : "22011", "role" : "HOST", "isMuted" : false, "isNew" : true, "nChats" : 0, "nMarkableChats" : 0, "nUnread" : 0, "nFollowups" : 0, "membersURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/members", "membershipsURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/memberships", "messagesURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/messages", "propertiesURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/properties", "userPropertiesURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/userProperties", "starsURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/stars", "likesURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/likes", "gadgetsURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/gadgets", "archiveURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/conversations/22006/archive", "folderURL" : "https://socialnetwork06065-ustraveler15926.socialnetwork.dc1.c9dev1.example.com/osn/social/api/v1/folders/22011" }