Receive entities from conversations

Process video file

Before getting entities, you need to process your conversation. The code in this example is from the Process video page. If you want to use an audio or text file, you can use the code from Process audio or Process text.

You can use the default video file, or you can replace it with any other publicly available video URL.

Note that you must wait for the job to finish processing before generating Conversation Intelligence. If you make a request from the Conversations API while the job is processing, you might receive incomplete insights. You can find out if a job is still processing by passing the jobId in the Get job status request.

Authentication

Before using this API, you must generate your authentication token (AUTH_TOKEN) as described in Authentication.

Example request

curl "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID/entities" \
    -H "Authorization: Bearer $AUTH_TOKEN"

const request = require('request');
const authToken = AUTH_TOKEN;
const conversationId = CONVERSATION_ID;

request.get({
    url: `https://api.symbl.ai/v1/conversations/${conversationId}/entities`,
    headers: { 'Authorization': `Bearer ${authToken}` },
    json: true
}, (err, response, body) => {
    console.log(body);
});

import requests

baseUrl = "https://api.symbl.ai/v1/conversations/{conversationId}/entities"
conversationId = 'your_conversation_id'  # Generated using Submit text end point

url = baseUrl.format(conversationId=conversationId)

# set your access token here. See https://docs.symbl.ai/docs/developer-tools/authentication
access_token = 'your_access_token'

headers = {
    'Authorization': 'Bearer ' + access_token,
    'Content-Type': 'application/json'
}

responses = {
    401: 'Unauthorized. Please generate a new access token.',
    404: 'The conversation and/or it\'s metadata you asked could not be found, please check the input provided',
    500: 'Something went wrong! Please contact [email protected]'
}

response = requests.request("GET", url, headers=headers)

if response.status_code == 200:
    # Successful API execution
    print("entities => " + str(response.json()['entities']))  # List of entity object containing type, value, text, messageRefs, customType (if a custom entity)
elif response.status_code in responses.keys():
    print(responses[response.status_code])  # Expected error occurred
else:
    print("Unexpected error occurred. Please contact [email protected]" + ", Debug Message => " + str(response.text))

exit()

Example response

{
  "type": "custom",
  "customType": "Company Executives",
  "value": "marketing director",
  "text": "marketing director",
  "messageRefs": [
    {
      "id": "5118221462011904",
      "text": "The marketing director is out-of-town due to some work.",
      "offset": 4
    }
  ]
}

{
  "type": "person",
  "value": "jamie smith",
  "text": "jamie smith",
  "messageRefs": [
    {
      "id": "5979280332816384",
      "text": "The name is Jamie Smith.",
      "offset": 12
    }
  ]
}

{
  "type": "organization",
  "value": "Vodafone",
  "text": "Vodafone",
  "messageRefs": [
    {
      "id": "6141473464516608",
      "text": "Hello, this is Peter from Vodafone, I help you today.",
      "offset": 26
    }
  ]
}

{
  "type": "date",
  "value": "2020-07-15",
  "text": "today",
  "messageRefs": [
    {
      "id": "6141473464516608",
      "text": "Hello, this is Peter from Vodafone, I help you today.",
      "offset": 47
    },
    {
      "id": "4603163403354112",
      "text": "Being a loyal customer at the three types of plan options that I can offer you today.",
      "offset": 79
    },
    {
      "id": "5936512994639872",
      "text": "Is there anything else I may assist you with today?",
      "offset": 45
    }
  ]
}

{
  "type": "number",
  "value": "two",
  "text": "two",
  "messageRefs": [
    {
      "id": "6137109238775808",
      "text": "What do you two think of that?",
      "offset": 12
    }
  ]
}

For a full reference of the response fields, see Get entities.

Generate more insights

In addition to analytics, you can use the Conversations API to:

Get topics
Topics provide a quick overview of the key things that were talked about in the conversation.
Get action items
An action item is a specific outcome recognized in the conversation that requires one or more people in the conversation to take a specific action, such as set up a meeting, share a file, or complete a task.
Get follow-ups
This is a category of action items with an associated follow-up request or a task. The follow-up could be sending an email, making a phone call, or setting up a meeting.