# Conversations API

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](/docs/api-overview).

## Conversations

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

Request bodies:

- `CreateConversationDto` (`create`): requires `participants` (array of ConversationParticipantInputDto).

## Messages

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

## Message reminders

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

Request bodies:

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

## Message stars

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

## Polls

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

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.

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