Get started

This guide describes how to get started with the Call Score API.

Before you start

Before you use the API, you must generate an access token. For more information, see Authenticate
The transcript needs to be at least 50 words or longer in order to qualify for call-score processing

Process a conversation

Use the Async API to process a recorded text, audio, or video conversation. You can use following attributes to use Call Score behavior for your business use case.

For additional Async API settings, see the API reference documentation.

features: Enable callScore and insights features to generate the call score.

{
    "features": {
        "featureList": ["callScore", "insights"]
    }
}

metadata: Provide additional context about a call such as sales stage to customize call score algorithm. When setting salesStage, the value must be lowercase. You can choose salesStage as qualification, discovery, demo, negotiation, and general.

{
    "metadata": {
        "salesStage": "qualification",
        "prospectName": "DeepMind AI" 
    }
}

conversationType: Set as sales for sales calls and general for other types of calls.

{
    "conversationType": "sales"
}

Process text conversation

Request

POST https://api.symbl.ai/v1/process/text

{
    "name": "My text conversation",
    "conversationType": "general",
    "features": {
        "featureList": [
            "insights",
            "callScore"
        ]
    },
    "metadata": {
        "salesStage": "qualification",
        "prospectName": "DeepMind AI"
    },
    "messages": [
        {
            "duration": {
                "startTime": "2023-07-20T16:04:19.99Z",
                "endTime": "2023-07-20T16:04:20.99Z"
            },
            "payload": {
                "content": "Hi, this is a live demo that we are trying to give very we are going to show how the platform detects various insights can do transcription in real-time and also the different topics of discussions, which would be generated after the call is over, and they will be an email that will be sent to the inbox.",
                "contentType": "text/plain"
            },
            "from": {
                "name": "John",
                "userId": "[email protected]"
            }
        }
    ]
}

Response

{
    "jobId": "bb3d5e45-d9a6-46e4-b593-10cb24a2b7bf",
    "conversationId": "6089504127713280"
}

Process an audio sales conversation using an URL

Request

POST https://api.symbl.ai/v1/process/audio/url

{
    "name": "Use cases discovery call",
    "conversationType": "sales"
    "features": {
        "featureList": ["insights", "callScore"]
    },
    "metadata": {
        "salesStage": "Discovery",
        "prospectName": "Wayne Enterprises"
    }
}

Response

{
    "jobId": "bb3d5e45-d9a6-46e4-b593-10cb24a2b7bf",
    "conversationId": "6089504127713280"
}

Process a video conversation by a uploading file

Request

POST https://api.symbl.ai/process/video
POST https://api.symbl.ai/process/video ?name="Charmingdale Sales Meeting" &features={"featureList":["callScore", "insights"]} &conversationType=sales &metadata={"callStage":"general","prospectName":"CharmAI"}

{
    <video file>
}

Response

{
    "jobId": "bb3d5e45-d9a6-46e4-b593-10cb24a2b7bf",
    "conversationId": "6089504127713280"
}

Wait for Call Score to complete

After you have processed the conversation, wait for the callScore job to complete before proceeding.

Request

GET https://api.symbl.ai/v1/conversations/6089504127713280/callscore/status

You can also pass in a webhook in the Async API request to get the call score status, instead of making multiple API calls for call score status. When the status of the processing job is updated, the Call Score Status API sends an HTTP request to the URL that you specify. This is applicable for both Async API and Streaming API

"callScoreWebhookUrl": "https://abc.site/dc3907b1-429a-466a-97e2-2eae00b752da",

Response

{
    "jobId": "24991ace-2f34-442a-83bf-cea6e2f6e338",
    "status": "completed"
}

Process a conversation using Streaming API

You can process a real-time conversation using Streaming API and generate call score once the stream is complete. To get call score after the streaming session is completed, add generate call score action in the streaming API start request.

{
    type: "start_request",
    actions: [
                {
                    name: 'generateCallScore',
                    parameters: {
                        conversationType: "general",
                        salesStage: "general",
                        scorecardId: "5733078868164608",
                        prospectName: "Realtime Call Score",
                        callScoreWebhookUrl: "https://webhook.site/dc3907b1-429a-466a-97e2-2eae00b752da"
                    }
                }
            ]
}

Get Call Score

Request

GET https://api.symbl.ai/v1/conversations/6089504127713280/callscore

Response

{
  "score": 82,
  "summary": "The sales call had some good aspects, but there were areas that could be improved. The representative was able to engage the prospect and discuss the product, but there were some interruptions and the conversation could have been more focused on the prospect's needs. The new context provided additional information about the product and the prospect's interest, which improved the evaluation.",
  "criteria": [
    {
      "name": "Communication and Engagement",
      "score": 75,
      "summary": "The representative engaged in a conversation with the prospect, discussing the product and its features. However, there were some interruptions and the conversation could have been more focused on the prospect's needs. The new context shows the prospect's strong desire to learn about the product and their willingness to schedule a follow-up call.",
      "feedback": {
        "positive": {
          "summary": "The representative was able to engage the prospect in a conversation about the product and its features. The talk times between the representative and the prospect were relatively balanced, and the representative's pace matched the prospect's pace. The prospect's sentiment was very positive."
        },
        "negative": {
          "summary": "The representative interrupted the prospect a few times during the call, and the agenda of the call was not explicitly mentioned in the first 5 minutes."
        }
      }
    },
    {
      "name": "Question Handling",
      "score": 85,
      "summary": "The representative was able to answer most of the prospect's questions and provide information about the product. The new context shows the representative addressing the prospect's questions about pricing and other tools using the product, as well as handling the prospect's request for a follow-up call with the CEO.",
      "feedback": {
        "positive": {
          "summary": "The representative was able to answer all of the prospect's questions and provide information about the product, including addressing questions about pricing and other tools using the product, as well as handling the prospect's request for a follow-up call with the CEO."
        },
        "negative": {
          "summary": "There were no major issues in question handling."
        }
      }
    },
    {
      "name": "Forward Motion",
      "score": 86,
      "summary": "The representative discussed the product and its features with the prospect, and the new context shows the representative suggesting a follow-up call with the CEO to address the prospect's concerns and questions. This demonstrates a clear mention of next steps and alignment with the prospect's needs.",
      "feedback": {
        "positive": {
          "summary": "The representative was able to discuss the product and its features with the prospect and suggested a follow-up call with the CEO to address the prospect's concerns and questions."
        },
        "negative": {
          "summary": "There was no clear mention of next steps or alignment with the prospect's needs earlier in the conversation."
        }
      }
    }
  ]
}