Conversations¶

A conversation represents an instance of one or more active connections communicating together. Conversations are most commonly created by either commanding a connection to join a Conference, or by uploading audio directly. If a Conversation has audio data available, it may be analyzed in various ways using Conversation Processors.

For a further dicussion of what can be done with Conversations, see the related guide.

The Conversation object¶

Conversation objects have the following properties:

Property	Type	Description
Required Properties
conversation_id	string	Unique ID of the conversation.
start_time	string	ISO 8601 formatted date and time.
end_time	string	ISO 8601 formatted date and time.
status	string	The current status of the conversation. See Conversation status strings.
mixed_audio	object	A mixed recording of all speakers in a conversation.
mixed_audio. wav_file	string	A URL of a PCM wave file.
mixed_audio. duration_ms	integer	The duration of the recording in milliseconds.
mixed_audio. snr	float	The signal to noise ratio of the recording. A measure of quality. Higher is better.
mixed_audio. rt60	float	The reverbetion time of the recording. A measure of quality. Normally, lower is better.
channels	list	A list of connections in a conversation, their metadata, and, possibly, audio.
channels[]. start_ms	integer	The time at which this connection joined the conference, measured in milliseconds from `start_time`.
channels[]. end_ms	integer	The time at which this connection left the conference, measured in milliseconds from `start_time`.
channels[]. audio	object	A recording of a single device in a conversation, if available.
channels[]. audio. wave_file	string	A URL of a PCM wave file.
channels[]. audio. duration_ms	integer	The duration of the recording in milliseconds.
channels[]. audio. snr	float	The signal to noise ratio of the recording. A measure of quality. Higher is better.
channels[]. audio. rt60	float	The reverberation time of the recording. A measure of quality. Normally, lower is better.
channels[]. connection	object	The Connection object that produced this channel.
channels[]. connection. type	string	Takes the values “phone” or “voip”.
channels[]. connection. connection_id	string	The unique identifier for the connection. Generated by Sift on connection.
channels[]. connection. from	string	Either the phone_number or webrtc_name of the source of the call, depending the value of type.
channels[]. connection. to	string	The phone_number of the destination of the call, if it is a phone connection, otherwise blank.
Optional Properties
name	string	The name of the conversation. If the conversation was generated from a Conference, it will be the same as the conference name.
topics	list	A list of topics discussed in the conversation. Present if the “find topics” processor has been executed on this conversation.
transcript	object	Link to the transcript of the entire conversation. Is populated if the “transcribe” processor has been executed on this conversation. See Retrieve a transcript
transcript.url	string	The url where the transcript can be accessed.
detected_classes	list	A list of classes describing the conversation, generated from user-trained models. Present if one or more “classify” processors has been executed on this conversation.
detected_classes[]. model	string	The name of the model that generated this class.
detected_classes[]. model. class	string	The name of the class that best describes This conversation according to `model`.
call_grades	object	A series of labelled call metrics related to the quality of the conversations in the call. Call grading can be used to survey human interactions.
processors	list[ string]	List of Conversation Processors bound to this conversation. Includes all processors, regardless of whether they are finished or not.

Conversation status strings¶

The following strings are possible values of the status attribute of a Conversation.

Status	Description
in-progress	The conversation is in progress.
processing	The conversation has ended and the Conversation Processors bound to the conversation are still working.
finished	The conversation has ended and all previously bound Conversation Processors are done working. Note if more processors are bound to the conversation, its status may return to `processing`.

Example¶

{
    "conversation_id": "5d3dc73fc8cf34be",
    "name": "ConferenceRoom",
    "start_time": 2016-05-06T19:22:22Z,
    "end_time": 2016-05-06T19:45:21Z,
    "status": "finished"
    "mixed_audio": {
        "wav_file": "https://api.gridspace.com/media/2561659e6c7a4a21ad14b9b9749facb2/mixed.wav",
        "duration_ms": 135928,
        "snr": 21.5,
        "rt60": 0.6
    },
    "channels": [
        {
            "start_ms": 0,
            "end_ms": 131223,
            "connection": {
                "connection_id": c458af9f15eb429e,
                "type": "phone",
                "from": "+15553332222",
                "to": "+15552215568"
            },
            "audio": {
                "wav_file": "https://api.gridspace.com/media/34abea156b964feab8073fbbe96bd661.wav",
                "duration_ms": 131223,
                "snr": 22.7,
                "rt60": 0.4
            }
        },
        {
            "start_ms": 21440,
            "end_ms": 135928,
            "connection": {
                "connection_id": c458af9f15eb429e,
                "type": "phone",
                "from": "+15558978888",
                "to": "+15552215568"
            },
            "audio": {
                "wav_file": "https://api.gridspace.com/media/596655cdc4ea48b4a05d12d89050c606.wav",
                "duration_ms": 114488,
                "snr": 14.0,
                "rt60": 1.7
            }
        }
    ],
    "processors": ["transcribe", "findtopics", "classify:calltype"],
    "topics": ["service", "internet", "problem"],
    "transcript": {
        "url": "https://api.gridspace.com/v0/conversations/e71d54b31fa24691/transcript"
    },
    "detected_classes": [
        {
            "calltype": "notworking"
        }
    ]
}

Conversation Event Callback¶

Sent to a user-specified URL when an event related to a particular conversation occurs. For details on how these are used, see the corresponding guide.

Request¶

