Get Protocol by Slug

Get Protocol by Slug

The getProtocolBySlug query allows you to retrieve the current state, metadata, speakers, and summaries of an existing protocol.

This query is used to:

• check the current creating step of the protocol,
• check whether the protocol has finished processing,
• retrieve speaker information,
• retrieve summary text and
• use this information for the renameSpeakerInTextsegment mutation.

Understanding the status Field

Every protocol includes a boolean status field:

• status = false → processing is still running
• status = true → processing is finished, and all final data is available

Use this field to determine whether your application should:

• show a loading/progress screen, or
• continue to the next step

GraphQL Query

fragment protocolDetails on ApiProtocolType {
  slug
  name
  status
  date
  language
  empty
  creatingStep
}

fragment speakerDetails on ApiSpeakerType {
  slug
  gender
  familyName
  givenName
  party
  preTitle
  postTitle
  posShort
  posLong
  systemId
}

fragment summaryPerSpeakerDetails on ApiSummaryPerSpeakerItemTypeWithSpeaker {
  speakerObj {
    ...speakerDetails
  }
  textList
  speakerSuggestion
}

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

Example JS Code

Below is a minimal example showing how to fetch the protocol and check whether it’s finished processing:

import axios from "axios";

export const GET_PROTOCOL_BY_SLUG = `
  fragment protocolDetails on ApiProtocolType {
    slug
    name
    status
    date
    language
    empty
    creatingStep
  }

  fragment speakerDetails on ApiSpeakerType {
    slug
    gender
    familyName
    givenName
    party
    preTitle
    postTitle
    posShort
    posLong
    systemId
  }

  fragment summaryPerSpeakerDetails on ApiSummaryPerSpeakerItemTypeWithSpeaker {
    speakerObj {
      ...speakerDetails
    }
    textList
    speakerSuggestion
  }

  query GetProtocolBySlug($protocolSlug: String!) {
    getProtocolBySlug(protocolSlug: $protocolSlug) {
      protocol {
        ...protocolDetails
      }
      speakerList
      summaryPerSpeakerList {
        ...summaryPerSpeakerDetails
      }
    }
  }
`;

const fetchProtocol = async (protocolSlug) => {
  try {
    const response = await axios({
      method: "POST",
      url: "https://api-v2.speechmind.com/external/v2/graphql",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.VUE_APP_API_KEY,
      },
      data: JSON.stringify({
        query: GET_PROTOCOL_BY_SLUG,
        variables: { protocolSlug },
      }),
    });

    const data = response.data.data.getProtocolBySlug;

    console.log("Protocol:", data.protocol);
    console.log("Speakers:", data.speakerList);
    console.log("Summary per speaker:", data.summaryPerSpeakerList);

    if (data.protocol.status === true) {
      console.log("✔️ Processing completed!");
    } else {
      console.log("⏳ Still processing...");
    }
  } catch (error) {
    console.error("Error fetching protocol:", error);
  }
};

fetchProtocol("your-protocol-slug");

Using speakerList & summaryPerSpeakerList for Renaming Speakers

Once your protocol has finished processing (status = true), the speakerList and summaryPerSpeakerList provide the structured data you need to identify and rename speakers in your text segments.

1. Understanding the Data

• speakerList Contains all speakers along with their spoken segments and timing information:

{
  "SPEAKER_SLUG": {
    "duration": 61.05,
    "textsegment": [
      { "id": 328124, "time": { "start_time": 13.2, "end_time": 18.88 }, "text": "…", "textsegment_duration": 5.68 }
    ],
    "speaker_obj": {
      "slug": "SPEAKER_SLUG",
      "givenName": "Thomas",
      "familyName": "Müller",
      "preTitle": "",
      "postTitle": "",
      "gender": "m"
    }
  }
}

• summaryPerSpeakerList Provides aggregated summaries and suggested names for each speaker:

[
  {
    "speakerObj": {
      "slug": "SPEAKER_SLUG",
      "givenName": "Thomas",
      "familyName": "Müller"
    },
    "textList": "{\"0\": [\"Summary text...\"]}",
    "speakerSuggestion": "[\"Herr Müller\"]"
  }
]

2. Preparing for renameSpeakerInTextsegment You can use these objects to:

• Map speaker slugs to their current givenName / familyName
• Determine suggested names from speakerSuggestion
• use speakerList.textsegment list for passing the user the audio time for listening to a current audio position and the text to identify the speaker by voice or text
• summaryPerSpeakerList.speakerSuggenstion provides a AI generated suggestions who this speaker is based on the audio data

3. Example flow

// Example: Build mapping for renaming
const speakerMap = {};
Object.values(data.speakerList).forEach(speakerItem => {
  speakerMap[speakerItem.speaker_obj.slug] = {
    currentName: `${speakerItem.speaker_obj.givenName} ${speakerItem.speaker_obj.familyName}`,
    suggestedNames: []
  };
});

// Fill suggested names from summary
data.summaryPerSpeakerList.forEach(summaryItem => {
  const slug = summaryItem.speakerObj.slug;
  if (speakerMap[slug]) {
    speakerMap[slug].suggestedNames = JSON.parse(summaryItem.speakerSuggestion);
  }
});

console.log("Speaker rename mapping:", speakerMap);

4. Next step Once you have your speakerMap, you can call the renameSpeakerInTextsegment mutation.

Have questions?

Still have questions? Talk to support.