Uploading transcriptions and chat data to QueueMetrics

You can upload transcriptions and chat conversations to QueueMetrics via an HTTP/HTTPS web service. This allows you to store conversation data (e.g. call transcriptions, chat logs, WhatsApp messages) and retrieve it later.

The service is located at transcription.do relative to the base QM URL; so if QM’s main URL is at https://my.queuemetrics-live/somecustomer, the web service will appear at https://my.queuemetrics-live/somecustomer/transcription.do.

The endpoint accepts both GET and POST requests. The payload is expressed as a JSON structure in the single parameter named data. When using GET, the data parameter must be URL-encoded.

Authentication and keys

The user must have the key ROBOT and one or both of the following keys:

  • CHAT_WRITE - required to insert or append data

  • CHAT_READ - required to read data back

In general, writers do not need read access, as the typical use case is a one-way upload from an external system.

Response format

If all goes well, the response will be a JSON object with HTTP status 200:

{
  "response": "ok"
}

or, for read operations:

{
  "response": "ok",
  "transcript": { ... }
}

An error is indicated by either:

  • A JSON response with "response": "error" and a "message" field describing the problem

  • A non-JSON response

  • An HTTP status code other than 200

Data model

A transcription contains:

  • An external ID (id) that uniquely identifies the conversation

  • A type (type): one of Transcription, Chat, or WhatsApp

  • Zero or more segments, each representing a single utterance or message

A transcription has the following fields:

Field Required Description

id

Yes

Unique external ID for this conversation

type

Yes

One of Transcription, Chat, or WhatsApp

action

Yes

One of insert, append, or read

driverId

No

Identifier of the source system (default: empty)

fileName

No

Original file name, if applicable

startedAt

No

Start date/time in format yyyy-MM-dd.HH:mm:ss. This is in the same time zone as QM is.

lang

No

Language code (e.g. it, en)

status

Yes

One of ok, error (transcription failed), or skip (intentionally not transcribed).

segments

Yes

Array of segments (see below)

Each segment has then the following fields:

Field Required Description

id

Yes

Unique external segment ID

speaker

Yes

Speaker name (must not be empty)

startMs

One of

Start time in milliseconds from the beginning of the call. Mutually exclusive with startAt.

startAt

One of

Absolute timestamp of the segment, in the server’s local timezone. Format: yyyy-MM-dd.HH:mm:ss or yyyy-MM-dd.HH:mm:ss.SSS. The stored value is the delta from the call’s startedAt. Must not precede the call start. Mutually exclusive with startMs.

text

Yes

Segment text content, or URL to external contents (eg video, audio)

mimeType

No

MIME type for the segment (default: text/plain)

prob

No

Confidence score for audio transcription, 0-100 (default: 100)

A minimal segment therefore looks like:

{
  "id": "seg004",
  "speaker": "Zeb",
  "startMs": 160,
  "text": "Hello there"
}

This implies prob=100 and mimeType="text/plain".

Typical workflows

There are two main ways to upload data:

Upload a complete transcription at once

If you have the full transcription available, insert it in a single call with all segments:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcription.do \
  -G --data-urlencode 'data={
    "action": "insert",
    "id": "call-001",
    "type": "Transcription",
    "driverId": "pbx1",
    "fileName": "call-001.wav",
    "startedAt": "2026-04-10.14:26:24",
    "lang": "it",
    "status": "ok",
    "segments": [
      {
        "id": "s1",
        "speaker": "Agent",
        "startMs": 100,
        "text": "Hello! How can I help you?"
      },
      {
        "id": "s2",
        "speaker": "Customer",
        "startMs": 3500,
        "text": "I am missing an invoice"
      }
    ]
  }'

Create a chat and append segments incrementally

This is useful for live chats or streaming transcriptions, where segments arrive over time.

First, create the chat with zero or one segment:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcription.do \
  -G --data-urlencode 'data={
    "action": "insert",
    "id": "chat-055",
    "type": "Chat",
    "driverId": "",
    "fileName": "",
    "startedAt": "2026-04-10.15:00:00",
    "lang": "en",
    "status": "ok",
    "segments": [
      {
        "id": "m1",
        "speaker": "Alice",
        "startMs": 0,
        "text": "Hello!"
      }
    ]
  }'

