--- updatedAt: 2026-06-18T12:14:42.000Z agentTools: projectIndex: https://developer.liveswitch.com/llms.txt --- # Gets a conversation by ID. **Required scope:** `conversations` # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "LiveSwitch Public API", "version": "v1" }, "servers": [ { "url": "https://public-api.production.liveswitch.com/", "description": "Public API" } ], "paths": { "/v1/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Gets a conversation by ID.", "description": "**Required scope:** `conversations`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } } }, "security": [ { "oauth2": [ "conversations" ] } ] } } }, "components": { "schemas": { "ContactDto": { "type": "object", "properties": { "id": { "type": "string", "description": "This is the contact's system wide unique identifier", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationId to which the Contact belongs", "format": "uuid", "nullable": true }, "firstName": { "type": "string", "description": "This is the contact's first name, an optional field", "nullable": true }, "lastName": { "type": "string", "description": "This is the contact's last name, an optional field", "nullable": true }, "email": { "type": "string", "description": "This is the contact's email, an optional field", "nullable": true }, "phone": { "type": "string", "description": "This is the contact's phone, an optional field", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeResponseDto" }, "description": "Attributes assigned to this contact", "nullable": true } }, "additionalProperties": false }, "ConversationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Conversation", "format": "uuid" }, "type": { "type": "string", "description": "Represents the type of Conversation. Values are LiveConversation, RecordingRequest, StartRecording, TakePhotos, or Uploads", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationID that owns this Conversation", "format": "uuid", "nullable": true }, "hostJoinUrl": { "type": "string", "description": "The conversation URL the host will use to join and take notes, screenshots, etc.\r\nFor StartRecording, TakePhotos, and Uploads types, this will be null.", "nullable": true }, "participantJoinUrl": { "type": "string", "description": "The conversation URL the participant will use.\r\nFor StartRecording and TakePhotos types, this will be the URL for the user to start their own recording or photo session.\r\nFor Uploads types, this will be null. Use the documents API to upload files to the conversation.", "nullable": true }, "conversationUrl": { "type": "string", "description": "The conversation URL that an authenticated admin user can use to review the recording, notes, etc.", "nullable": true }, "embeddedConversationUrl": { "type": "string", "description": "The conversation URL that an authenticated admin user can use to review the recording, notes, etc, without a header or navigation bar.", "nullable": true }, "projectShareUrl": { "type": "string", "description": "The URL that an un-authenticated user can use to review the recording, notes, etc. This URL will be blank if the project is not shared.", "nullable": true }, "projectUrl": { "type": "string", "description": "The URL that an authenticated user can use to review the recording, notes, etc.", "nullable": true }, "projectEmbeddedUrl": { "type": "string", "description": "The URL that an authenticated user can use to review the recording, notes, etc, without any header/nav bar/etc.", "nullable": true }, "projectEmbeddedShareUrl": { "type": "string", "description": "The URL that an un-authenticated user can use to review the recording, notes, etc, without any header/nav bar/etc. This URL will be blank if the project is not shared.", "nullable": true }, "projectId": { "type": "string", "description": "The project identifier, if there is one, associated with this Conversation.", "nullable": true }, "assignedUserId": { "type": "string", "description": "The ID of the LiveSwitch user assigned to this Conversation, or null when unassigned.", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the conversation was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the conversation was last updated", "format": "date-time" }, "startAt": { "type": "string", "description": "The scheduled start date/time for scheduled conversations, or null for non-scheduled conversations.", "format": "date-time", "nullable": true }, "endAt": { "type": "string", "description": "The scheduled end date/time for scheduled conversations, or null for non-scheduled conversations.", "format": "date-time", "nullable": true }, "name": { "type": "string", "description": "The name of the conversation", "nullable": true }, "contactId": { "type": "string", "description": "The ID of the Contact record associated with this Conversation", "nullable": true }, "status": { "type": "string", "description": "The Status of the Conversation. Useful when listening for updates via Webhooks, tracking the \"ReadyForReview\" state meaning\r\nat least one recording is available. Note that this Status may occur multiple times if multiple recordings are created for this Conversation.", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this project", "nullable": true }, "qrCodeId": { "type": "string", "description": "The ID of the QR code that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "kioskId": { "type": "string", "description": "The ID of the Kiosk that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "formId": { "type": "string", "description": "The ID of the Form that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "formSubmissionId": { "type": "string", "description": "The ID of the Form Submission that was used to create this conversation, or null. Note that a given Form can be submitted multiple times, each creating a new FormSubmission.", "format": "uuid", "nullable": true }, "contact": { "$ref": "#/components/schemas/ContactDto" }, "createdByEmail": { "type": "string", "description": "The email address of the user who created this Conversation", "nullable": true }, "notes": { "type": "string", "description": "Notes associated with this Conversation", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeResponseDto" }, "description": "Attributes assigned to this conversation", "nullable": true } }, "additionalProperties": false }, "EntityAttributeResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of this entity attribute instance.", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The organization ID.", "format": "uuid", "nullable": true }, "attributeId": { "type": "string", "description": "The attribute definition ID.", "format": "uuid", "nullable": true }, "attributeName": { "type": "string", "description": "The attribute definition name.", "nullable": true }, "entityId": { "type": "string", "description": "The entity ID this attribute is attached to.", "format": "uuid", "nullable": true }, "title": { "type": "string", "description": "Optional title/display text (for link attributes, this is the link text).", "nullable": true }, "value": { "maxLength": 255, "type": "string", "description": "The attribute value.", "nullable": true }, "createdAt": { "type": "string", "description": "Timestamp when created.", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Timestamp when updated.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "The value of the attribute added for an entity (response without group details)" }, "TagDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Tag.", "format": "uuid" }, "name": { "type": "string", "description": "The string value for display.", "nullable": true }, "hexColor": { "type": "string", "description": "The hex-based color value for display. Useful if you want to match the color in your application to LiveSwitch.", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth2 authentication using Auth0 Implicit flow", "flows": { "implicit": { "authorizationUrl": "https://id.staging.liveswitch.com/authorize", "scopes": { "openid": "OpenID Connect scope", "profile": "Access to user profile", "email": "Access to user email", "me": "Access to user information", "contacts": "Read access to contacts", "contacts.write": "Write access to contacts", "conversations": "Read access to conversations", "conversations.write": "Write access to conversations", "organizations": "Read access to organizations", "webhooks": "Read access to webhooks", "webhooks.write": "Write access to webhooks", "applications": "Read access to applications", "applications.write": "Write access to applications", "forms": "Read access to forms", "projects": "Read access to projects", "projects.write": "Write access to projects", "recordings": "Read access to recordings", "documents": "Read access to documents", "accounts": "Read access to accounts", "guided-instructions": "Read access to guided instructions", "sparks": "Read access to Spark runs", "sparks.write": "Write access to Spark runs", "spark-templates": "Read access to installed Spark templates for the organization", "scribe-templates": "Read access to installed Scribe templates (legacy)" } } } }, "bearer": { "type": "http", "description": "

