Protocol Retrieval (Current)

✅ Current Implementation: This page contains the latest recommended approach for protocol retrieval using the enhanced speakerObj structure. For legacy documentation, see Protocol Retrieval (Legacy).

API v2 Endpoint

All examples in this documentation use the new API v2 endpoint:

 https://api-v2.speechmind.com/external/v2/graphql

After importing the Audio file to the server, next steps are given below:

• Fetch a protocol using getProtocolBySlug query
• If the protocol is not found, an error message is returned.
• If the protocol status is true, it is editable.

When editable, two key parameters are populated:

• summaryPerSpeakerList (now with enhanced speakerObj)
• speakerList

Current getProtocolBySlug Query

export const GET_PROTOCOL_BY_SLUG = `
  fragment protocolDetails on ApiProtocolType {
    slug
    name
    status
    editStage
    date
    bucketAws
  }

  query GetProtocolBySlug($protocolSlug: String!){
    getProtocolBySlug(protocolSlug:$protocolSlug){
      protocol{
        ...protocolDetails
      }

      speakerList 
      
      summaryPerSpeakerList {
        createdAt
        updatedAt
        speakerObj {
          slug
          gender
          givenName
          familyName
          party
          preTitel
          postTitel
          posShort
          posLong
          specialCase
        }
        speakerSuggestion
        textList
      }
    }
  }
`;

Example JavaScript Implementation

import axios from "axios";

async function getProtocolBySlug(protocolSlug) {
  const dataObj = {
    query: GET_PROTOCOL_BY_SLUG,
    variables: {
      protocolSlug: protocolSlug,
    },
  };

  return await axios({
    method: "post",
    url: process.env.VUE_APP_GRAPHQL_API,
    data: JSON.stringify(dataObj),
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.VUE_APP_API_KEY,
    },
  })
    .then((response) => {
      const responseData = response.data.data.getProtocolBySlug;
      return responseData 
    })
    .catch((error) => {
      console.log(error);
    })
}

Example Response Structure

The getProtocolBySlug query returns a response with the enhanced speakerObj structure:

{
  "data": {
    "getProtocolBySlug": {
      "protocol": {
        "slug": "abc123xyz789example",
        "name": "Weekly Team Meeting - Example",
        "status": true,
        "editStage": true,
        "date": "2024-03-15",
        "bucketAws": "{\"bucket\": \"example-audio-bucket\", \"Key\": \"abc123xyz789example.mp3\", \"video\": \"\"}"
      },
      "speakerList": {
        "mX9z2K4pR7qL8nE1bF5j": {
          "speaker_name": {
            "givenName": "Alice",
            "familyName": "Johnson",
            "gender": "f",
            "party": null,
            "preTitel": null,
            "postTitel": null,
            "specialCase": false,
            "posShort": null,
            "posLong": null
          },
          "duration": 45.32,
          "textsegment": [
            {
              "id": 101,
              "time": {
                "start_time": 5.20,
                "end_time": 12.80
              },
              "text": "Good morning everyone. Let's start with the project updates from last week.",
              "textsegment_duration": 7.60
            }
          ]
        }
      },
      "summaryPerSpeakerList": [
        {
          "createdAt": "2024-03-15T09:30:15.123456+00:00",
          "updatedAt": "2024-03-15T10:15:22.789012+00:00",
          "speakerObj": {
            "slug": "pQ8v3N6wY9sH2kD4fG7x",
            "gender": "m",
            "givenName": "Bob",
            "familyName": "Smith",
            "party": null,
            "preTitel": "Dr.",
            "postTitel": null,
            "posShort": "PM",
            "posLong": "Project Manager",
            "specialCase": false
          },
          "speakerSuggestion": "[\"Robert\", \"Bobby\"]",
          "textList": "{\"0\": [\"Speaker demonstrates leadership qualities and provides clear project updates.\"], \"1\": [\"Effectively manages team coordination and communicates milestones.\"]}"
        }
      ]
    }
  }
}

Benefits of the Enhanced Structure

The new speakerObj provides:

• Structured Data: Speaker information is now properly structured instead of a simple string
• Detailed Name Components: Access to givenName, familyName, preTitel, postTitel separately
• Rich Metadata: Gender, party affiliation, and position information
• Unique Identifiers: Each speaker has a unique slug for reliable identification
• Better Integration: Enhanced data consistency across the entire API
• Improved Performance: More efficient speaker matching and processing

Working with Speaker Objects

Here are common patterns for working with the new speakerObj:

// Get display name for UI
function getDisplayName(speakerObj) {
  return `${speakerObj.givenName} ${speakerObj.familyName}`;
}

// Check if speaker has specific role
function hasPosition(speakerObj) {
  return speakerObj.posLong || speakerObj.posShort;
}

// Format speaker information for display
function formatSpeakerInfo(speakerObj) {
  const name = getFullSpeakerName(speakerObj);
  const position = speakerObj.posLong || speakerObj.posShort || 'No position';
  const party = speakerObj.party || 'Independent';
  
  return `${name} - ${position} (${party})`;
}

These parameters are crucial for identifying speakers for the initial renaming process — a key step to ensure the quality of the resulting document. The enhanced speakerObj structure provides much richer data for accurate speaker identification and better document processing.

📚 Legacy Documentation

If you need to reference the old implementation for migration purposes, see:

Legacy Protocol Retrieval Documentation →

Have questions?

Still have questions? Talk to support.