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.

Parameter

Data Type

Description

Default Value

limit

Integer (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

offset

Integer (int16)

Specifies a non-negative number of items to skip before applying the limit.

0

order

String / enum

Specifies 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

startTime

String / ISO 8601 date format

Specifies 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')

endTime

String / ISO 8601 date format

Specifies 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()

sort

String

Specifies one or more fields to be used to sort the results.

conversation.startTime

filter

String / RSQL format

Specifies 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.

Field

Description

conversations

A 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.

Field

Description

id

The unique conversation identifier.

type

The conversation type. Default value is meeting.

name

The name of the conversation.

startTime

DateTime value of when the conversation started.

endTime

DateTime value of when the conversation ended.

members

A list of member objects containing ID, name and email (if detected).

metadata

Contains 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 (Beta).

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.

Field

Description

id

The unique conversation identifier.

metadata

An 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.

Field

Description

message

Specifies if the conversation was successfully deleted.

Example response

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

Did this page help you?