Then append new segments as they arrive:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcription.do \
  -G --data-urlencode 'data={
    "action": "append",
    "id": "chat-055",
    "type": "Chat",
    "segments": [
      {
        "id": "m2",
        "speaker": "Bob",
        "startMs": 5000,
        "text": "Hi Alice, how can I help?"
      }
    ]
  }'

You can append multiple times, as needed, pushing one or more segments at a time.

Each segment ID must be unique within the chat. Attempting to append a segment with an ID that already exists will result in an error.

Service reference

Insert

Creates a new transcription with all its segments.

Keys required: CHAT_WRITE and ROBOT

Input:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcription.do \
  -G --data-urlencode 'data={
    "action": "insert",
    "id": "yyy12",
    "type": "Chat",
    "driverId": "zebra",
    "fileName": "test.txt",
    "startedAt": "2026-04-10.14:26:24",
    "lang": "it",
    "status": "ok",
    "segments": [
      {
        "id": "seg001",
        "speaker": "Alice",
        "startMs": 100,
        "mimeType": "text/plain",
        "text": "Ciao",
        "prob": 95
      },
      {
        "id": "seg002",
        "speaker": "Bob",
        "startMs": 200,
        "mimeType": "text/plain",
        "text": "Buongiorno",
        "prob": 90
      }
    ]
  }'

Output:

{
  "response": "ok"
}

An error is returned if a valid chat with the same id and type already exists, or segments are malformed.

Append

Adds segments to an existing chat.

Keys required: CHAT_WRITE and ROBOT

Input:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcription.do \
  -G --data-urlencode 'data={
    "action": "append",
    "id": "yyy12",
    "type": "Chat",
    "segments": [
      {
        "id": "seg003",
        "speaker": "Alice",
        "startMs": 150,
        "mimeType": "text/plain",
        "text": "Ciao",
        "prob": 95
      }
    ]
  }'

Output:

{
  "response": "ok"
}

An error is returned if no valid chat with the given id and type exists.

Read

Retrieves a transcription with all its current segments, ordered by start time.

Keys required: CHAT_READ and ROBOT

Input:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcription.do \
  -G --data-urlencode 'data={
    "action": "read",
    "id": "xxx1234",
    "type": "Chat"
  }'

Output:

{
  "response": "ok",
  "transcript": {
    "id": "xxx1234",
    "type": "Chat",
    "driverId": "zebra",
    "fileName": "test.txt",
    "startedAt": "2026-04-10.14:26:24",
    "lang": "en",
    "status": "ok",
    "segments": [
      {
        "id": "seg001",
        "speaker": "Alice",
        "startMs": 100,
        "mimeType": "text/plain",
        "text": "Hello",
        "prob": 95
      },
      {
        "id": "seg002",
        "speaker": "Bob",
        "startMs": 200,
        "mimeType": "text/plain",
        "text": "Goodbye",
        "prob": 90
      }
    ]
  }
}

If the chat is not found, an empty transcript object is returned.

Delete

Deletes (soft-delete) an existing chat or transcription.

This is a separate endpoint, located at transcriptionDelete.do relative to the base QM URL, but it follows the same authentication model as the rest of this page.

Keys required: CHAT_DELETE and ROBOT

Input:

curl -v --user transcripts:trans \
  http://localhost:8080/qm/transcriptionDelete.do \
  -G --data-urlencode 'parameters={
    "uniqueId": "xxx1234",
    "type": "Chat"
  }'

Output:

Unlike the other services on this page, the response is wrapped in the standard QM envelope (status, runTimeMs, srvTime, message):

{
  "status": "OK",
  "runTimeMs": 4,
  "srvTime": 1787660237991,
  "message": ""
}

An error ("status": "ERROR", with message describing the problem) is returned if no valid chat with the given uniqueId and type exists (this includes a chat that was already deleted).

For a type of Transcription, deleting the chat also clears QM’s record that the underlying audio file was transcribed. If that file is still present when the Uniloader (or any transcription client) next starts up, it will be transcribed again.