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:

• Get a list of your conversations.
• Get information about a specific conversation.
• Update the metadata for a conversation.
• Delete a conversation.

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:

• <ACCESS_TOKEN> is a valid API access token.

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.

Response

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

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:

• <ACCESS_TOKEN> is a valid API access token.
• <CONVERSATION_ID> is the ID of a conversation that you previously processed.

For additional reference information, see Get Conversation by ID.

Response

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

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.

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:

• <ACCESS_TOKEN> is a valid API access token.
• <CONVERSATION_ID> is the ID of a conversation that you previously processed.

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

Response

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

Example response

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