HTTP API

Reference

Conversations API

Endpoints for chats and item discussions: messages, participants, polls, message reminders and starred messages.

This group covers chats and the discussions of tasks, requests, pull requests, meetings and app records: their messages and participants, polls, message reminders and starred messages. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope Volobox). An integration app's own client secret is refused with 403 (Volobox:Integrations:MemberConnectionRequired). Paths, tokens and conventions are in API overview.

Conversations

POST/api/v1/conversation
Creates a chat with the members and title the caller gives.
conversations.conversation.create
GET/api/v1/conversation/{id}
Gets a conversation the caller can open.
conversations.conversation.get
POST/api/v1/conversation/{id}/archive
Archives a conversation so it leaves the chat list.
conversations.conversation.archive
GET/api/v1/conversation/{id}/effective-members
Lists everyone who is a member of a conversation, directly or through a group, project or desk.
conversations.conversation.getEffectiveMembers
GET/api/v1/conversation/{id}/participants
Lists the participant rows of a conversation the caller can open.
conversations.conversation.getParticipants
POST/api/v1/conversation/{id}/participants
Adds a person, group or agent to a conversation the caller may change.
conversations.conversation.addParticipant
DELETE/api/v1/conversation/{id}/participants
Removes a person, group or agent from a conversation, or lets the caller leave it.
conversations.conversation.removeParticipant
GET/api/v1/conversation/{id}/related-item
Gets the item a conversation discusses (a task, request, pull request, meeting or app record), or null for a plain chat.
conversations.conversation.getRelatedItem
PUT/api/v1/conversation/{id}/star
Stars or unstars a conversation for the caller.
conversations.conversation.star
PUT/api/v1/conversation/{id}/title
Renames a conversation.
conversations.conversation.rename
POST/api/v1/conversation/{id}/unarchive
Brings an archived conversation back to the chat list.
conversations.conversation.unarchive
POST/api/v1/conversation/ensure-direct
Returns the caller's direct message conversation with another member, creating it when there is none.
conversations.conversation.ensureDirect
POST/api/v1/conversation/ensure-for-group
Returns the conversation of a group the caller can open, creating it when there is none.
conversations.conversation.ensureForGroup
POST/api/v1/conversation/ensure-for-project
Returns a project's channel conversation, creating it when there is none.
conversations.conversation.ensureForProject
GET/api/v1/conversation/for-app-record
Returns the discussion of a published app record the caller can read, or null while it has none.
conversations.conversation.findForAppRecord
GET/api/v1/conversation/for-meeting
Returns the chat of a meeting the caller can see, or null while it has none.
conversations.conversation.findForMeeting
GET/api/v1/conversation/for-pull-request
Returns the discussion of a pull request, or null while it has none.
conversations.conversation.findForPullRequest
GET/api/v1/conversation/for-request
Returns the discussion of a project request, or null while it has none.
conversations.conversation.findForRequest
GET/api/v1/conversation/for-task
Returns the discussion of a task, or null while it has none.
conversations.conversation.findForTask
POST/api/v1/conversation/join-app-record
Joins a published app record's discussion, creating it when there is none; seats the caller only.
conversations.conversation.joinAppRecordConversation
POST/api/v1/conversation/join-calendar-event
Joins the chat of an event on the caller's own connected calendar, creating it with the event's guests who are workspace members.
conversations.conversation.joinCalendarEventConversation
POST/api/v1/conversation/join-meeting
Joins a meeting's chat, creating it when there is none.
conversations.conversation.joinMeetingConversation
POST/api/v1/conversation/join-pull-request
Joins a pull request's discussion, creating it when there is none.
conversations.conversation.joinPullRequestConversation
POST/api/v1/conversation/join-request
Joins a project request's discussion, creating it when there is none.
conversations.conversation.joinRequestConversation
POST/api/v1/conversation/join-task
Joins a task's discussion, creating it when there is none.
conversations.conversation.joinTaskConversation
GET/api/v1/conversation/mentionable-agents
Lists the agents the caller can mention in a conversation.
conversations.conversation.getMentionableAgents
GET/api/v1/conversation/mentionable-groups
Lists the groups the caller can mention in a conversation.
conversations.conversation.getMentionableGroups
GET/api/v1/conversation/my-list
Lists the conversations the caller can open in their chat list, filtered and paged. Acts on the signed-in person's own account.
conversations.conversation.getMyList
POST/api/v1/conversation/send-app-record-message
Sends a message in a published app record's discussion, creating it and seating the caller when needed.
conversations.conversation.sendAppRecordMessage
POST/api/v1/conversation/send-pull-request-message
Sends a message in a pull request's discussion, creating the discussion and seating the caller when needed.
conversations.conversation.sendPullRequestMessage
POST/api/v1/conversation/send-request-message
Sends a message in a project request's discussion, creating the discussion and seating the caller when needed.
conversations.conversation.sendRequestMessage
POST/api/v1/conversation/send-task-message
Sends a message in a task's discussion, creating the discussion and seating the caller when needed.
conversations.conversation.sendTaskMessage

