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 list Full transcript of the entire conversation. Present if the “transcribe” processor has been executed on this conversation. Provided as a chronologically ordered list of segments, each attributed to a single speaker.
transcript[].
connection_id
string The connection within the conversation that said this line of the transcript.
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[].
text
string Text transcript of the voice segment.
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": [
        {
            "connection_id": "c458af9f15eb429e",
            "offset_ms": 1004,
            "duration_ms": 5500,
            "text": "thank you for calling internet company how can i help you"
        },
        {
            "connection_id": "c458af9f15eb429e",
            "offset_ms": 7201,
            "duration_ms": 2119,
            "text": "yes i am calling to report a problem with my internet"
        }
        ...
    ]
    "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 URL or media ID pointing to the audio of the conversation.

Property Type Description
Required Properties
audio_url string URL of an audio recording of the conversation.
audio_id string Audio ID of a previously updated audio file. Eactly one of audio_url or audio_id must be present.
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"],
}