Free Sign Up

PUT Text API

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


The PUT Async Text API allows you to process any text payload to append the transcription of the previous conversation.

It can be useful in cases where you have new information like chats, emails or messages which keep generating for single entity. Using this API, you can add all the new entity data to the existing Conversation ID (conversationId).

:::info
If there are multiple requests are submitted for the same Conversation ID, all the requests will be processed synchronously in order to maintain the order of the requests for the conversation.
:::

Authentication #

Before using this API, you must generate your authentication token (AUTH_TOKEN). To learn how to get the authentication token, see the Authentication page.

API Endpoint #

PUT https://api.symbl.ai/v1/process/text/:conversationId

Example API Call #

<Tabs
defaultValue="cURL"
values={[
{ label: 'cURL', value: 'cURL', },
{ label: 'Native Javascript', value: 'javascript', },
{ label: 'Node.js', value: 'nodejs', },
{ label: 'Python', value: 'python' }
]
}>

curl --location --request PUT "https://api.symbl.ai/v1/process/text/$CONVERSATION_ID" \
--header "Authorization: Bearer $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
  "detectPhrases": "true",
  "messages": [
    {
      "payload": {
        "content": "Hi Mike, Natalia here. Hope you don’t mind me reaching out. Who would be the best possible person to discuss internships and student recruitment at ABC Corp? Would you mind pointing me toward the right person and the best way to reach them? Thanks in advance for your help, I really appreciate it!"
      },
      "from": {
        "userId": "natalia@example.com",
        "name": "Natalia"
      },
      "duration":{
        "startTime":"2020-07-21T16:02:19.01Z",
        "endTime":"2020-07-21T16:04:19.99Z"
      }
    },
    {
      "payload": {
        "content": "Hey Natalia, thanks for reaching out. I am connecting you with Steve who handles recruitments for us."
      },
      "from": {
        "userId": "mike@abccorp.com",
        "name": "Mike"
      },
      "duration":{
        "startTime":"2020-07-21T16:04:19.99Z",
        "endTime":"2020-07-21T16:04:20.99Z"
      }
    }
  ]
}'
const authToken = AUTH_TOKEN;
const conversationId = CONVERSATION_ID;

const payload = {
  "customEntities": [{"customType": "Hiring Process", "text": "internships"}],
  "detectPhrases":true,
  "messages": [
    {
      "payload": {
        "content": "Hi Mike, Natalia here. Hope you don’t mind me reaching out. Who would be the best possible person to discuss internships and student recruitment at ABC Corp? Would you mind pointing me toward the right person and the best way to reach them? Thanks in advance for your help, I really appreciate it!"
      },
      "from": {
        "userId": "natalia@example.com",
        "name": "Natalia"
      },
      "duration":{
        "startTime":"2020-07-21T16:02:19.01Z",
        "endTime":"2020-07-21T16:04:19.99Z"
      }
    },
    {
      "payload": {
        "content": "Hey Natalia, thanks for reaching out. I am connecting you with Steve who handles recruitments for us."
      },
      "from": {
        "userId": "mike@abccorp.com",
        "name": "Mike"
      },
      "duration":{
        "startTime":"2020-07-21T16:04:19.99Z",
        "endTime":"2020-07-21T16:04:20.99Z"
      }
    }
  ],
  "confidenceThreshold": 0.5
}

const responses = {
  400: 'Bad Request! Please refer docs for correct input fields.',
  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',
  429: 'Maximum number of concurrent jobs reached. Please wait for some requests to complete.',
  500: 'Something went wrong! Please contact support@symbl.ai'
}

const fetchData = {
  method: "PUT",
  headers: {
    'Authorization': `Bearer ${authToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
}

fetch(`https://api.symbl.ai/v1/process/text/${conversationId}`, fetchData).then(response => {
  if (response.ok) {
    return response.json();
  } else {
    throw new Error(responses[response.status]);
  }
}).then(response => {
  console.log('response', response);
}).catch(error => {
  console.error(error);
});
const request = require('request');
const conversationId = CONVERSATION_ID;
const authToken = AUTH_TOKEN;