Please enter a valid token. This shoud NOT include the Bearer: prefix, but just the token itself.

\n
\n

To generate a token from the Swagger UI:

\n

\n 1. Select the 'v1/tokens' endpoint in the Swagger UI
\n 2. Set the 'redirect' setting to false
\n 3. Fill in the values according to your application configuration
\n 4. Click 'Execute'
\n

\n
\n

\n The response from this request will include the URL you need to generate a token. Copy/paste it into a new window and follow the instructions.\n

", "scheme": "bearer", "bearerFormat": "JWT" } } }, "security": [ { "bearer": [] } ] } ``` # Sibling pages * [Creates a conversation.](https://developer.liveswitch.com/reference/post_v1-conversations.md) * [Retrieves a list of conversations.](https://developer.liveswitch.com/reference/get_v1-conversations.md) * [Creates presigned URLs for uploading images to a conversation](https://developer.liveswitch.com/reference/post_v1-conversations-id-upload-urls-images.md) * [Creates presigned URLs for uploading documents to a conversation](https://developer.liveswitch.com/reference/post_v1-conversations-id-upload-urls-documents.md) * [Creates presigned URLs for uploading videos to a conversation](https://developer.liveswitch.com/reference/post_v1-conversations-id-upload-urls-videos.md) * [Updates a conversation.](https://developer.liveswitch.com/reference/put_v1-conversations-id.md) * [Run a Spark on a conversation](https://developer.liveswitch.com/reference/post_v1-conversations-conversationid-sparks.md) * [Gets all Sparks by conversation ID](https://developer.liveswitch.com/reference/get_v1-conversations-conversationid-sparks.md)