Manage conversations

As you work with the Symbl.ai APIs, you may need to perform various operations to manage your conversations. This page describes how to:

Authentication

These requests require an access token, as described in Authenticate.


Get all conversations

This request returns a list of your conversations. By default, up to 20 conversations are returned. You can use the optional query parameters to filter and change the number of results.

To get a list of your conversations, use the GET <https://api.symbl.ai/v1/conversations> operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"

curl --request GET \
  --url "https://api.symbl.ai/v1/conversations" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

For additional reference information, see Get all Conversations.

Optional query parameters

The following table describes the optional query parameters that can be used with this request.

ParameterData TypeDescriptionDefault Value
limitInteger (int16)Specifies a non-negative integer count, to indicate that no more than count items in the result will be returned. limit set to 0 returns 0 items in the result.

Value must be between 0 to 65536.
20
offsetInteger (int16)Specifies a non-negative number of items to skip before applying the limit.0
orderString / enumSpecifies the order in which the results should be sorted. By default, the order is based on the startTime field of the associated conversation.

Valid values are asc and desc.
asc
startTimeString / ISO 8601 date formatSpecifies the start of the datetime range for the results to be returned. This startTime is associated with the startTime field of the associated conversation. If the startTime parameter is not included, then startTime is calculated as startTime = endTime - duration('7 days').

Valid values are ISO 8601 formatted strings with value less than current timestamp and less than endTime.
startTime = endTime - duration('7 days')
endTimeString / ISO 8601 date formatSpecifies the end of the datetime range for the results to be returned. This endTime is associated with the endTime field of the associated conversation. If endTime is not included, then the current date and time is used as endTime automatically.

Valid values are ISO 8601 formatted strings with value less than current timestamp and greater than startTime.
endTime = currentDatetime()
sortStringSpecifies one or more fields to be used to sort the results.conversation.startTime
filterString / RSQL formatSpecifies a filter string in RSQL format to filter the results.


  • Filter parameter should be a valid RSQL string however it can't have OR logical Operator.

  • Filter parameter can not have more than 2 parameters in its filters. There is no limit on filters though, so user can add any number of filters using maximum of two parameters.

conversation.startDate <= {currentTimestamp - 7 days}

Response

The following table describes the response body that is returned by this request.

FieldDescription
conversationsA list of conversations. For the response fields specific to conversations, see Get Conversation.

Example response

{
  "conversations": [
    {
      "id": "4866329603473408",
      "type": "meeting",
      "name": "John / Mary Brainstorming",
      "startTime": "2021-02-27T15:53:05.594Z",
      "endTime": "2021-02-27T16:18:05.048Z",
      "members": [
        {
          "name": "John",
          "email": "[email protected]"
        },
        {
          "name": "Mary",
          "email": "[email protected]"
        }
      ],
      "metadata": {
        "key": "value", 
        "agentId": "johndoe"
      }
    },
    {
      "id": "4931769134481408",
      "type": "meeting",
      "name": "John / Mary Catch up",
      "startTime": "2021-02-24T15:53:05.594Z",
      "endTime": "2021-02-24T16:18:05.048Z",
      "members": [],
      "metadata": {
        "agentId": "johndoe"
      }
    },
    {
      "id": "6866329803473407",
      "type": "meeting",
      "name": "John / Acme Corp Meeting",
      "startTime": "2021-02-27T15:53:05.594Z",
      "endTime": "2021-02-27T16:18:05.048Z",
      "members": [],
      "metadata": {
        "customerId": "889988999", 
        "agentId": "johndoe"
      }
    }
  ]
}

Get conversation

This request returns conversation data such as the meeting name, member names and emails, start and end time of the meeting, meeting type, meeting ID, and any custom conversation metadata that you added.

To get information about a specific conversation, use the GET <https://api.symbl.ai/v1/conversations/{conversationId}> operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
CONVERSATION_ID="<CONVERSATION_ID>"

curl --request GET \
  --url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

For additional reference information, see Get Conversation by ID.

Response

The following table describes the response body that is returned by this request.

FieldDescription
idThe unique conversation identifier.
typeThe conversation type. Default value is meeting.
nameThe name of the conversation.
startTimeDateTime value of when the conversation started.
endTimeDateTime value of when the conversation ended.
membersA list of member objects containing ID, name and email (if detected).
metadataContains user-defined metadata key-value pairs which are used for labeling conversations and including conversations in conversation groups.

Example response

{
  "id": "4866329603473408",
  "type": "meeting",
  "name": "John / Mary Brainstorming",
  "startTime": "2021-02-27T15:53:05.594Z",
  "endTime": "2021-02-27T16:18:05.048Z",
  "members": [
    {
      "name": "John",
      "email": "[email protected]"
    },
    {
      "name": "Mary",
      "email": "[email protected]"
    }
  ],
  "metadata": {
    "key": "value", 
    "agentId": "johndoe"
  }
}

Update conversation metadata

This request adds or updates conversation metadata. Conversation metadata is a collection of custom key-value pairs that you can use to label the conversation. Conversation metadata is also used to include conversations in Conversation Groups.

To get update the metadata for a conversation, use the PUT <https://api.symbl.ai/v1/conversations/{conversationId}> operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
CONVERSATION_ID="<CONVERSATION_ID>"

curl --request PUT \
  --url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "metadata": {
      "exampleKey": "exampleValue", 
      "exampleKey2": "exampleValue2"
    }
  }'

Where:

  • <ACCESS_TOKEN> is a valid API access token.
  • <CONVERSATION_ID> is the ID of a conversation that you previously processed.
  • The metadata object is a collection of key-value pairs that you specify. Metadata must meet the following criteria:
    • The value of the metadata field must be of type string.
    • The maximum length of the string value allowed is 128 characters.
    • Duplicate fields are not allowed in metadata.

For additional reference information, see Update a Conversation.

Response

The following table describes the response body that is returned by this request.

FieldDescription
idThe unique conversation identifier.
metadataAn object that contains the custom key-value pairs that you specified in the request.

Example response

{
   "id":"4931769134481408",
   "metadata":{
      "key":"value",
      "agentId":"johndoe"
   }
}

Delete conversation

This request deletes a conversation and all data directly associated with the conversation ID, such as messages, action items, topics, the summary, and more. When you delete a conversation, it cannot be recovered and the conversation ID will no longer work with requests.

To delete a conversation, use the DELETE <https://api.symbl.ai/v1/conversations/{conversationId}> operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
CONVERSATION_ID="<CONVERSATION_ID>"

curl --request DELETE \
  --url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

For additional reference information, see Delete a Conversation by ID.

Response

The following table describes the response body that is returned by this request.

FieldDescription
messageSpecifies if the conversation was successfully deleted.

Example response

{
    "message": "successfully deleted the conversation"
}