Get a support conversation

GET/conversations/{conversationId}/

API version

v2

Request method

GET

Operation ID

conversation-get-conversation

---

Request

• conversationIdstring (uuid)

  required

Responses

Format

application/json

Description

The metadata of the conversation. Does not contain messages send in the conversation. Use /v2/conversations/{conversationId}/messages to get the messages.

Schema documentation

• categoryobject
  • categoryIdstring (uuid)

    required
  • namestring

    required
  • referenceTypearray of string (one of: unspecified, server, project, organisation, extensionInstance)

    required
    • Array[
    • *string (one of: unspecified, server, project, organisation, extensionInstance)
    ]

conversationIdstring (uuid)

required

createdAtstring (date-time)

required

createdByobject

• activeboolean
• avatarRefIdstring
• clearNamestring
• departmentstring (one of: development, mail, accounting, cloudHosting, customerService, generic)
• userIdstring

  required

lastMessageobject

• createdAtstring (date-time)

  required
• createdByobject
  • activeboolean
  • avatarRefIdstring
  • clearNamestring
  • departmentstring (one of: development, mail, accounting, cloudHosting, customerService, generic)
  • userIdstring

    required

lastMessageAtstring (date-time)

lastMessageByobject

• activeboolean
• avatarRefIdstring
• clearNamestring
• departmentstring (one of: development, mail, accounting, cloudHosting, customerService, generic)
• userIdstring

  required

mainUserobject

required

• activeboolean
• avatarRefIdstring
• clearNamestring
• departmentstring (one of: development, mail, accounting, cloudHosting, customerService, generic)
• userIdstring

  required

notificationRolesarray of string (one of: customer_owner, customer_accountant, customer_member, project_owner, project_email_admin, project_external)

• Array[
• *string (one of: customer_owner, customer_accountant, customer_member, project_owner, project_email_admin, project_external)
]

relatedToone of 6 alternatives

relationsarray of object

• Array[
• *object
  • aggregatestring

    required
  • domainstring

    required
  • idstring

    required
]

sharedWithone of 4 alternatives

shortIdstring

required

statusstring (one of: open, closed, answered, inProgress, waiting)

required

titlestring

required

visibilitystring (one of: shared, private)

required

Example

{
  "category": {
    "categoryId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "name": "string",
    "referenceType": [
      "unspecified"
    ]
  },
  "conversationId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "createdAt": "2024-12-21T00:27:27.731Z",
  "createdBy": {
    "active": true,
    "avatarRefId": "string",
    "clearName": "string",
    "department": "development",
    "userId": "string"
  },
  "lastMessage": {
    "createdAt": "2024-12-21T00:27:27.731Z",
    "createdBy": {
      "active": true,
      "avatarRefId": "string",
      "clearName": "string",
      "department": "development",
      "userId": "string"
    }
  },
  "lastMessageAt": "2024-12-21T00:27:27.731Z",
  "lastMessageBy": {
    "active": true,
    "avatarRefId": "string",
    "clearName": "string",
    "department": "development",
    "userId": "string"
  },
  "mainUser": {
    "active": true,
    "avatarRefId": "string",
    "clearName": "string",
    "department": "development",
    "userId": "string"
  },
  "notificationRoles": [
    "customer_owner"
  ],
  "relatedTo": {
    "aggregate": "user",
    "domain": "user",
    "id": "string"
  },
  "relations": [
    {
      "aggregate": "string",
      "domain": "string",
      "id": "string"
    }
  ],
  "sharedWith": {
    "aggregate": "user",
    "domain": "user",
    "id": "string"
  },
  "shortId": "string",
  "status": "open",
  "title": "string",
  "visibility": "shared"
}

JSON Schema

{
  "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"
    },
    "createdBy": {
      "properties": {
        "active": {
          "type": "boolean"
        },
        "avatarRefId": {
          "type": "string"
        },
        "clearName": {
          "type": "string"
        },
        "department": {
          "enum": [
            "development",
            "mail",
            "accounting",
            "cloudHosting",
            "customerService",
            "generic"
          ],
          "type": "string"
        },
        "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"
            },
            "department": {
              "enum": [
                "development",
                "mail",
                "accounting",
                "cloudHosting",
                "customerService",
                "generic"
              ],
              "type": "string"
            },
            "userId": {
              "type": "string"
            }
          },
          "required": [
            "userId"
          ],
          "type": "object"
        }
      },
      "required": [
        "createdAt"
      ],
      "type": "object"
    },
    "lastMessageAt": {
      "format": "date-time",
      "type": "string"
    },
    "lastMessageBy": {
      "properties": {
        "active": {
          "type": "boolean"
        },
        "avatarRefId": {
          "type": "string"
        },
        "clearName": {
          "type": "string"
        },
        "department": {
          "enum": [
            "development",
            "mail",
            "accounting",
            "cloudHosting",
            "customerService",
            "generic"
          ],
          "type": "string"
        },
        "userId": {
          "type": "string"
        }
      },
      "required": [
        "userId"
      ],
      "type": "object"
    },
    "mainUser": {
      "properties": {
        "active": {
          "type": "boolean"
        },
        "avatarRefId": {
          "type": "string"
        },
        "clearName": {
          "type": "string"
        },
        "department": {
          "enum": [
            "development",
            "mail",
            "accounting",
            "cloudHosting",
            "customerService",
            "generic"
          ],
          "type": "string"
        },
        "userId": {
          "type": "string"
        }
      },
      "required": [
        "userId"
      ],
      "type": "object"
    },
    "notificationRoles": {
      "items": {
        "enum": [
          "customer_owner",
          "customer_accountant",
          "customer_member",
          "project_owner",
          "project_email_admin",
          "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"
        }
      ]
    },
    "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"
}

Usage examples

cURL

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/conversations/f0f86186-0a5a-45b2-aa33-502777496347

JavaScript SDK

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.getConversation({
  "conversationId": "f0f86186-0a5a-45b2-aa33-502777496347"
});

assertStatus(response, 200);
  

PHP SDK

use \Mittwald\ApiClient\Generated\V2\Clients\Conversation\GetConversation\GetConversationRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new GetConversationRequest(
  conversationId: "f0f86186-0a5a-45b2-aa33-502777496347"
));
$response = $client->conversation()->getConversation($request);

var_dump($response->getBody();