Request bodies:

  • CreateConversationDto (create): requires participants (array of ConversationParticipantInputDto).

Messages

DELETE/api/v1/conversation-messaging/{messageId}
Deletes a message the caller wrote or may moderate.
conversations.conversationMessaging.deleteMessage
POST/api/v1/conversation-messaging/add-reaction
Adds the caller's emoji reaction to a message.
conversations.conversationMessaging.addReaction
POST/api/v1/conversation-messaging/edit
Edits a message the caller wrote.
conversations.conversationMessaging.edit
GET/api/v1/conversation-messaging/file-references
Lists the Drive files referenced in a conversation's messages, paged.
conversations.conversationMessaging.getFileReferences
GET/api/v1/conversation-messaging/files
Lists the files other than pictures and videos shared in a conversation, paged.
conversations.conversationMessaging.getFiles
POST/api/v1/conversation-messaging/forward
Forwards a message to one or more conversations the caller can write in.
conversations.conversationMessaging.forward
GET/api/v1/conversation-messaging/links
Lists the links shared in a conversation, paged.
conversations.conversationMessaging.getLinks
GET/api/v1/conversation-messaging/media
Lists the pictures and videos shared in a conversation, paged.
conversations.conversationMessaging.getMedia
GET/api/v1/conversation-messaging/messages
Lists a page of the messages of a conversation the caller can open, newest page first, or around, before or from a given message.
conversations.conversationMessaging.getMessages
GET/api/v1/conversation-messaging/references
Lists the Volobox items referenced in a conversation's messages, paged.
conversations.conversationMessaging.getReferences
POST/api/v1/conversation-messaging/remove-reaction
Removes the caller's emoji reaction from a message.
conversations.conversationMessaging.removeReaction
POST/api/v1/conversation-messaging/search
Searches messages across the conversations the caller can open, or within one conversation.
conversations.conversationMessaging.searchMessages
POST/api/v1/conversation-messaging/send
Sends a message to a conversation the caller can write in.
conversations.conversationMessaging.send

Message reminders

GET/api/v1/message-reminders
Lists all of the caller's pending message reminders.
conversations.messageReminders.getPending
POST/api/v1/message-reminders
Sets a reminder for the caller about a message at a chosen time.
conversations.messageReminders.create
POST/api/v1/message-reminders/{id}/cancel
Cancels one of the caller's pending message reminders.
conversations.messageReminders.cancel
POST/api/v1/message-reminders/{id}/reschedule
Moves one of the caller's pending message reminders to a new time.
conversations.messageReminders.reschedule
GET/api/v1/message-reminders/conversation/{conversationId}
Lists the caller's pending reminders on messages of one conversation.
conversations.messageReminders.getPendingForConversation

Request bodies:

  • CreateMessageReminderInput (create): requires messageId (uuid), remindAtUtc (date-time).

Message stars

GET/api/v1/message-stars
Lists the messages the caller has starred, paged.
conversations.messageStars.getList
PUT/api/v1/message-stars/{messageId}
Stars a message for the caller.
conversations.messageStars.star
DELETE/api/v1/message-stars/{messageId}
Removes the caller's star from a message.
conversations.messageStars.unstar
GET/api/v1/message-stars/conversation/{conversationId}/message-ids
Lists the ids of the messages the caller has starred in one conversation.
conversations.messageStars.getStarredMessageIds
GET/api/v1/message-stars/conversations
Lists the conversations that hold messages the caller has starred.
conversations.messageStars.getStarredConversations

Polls

GET/api/v1/poll/{id}
Gets a poll in a chat the caller can read.
conversations.poll.get
PUT/api/v1/poll/{id}
Changes a poll the caller asked.
conversations.poll.update
POST/api/v1/poll/{id}/close
Closes a poll the caller asked, so it takes no more answers.
conversations.poll.close
POST/api/v1/poll/{id}/remind
Pings the chat's people who have not answered a poll the caller asked, at most once a day.
conversations.poll.remindPending
GET/api/v1/poll/{id}/voters
Lists who picked an option of a named poll whose voters the caller may see, paged.
conversations.poll.getVoters
POST/api/v1/poll/conversation
Asks a chat a question: posts one message by the caller that carries the poll.
conversations.poll.createInConversation
GET/api/v1/poll/in-conversation
Lists the polls of a chat the caller can read, open ones first, each with the caller's own view of it.
conversations.poll.getListInConversation
POST/api/v1/poll/many
Gets several polls in one read, leaving out the ones the caller cannot read.
conversations.poll.getMany
POST/api/v1/poll/vote/{id}
Records or changes the caller's answer to a poll in a chat they can write in.
conversations.poll.vote

Request bodies:

  • UpdatePollDto (update): requires options (array of UpdatePollOptionDto), question (string).
  • CreateConversationPollDto (createInConversation): requires options (array of string), question (string).

Example

conversations.conversation.getMyList: lists the conversations the caller can open in their chat list, filtered and paged.

curl
curl -s "https://volobox.example.com/api/v1/conversation/my-list" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"