method:	`POST`
content-type:	`application/json`

The body of the request contains a single JSON-encoded Conversation Event. Inspect the event_type property to find out which type of event it is.

Response¶

The response body should be empty.

List conversations¶

Retrieve a list of all conversation objects associated with your account.

Request¶

url:	`https://api.gridspace.com/v0/conversations`
method:	`GET`

URL parameters¶

The following query string parameters are accepted:

Field	Allowed values	Description
status	Conversation status strings	Return only Conversations with the given status.

Response¶

Returns a paginated list of Conversations. See Paginated Results for details. Each entry in the results list is an abridged Conversation object with the following attributes included.

Property	Type	Description
Required Properties
conversation_id	string	ID of the conversation
start_time	string	ISO 8601 formatted date and time.
status	string	The current status of the conversation. See Conversation status strings.
Optional Properties
conference_name	string	The name of the conference, if the conversation happened in a conference. Optional.
end_time	string	If the status not `in-progress`, the date and time that the conversation ended as an ISO 8601-formatted datetime.

Example¶

{
    "previous": null,
    "next": "https://api.gridspace.com/v0/conversations?cursor=cE0yMDE2LTA1LTE5KzAxJTNBNDklM0E1MS4xODQ5NjElMkIwMCUzQTAw",
    "results": [
        {
            "conversation_id": "5d3dc73fc8cf34be",
            "start_time": 2016-05-06T19:22:22Z,
            "status": "in-progress"
        },
        {
            "conversation_id": "5d3dc73fc8cf34be",
            "start_time": 2016-05-06T19:22:22Z,
            "end_time": 2016-05-06T19:45:21Z,
            "status": "processing"
        },
        {
            "conversation_id": "5d3dc73fc8cf34be",
            "start_time": 2016-05-06T19:22:22Z,
            "end_time": 2016-05-06T19:45:21Z,
            "status": "processing"
        }
        ...
    ]
}

Retrieve a conversation¶

Retrieve the details of a conversation between two or more parties.

Request¶

url:	`https://api.gridspace.com/v0/conversations/:conversation_id`
method:	`GET`

Response¶

The response body contains a JSON formatted Conversation object.

Create a conversation¶

Create a new conversation using existing audio from another source.

Request¶

url:	`https://api.gridspace.com/v0/conversations`
method:	`POST`
content-type:	`application/json`

The request body should be a JSON object that provides metadata about the conversation and a media ID pointing to the audio of the conversation.

Property	Type	Description
Required Properties
audio_id	string	Audio ID of a previously updated audio file.
Optional Properties
start_time	string	The date that the conversation occurred, if available.
name	string	String name for the conversation. Will be stored in the `name` attribute of the Conversation object.
processors	list[string]	A list of Conversation Processors to bind to the conversation. If provided, the Conversation will enter the `processing` state immediately.
event_callback	string	A URL to receive Conversation Event Callback requests for this conversation. Note that since the conversation is already finished, only the `done_processing` event can be triggered.

Example¶

{
    "audio_id": "1e69aedecbe2d013"
    "start_time": 2016-05-06T19:22:22Z,
    "name": "5/12 Product Meeting",
    "processors": ["transcribe", "findtopics"],
    "event_callback": "http://mysite.com/callbacks/conversations"
}

Response¶

If successful, the response body will contain the new Conversation object.

Process a conversation¶

Bind a set of Conversation Processors to an existing Conversation. If new processors are bound, the Conversation’s status will immediately change to processing and the new processors will start executing.

Request¶

url:	`https://api.gridspace.com/v0/conversations/:conversation_id`
method:	`POST`
content-type:	`application/json`

The request body should be a JSON object with the following properties:

Property	Type	Description
Required Properties
processors	list[string]	A list of Conversation Processors to bind to the conversation.

Example¶

{
    "processors": ["transcribe", "find-topics", "classify:businessunit"],
}

Retrieve a transcript¶

Get the transcript for any conversation which has the live_transcripts flag enabled or has been post-processed with the Transcribe processor.

Request¶

url:	`https://api.gridspace.com/v0/conversations/:conversation_id/transcript`
method:	`GET`

URL parameters¶

The following query string parameters are accepted:

Field	Allowed values	Description
start_after	integer	Index of the first segment to return.
wait_secs	integer	Number of seconds to wait for a matching segment before returning.

Response¶

Returns a json object with the following properties:

Property	Type	Description
transcript	list	A list of transcribed segments. Each segment is roughly a “turn” of dialogue.
transcript[]. offset_ms	integer	Time in milliseconds from the start of the conversation that the current segment was spoken.
transcript[]. duration_ms	integer	Duration in milliseconds of the current segment of the transcript.
transcript[]. transcript	string	Text transcript of the voice segment.
transcript[]. pretty_transcript	string	A version of the text transcript with punctuation and capitalization.
transcript[]. index	number	Order of the segment in the transcript
transcript[]. channel	number	The index of the conversation channel that was speaking.

Example¶

{
    "transcript": [
        {
            "pretty_transcript": "Hello, thank you for calling.",
            "transcript": "hello thank you for calling",
            "offset_ms": 0,
            "index": 1,
            "channel": 0
        },
        {
            "pretty_transcript": "Thanks how are you.",
            "transcript": "thanks how are you",
            "offset_ms": 25124,
            "index": 2,
            "channel": 1
        }
    ]
}