Get all conversation the authenticated user has created or has access to
GET/v2/conversations
API version
v2
Request method
GET
Operation ID
conversation-list-conversations
Request
- fullTextSearchstring
keyword or "phrase" search
- statusarray of string (one of: open, closed)
- limitinteger (≥ 0)
The max count of resources to return in the list response.
- skipinteger
Number of items to skip. Should be multiple of
limit. - pageinteger (≥ 0)
Page to display.
skipandpageend up doing the same. If bothpageandskipare set, skip is used. - sortarray of string (one of: createdAt, lastMessage.createdAt, title, shortId, conversationId)
List of fields how the result should be sorted.
- orderarray of string (one of: asc, desc)
Should the result be sorted ascending or descending? You can specify for each field another sorting: sort[0]=foo, order[0]=asc, sort[1]=bar, order[1]=desc.
Responses
Response headers
- X-Pagination-Limitinteger
The limit used to select the resources for the response
- X-Pagination-Skipinteger
The number of skipped items
- X-Pagination-Pagenumber
The calculate page of the list response. Refer to parameters to learn more.
- X-Pagination-TotalCountinteger
The total amount of items available in the remote ressource. Use this value in combination with the limit to calculate the available pages.
Format
application/json
Description
The conversations list ordered by creation date
- Array[
- *
]
Content-Type: application/json
[
null
]
{
"items": {
"allOf": [
{
"properties": {
"category": {
"properties": {
"categoryId": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"referenceType": {
"items": {
"enum": [
"unspecified",
"server",
"project",
"organisation",
"extensionInstance"
],
"type": "string"
},
"type": "array"
}
},
"required": [
"categoryId",
"name",
"referenceType"
],
"type": "object"
},
"conversationId": {
"format": "uuid",
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"lastMessageAt": {
"format": "date-time",
"type": "string"
},
"mainUser": {
"properties": {
"active": {
"type": "boolean"
},
"avatarRefId": {
"type": "string"
},
"clearName": {
"type": "string"
},
"isEmployee": {
"type": "boolean"
},
"userId": {
"type": "string"
}
},
"required": [
"userId"
],
"type": "object"
},
"notificationRoles": {
"items": {
"enum": [
"customer_owner",
"customer_accountant",
"customer_member",
"project_owner",
"project_emailadmin",
"project_external"
],
"type": "string"
},
"type": "array"
},
"relatedTo": {
"oneOf": [
{
"properties": {
"aggregate": {
"enum": [
"user"
],
"type": "string"
},
"domain": {
"enum": [
"user"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"customer"
],
"type": "string"
},
"domain": {
"enum": [
"customer"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"project"
],
"type": "string"
},
"domain": {
"enum": [
"project"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"appinstallation"
],
"type": "string"
},
"domain": {
"enum": [
"app"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"placementgroup"
],
"type": "string"
},
"domain": {
"enum": [
"project"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"extensionInstance"
],
"type": "string"
},
"domain": {
"enum": [
"extension"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"container"
],
"type": "string"
},
"domain": {
"enum": [
"container"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
}
]
},
"relations": {
"items": {
"properties": {
"aggregate": {
"type": "string"
},
"domain": {
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
"type": "array"
},
"sharedWith": {
"oneOf": [
{
"properties": {
"aggregate": {
"enum": [
"user"
],
"type": "string"
},
"domain": {
"enum": [
"user"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"customer"
],
"type": "string"
},
"domain": {
"enum": [
"customer"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"project"
],
"type": "string"
},
"domain": {
"enum": [
"project"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
},
{
"properties": {
"aggregate": {
"enum": [
"placementgroup"
],
"type": "string"
},
"domain": {
"enum": [
"project"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"aggregate",
"domain"
],
"type": "object"
}
]
},
"shortId": {
"type": "string"
},
"status": {
"enum": [
"open",
"closed",
"answered",
"inProgress",
"waiting"
],
"type": "string"
},
"title": {
"type": "string"
},
"visibility": {
"enum": [
"shared",
"private"
],
"type": "string"
}
},
"required": [
"conversationId",
"shortId",
"title",
"createdAt",
"status",
"visibility",
"mainUser"
],
"type": "object"
},
{
"properties": {
"createdBy": {
"properties": {
"active": {
"type": "boolean"
},
"avatarRefId": {
"type": "string"
},
"clearName": {
"type": "string"
},
"isEmployee": {
"type": "boolean"
},
"userId": {
"type": "string"
}
},
"required": [
"userId"
],
"type": "object"
},
"lastMessage": {
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"properties": {
"active": {
"type": "boolean"
},
"avatarRefId": {
"type": "string"
},
"clearName": {
"type": "string"
},
"isEmployee": {
"type": "boolean"
},
"userId": {
"type": "string"
}
},
"required": [
"userId"
],
"type": "object"
}
},
"required": [
"createdAt"
],
"type": "object"
},
"lastMessageBy": {
"properties": {
"active": {
"type": "boolean"
},
"avatarRefId": {
"type": "string"
},
"clearName": {
"type": "string"
},
"isEmployee": {
"type": "boolean"
},
"userId": {
"type": "string"
}
},
"required": [
"userId"
],
"type": "object"
}
},
"type": "object"
}
]
},
"type": "array"
}
Format
application/json
Description
Your request ran into a rate limit. You have to wait until rate limit expires
- messagestring
- typestring
Content-Type: application/json
{
"message": "too many requests",
"type": "RateLimitError"
}
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "too many requests"
},
"type": {
"type": "string",
"example": "RateLimitError"
}
}
}
Format
application/json
Description
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
Usage examples
$ curl \
--fail \
--location \
-H "Authorization: Bearer $MITTWALD_API_TOKEN" \
https://api.mittwald.de/v2/conversations?fullTextSearch=string&status=open&limit=50&page=1&sort=createdAt&order=asc
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.conversation.listConversations({
"queryParameters": {
"fullTextSearch": "string",
"status": [
"open"
],
"limit": 50,
"page": 1,
"sort": [
"createdAt"
],
"order": [
"asc"
]
}
});
assertStatus(response, 200);
use \Mittwald\ApiClient\Generated\V2\Clients\Conversation\ListConversations\ListConversationsRequest;
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));
$request = (new ListConversationsRequest())
->withFullTextSearch("string")
->withStatus(["open"])
->withLimit(50)
->withPage(1)
->withSort(["createdAt"])
->withOrder(["asc"]);
$response = $client->conversation()->listConversations($request);
var_dump($response->getBody();