Creates a conversation.

post

https://public-api.production.liveswitch.com/v1/conversations

Required scope: conversations.write

Recent Requests

Log in to see full request history

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

DTO for Conversation create request

contactId

uuid | null

The ID of the Contact record this Conversation will be associated with; if set and valid, the phone number will be ignored.
If set and invalid, throws an error. If the contact exists, it will NOT be updated.

phone

string | null

The Phone of the Contact record this Conversation will be associated with; if set, the phone number will be looked up
and if a Contact exists with that number, that Contact will be utilized. If the phone number does NOT exist, a new
contact will be created using the specified number. If the contact exists, it will NOT be updated.

email

string | null

The Email of the Contact record this Conversation will be associated with if it is created.

firstName

string | null

The FirstName of the Contact record this Conversation will be associated with if it is created.

lastName

string | null

The LastName of the Contact record this Conversation will be associated with if it is created.

message

string | null

The contents of the text message the user will receive. For Scheduled conversations, omit this field to
use the organization's configured scheduled-call template, which resolves ${user}, ${organization},
${day}, ${date}, ${time}, ${timezone}, and ${scheduledDate}. If provided, the message is sent as-is
and placeholders are not resolved.

notes

string | null

Notes to save on the Conversation.

name

string | null

Optional name/title for the conversation. For StartRecording, this becomes the session name.
For TakePhotos, this becomes the photo session name.

type

string

enum

required

Represents the type of Conversation

Allowed:

tags

array of strings | null

Optional. Array of tag names to assign to the project. Tags will be auto-created if they don't exist.

tags

autoStartRecording

boolean

This only applies to LiveConversation

sendSmsNotification

boolean

When set to true, the user is sent a text message invite to the Conversation.
Only applies to LiveConversation, RecordingRequest, and Scheduled types; ignored for StartRecording, TakePhotos,
and Uploads.

sendEmailNotification

boolean

When set to true, the user is sent an email invite/reminder to the Conversation. Requires Email or ContactId to be set.
Email invite/reminder delivery also requires Allow Email Invitations to be enabled in organization settings.
Only applies to LiveConversation, RecordingRequest, and Scheduled types; ignored for StartRecording, TakePhotos, and Uploads.

assignedUserId

uuid | null

Optional. The user to assign the conversation to.

startAt

date-time | null

Required when Type is Scheduled. The scheduled start date/time in UTC.

endAt

date-time | null

Optional when Type is Scheduled. The scheduled end date/time in UTC.

timezone

string | null

Optional IANA timezone used for scheduled reminder text formatting. If omitted, the organization's default
timezone is used.

projectId

string | null

Optional. The id of a project to associate the conversation with. If specified, will link
this session into the specified project. If this value is provided then ProjectExternalId will be ignored.

projectExternalId

string | null

Optional. The external id of a project to associate this conversation with. If specified, will link
this session into the specified project. See LiveSwitch.Integration.Api.Models.v1.Conversation.ConversationCreateRequestDto.ProjectAutoCreate for more.

projectAutoCreate

boolean

Optional, default false. If this value is true, and no project with the specified ProjectExternalId exists,
a project will be created using the ProjectExternalId and ProjectName.
If this value is true, ProjectExternalId is required.
If this value is false, and the ProjectExternalId is specified but does not
exist, the request will fail and no data will be modified.

projectName

string | null

Optional, default empty. Only used if ProjectAutoCreate is true, and no project with a matching
ProjectExternalId was found. If not specified, will auto-generate a name
using the pattern "Project [project external id]". Note that project names must be unique.

attributes

array of objects | null

Optional attributes to set on the conversation. Use either attributeId or attributeGroupName+attributeName.

attributes

guidedInstructionId

string | null

Optional. The ID of the guided instructions to apply to the conversation.
Use an ID returned by GET /v1/guided-instructions.
Supported conversation types are RecordingRequest, StartRecording, and TakePhotos.
When provided it must be a valid GUID; an empty or whitespace value is ignored (treated as no guided instruction).

Response

Language

Credentials

OAuth2

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json