const options = {
  'method': 'PUT',
  'url': `https://api.symbl.ai/v1/process/text/${conversationId}`,
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${authToken}`
  },
  'body': JSON.stringify({
    "customEntities": [{"customType": "Hiring Process", "text": "internships"}],
    "detectPhrases":true,
    "messages": [
      {
        "payload": {
          "content": "Hi Mike, Natalia here. Hope you don’t mind me reaching out. Who would be the best possible person to discuss internships and student recruitment at ABC Corp? Would you mind pointing me toward the right person and the best way to reach them? Thanks in advance for your help, I really appreciate it!"
        },
        "from": {
          "userId": "natalia@example.com",
          "name": "Natalia"
        },
        "duration":{
          "startTime":"2020-07-21T16:02:19.01Z",
          "endTime":"2020-07-21T16:04:19.99Z"
        }
      },
      {
        "payload": {
          "content": "Hey Natalia, thanks for reaching out. I am connecting you with Steve who handles recruitments for us."
        },
        "from": {
          "userId": "mike@abccorp.com",
          "name": "Mike"
        },
        "duration":{
          "startTime":"2020-07-21T16:04:19.99Z",
          "endTime":"2020-07-21T16:04:20.99Z"
        }
      }
    ],
    "confidenceThreshold": 0.5
  })
};

request(options, function (error, response) {
  if (err) throw new Error(error);
  console.log(response.body);
});
import requests
import json

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

url = baseUrl + conversationId

payload = {
    "name": "Business Meeting",  # <Optional,String| your_meeting_name by default conversationId>

    "confidenceThreshold": 0.6,  # <Optional,double| Minimum required confidence for the insight to be recognized. Value ranges between 0.0 to 1.0. Default value is 0.5.>

    "detectPhrases": true,  # <Optional,boolean| It shows Actionable Phrases in each sentence of conversation. These sentences can be found using the Conversation's Messages API. Default value is false.>
    "messages": [
        {
            "payload": {
                "content": "Hi Mike, Natalia here. Hope you don’t mind me reaching out. Who would be the best possible person to discuss internships and student recruitment at ABC Corp? Would you mind pointing me toward the right person and the best way to reach them? Thanks in advance for your help, I really appreciate it!"
            },
            "from": {
                "userId": "natalia@example.com",
                "name": "Natalia"
            },
            "duration": {
                "startTime": "2020-07-21T16:02:19.01Z",
                "endTime": "2020-07-21T16:04:19.99Z"
            }
        },
        {
            "payload": {
                "content": "Hey Natalia, thanks for reaching out. I am connecting you with Steve who handles recruitments for us."
            },
            "from": {
                "userId": "mike@abccorp.com",
                "name": "Mike"
            },
            "duration": {
                "startTime": "2020-07-21T16:04:19.99Z",
                "endTime": "2020-07-21T16:04:20.99Z"
            }
        }
    ]
}

# 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'
}

# webhookUrl = "https://yourdomain.com/jobs/callback",  #<Optional, string| your_webhook_url| Webhook url on which job updates to be sent. (This should be post API)>
# if webhookUrl is not None:
#   url += "?webhookUrl=" + webhookUrl

responses = {
    400: 'Bad Request! Please refer docs for correct input fields.',
    401: 'Unauthorized. Please generate a new access token.',
    404: 'conversation and/or it\'s metadata you asked could not be found, please check the input provided',
    429: 'Maximum number of concurrent jobs reached. Please wait for some requests to complete.',
    500: 'Something went wrong! Please contact support@symbl.ai'
}

response = requests.request("PUT", url, headers=headers, data=json.dumps(payload), params=json.dumps(params)))

if response.status_code == 201:
    # Successful API execution
    print("conversationId => " + response.json()['conversationId'])  # ID to be used with Conversation API.
    print("jobId => " + response.json()['jobId'])  # ID to be used with Job API.
elif response.status_code in responses.keys():
    print(responses[response.status_code])  # Expected error occurred
else:
    print("Unexpected error occurred. Please contact support@symbl.ai" + ", Debug Message => " + str(response.text))

exit()

Request Headers #

Header Name Required Value
Authorization Mandatory Bearer <token> The token you get from our authentication process.
Content-Type Mandatory application/json
x-api-key Optional DEPRECATED. The JWT token you get from our authentication process.

Path Parameter #

Parameter Value
conversationId Conversation ID from the POST Async Text API response.

Request Body #

{
  "name": "Afternoon Business Meeting",
  "detectPhrases": true,
  "confidenceThreshold": 0.6,
  "entities": [
    {
      "customType": "Company Executives",
      "value": "Marketing director",
      "text": "Marketing director"
    }
  ],
  "detectEntities": true,
  "messages": [],
  "trackers": [
    {
      "name": "Promotion Mention",
      "vocabulary": [
        "We have a special promotion going on if you book this before",
        "I can offer you a discount of 10 20 percent you being a new customer for us",
        "We have our month special this month",
        "We have a sale right now on"
      ]
    }
  ]
}

Request Body Parameters #

Field Required Type Description
name Optional String Your meeting name. Default name set to conversationId.
messages Mandatory List Input Messages to look for insights. See the messages section below for more details.
confidenceThreshold Optional Double Minimum confidence score that you can set for an API to consider it as a valid insight (action items, follow-ups, topics, and questions). It should be in the range <=0.5 to <=1.0 (i.e., greater than or equal to 0.5 and less than or equal to 1.0.). The default value is 0.5.
detectPhrases Optional Boolean It shows Actionable Phrases in each sentence of a conversation. These sentences can be found using the Conversation's Messages API. The default value is false.
entities Optional List Input custom entities which can be detected in your conversation using Entities API.
detectEntities Optional Boolean Default value is false. If not set the Entities API will not return any entities from the conversation.
trackers BETA Optional String A tracker entity containing name and vocabulary (a list of key words and/or phrases to be tracked). Read more in theTracker API section.
enableAllTrackers BETA Optional Boolean Default value is false. Setting this parameter to true will enable detection of all the Trackers maintained for your account by the Management API.This will allow Symbl to detect all the available Trackers in a specific Conversation. Learn about this parameter here.
enableSummary ALPHA Optional Boolean Setting this parameter to true allows you to generate Summaries using Summary API. Ensure that you use https://api.symbl.ai/ as the base URL.
webhookUrl Optional String Webhook URL on which job updates to be sent. This should be post API. See Webhook section below.

messages #

Code Example #
{ 
  "messages": [{
    "payload": {
      "content": "Hi Mike, Natalia here. Hope you don’t mind me reaching out. Who would be the best possible person to discuss internships and student recruitment at ABC Corp? Would you mind pointing me toward the right person and the best way to reach them? Thanks in advance for your help, I really appreciate it!"
    },
    "from": {
      "userId": "natalia@example.com",
      "name": "Natalia"
    },
    "duration":{
      "startTime":"2020-07-21T16:02:19.01Z",
      "endTime":"2020-07-21T16:04:19.99Z"
    }
  }, {
    "payload": {
      "content": "Hey Natalia, thanks for reaching out. I am connecting you with Steve who handles recruitments for us."
    },
    "from": {
      "userId": "mike@abccorp.com",
      "name": "Mike"
    },
    "duration":{
      "startTime":"2020-07-21T16:04:19.99Z",
      "endTime":"2020-07-21T16:04:20.99Z"
    }
  }]
}
Field Required Type Description
payload Mandatory Object Input Messages to look for insights. See the payload section below for more details.
from Optional Object Information about the User information produced the content of this message.
duration Optional Object Duration object containing startTime and endTime for the transcript.

payload #

Field Required Type Default Description
content Mandatory String The text content that you want the API to parse.
Code Example #
{
  "payload": {
    "content": "Hi Mike, Natalia here. Hope you don’t mind me reaching out. Who would be the best possible person to discuss internships and student recruitment at ABC Corp? Would you mind pointing me toward the right person and the best way to reach them? Thanks in advance for your help, I really appreciate it!"
  }
}

from(user) #

Field Required Type Description
name Optional String Name of the user.
userId Optional String A unique identifier of the user. E-mail ID is usually a preferred identifier for the user.
Code Example #
{
  "from": {
    "userId": "mike@abccorp.com",
    "name": "Mike"
  }
}

duration #

Field Required Type Description
StartTime Optional DateTime The start time for the particular text content.
endTime Optional DateTime The end time for the particular text content.
Code Example #
{
  "duration": {
    "startTime":"2020-07-21T16:04:19.99Z",
    "endTime":"2020-07-21T16:04:20.99Z"
  }
}

webhookURL #

webhookUrl will be used to send the status of job created. Every time the status of the job changes it will be notified on the webhookUrl.

webhook Payload #

Field Description
jobId ID to be used with Job API.
status Current status of the job. (Valid statuses: [ scheduled, in_progress, completed ])
Code Example #
{
  "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "in_progress"
}

Response #

{
  "conversationId": "5815170693595136",
  "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Response object #

Field Description
conversationId ID to be used with Conversation API.
jobId ID to be used with Job API.

API Limit Error #

{
  "statusCode" : 429,
  "message" : "This API has a limit of maximum of `X` number of concurrent jobs per account. If you are looking to scale, and need more concurrent jobs than this limit, please contact us at support@symbl.ai"
}

Here, the value of X can be found in FAQ.

:::caution
You must wait for the job to complete processing before you proceed with getting the Conversation Intelligence. If you immediately make a GET request to Conversation API, it is possible that you'll receive incomplete insights. Therefore, ensure that you wait for the job to complete.
:::