Creating a Conversation

The most common action to perform is creating a new "Conversation" record. This entity (the "Conversation") has had numerous names, and is currently identified as the "Session" in the LiveSwitch Contact UI.

The workflow for this is all wrapped up in the "Create Conversation" endpoint (see the Creates a conversation API). There are a few important details here to make sure that your users have a great experience.

📘

Mandatory Requirement

LiveSwitch requires that, when using the Create Conversation endpoint to create a Live call, you must present the "Host Join URL" returned in the call response to the user creating the Conversation.

This link must be presented immediately, in the user interface that was used to create the conversation, and upon successful completion of the call to the Create Conversation endpoint.

First, this endpoint takes either a Contact ID or a Phone number. Generally, it is much simpler to use the Phone number option, because if a Contact doesn't exist for the phone number you specify, one will automatically be created for you.

Second, this endpoint takes an optional Project Code (and some associated information about projects - see the API for details). This links the Conversation record to a "Project" (which is a group of Conversations, along with any data specific to that project) in LiveSwitch Contact, allowing you to create multiple Conversations under a single umbrella. A Project can correspond to whatever you might call it in your platform - a Job, a Move, an Installation, whatever. That way if you have multiple recordings, photos, etc, they can all be stored in one place together.

Third, this endpoint has a "Share the project" option. If you enable this setting, you will get an additional "Project Share URL" and "Project Embedded Share URL" in the response. The important thing to note is that a shared URL does NOT require login to view it. The URL is long (and therefore hard to guess), and can be revoked from the LiveSwitch Contact side, but anyone with the URL can view it. This does, however, mean that you can easily embed and share this URL with anyone, regardless of their login status.

(Note: the only differenced between the "Share" and "Embedded Share" is that the embedded version removes the left and top nav bars from the share UI).

Fourth, and perhaps most importantly, when you create a Conversation of type "Live Conversation", there is a Host Join URL returned to you. You MUST present this URL upon successful completion of the "Create Conversation" to your users so they can join the meeting immediately.