Creating a Conversation

A common action is to create a new Conversation record. This entity has several previous names. The LiveSwitch UI calls it a "Session". This page uses Conversation for this entity.

The "Create Conversation" endpoint provides this workflow. See the Creates a conversation API. The details below explain the options and requirements.

📘

Mandatory Requirement

For a Live call, LiveSwitch requires the user who creates the Conversation to receive the "Host Join URL" from the response.

The interface where the user creates the Conversation must display this link immediately after the "Create Conversation" request succeeds.

First, this endpoint accepts either a Contact ID or a Phone number. The Phone number option is usually simpler. If no Contact exists for that phone number, LiveSwitch automatically creates one.

Second, this endpoint accepts an optional Project Code and related Project information. See the API for details. The Project Code links the Conversation record to a Project in LiveSwitch. A Project groups Conversations and data specific to that Project. You can create multiple Conversations in one Project.

A Project can correspond to a Job, Move, Installation, or another concept in your platform. A Project can keep multiple recordings and photos together in one place.

Third, if the Conversation is in a Project, the response includes the Project's share URLs: "projectShareUrl" and "projectEmbeddedShareUrl". Every Project has these URLs as soon as it exists. Anyone with the URL can view the Project, read-only, without a login. The URL is long and difficult to guess.

(Note: The "Embedded Share" version removes the left and top navigation bars from the share UI. This is the only difference from the "Share" version.)

Fourth, the response includes a Host Join URL when you create a Conversation of type "Live Conversation". After the "Create Conversation" request succeeds, immediately display this URL to your users. They can use it to join the meeting immediately.