Run voice test turn — Brigg developers

Access & visibility

Allow voice.RunVoiceTestTurn on your API key.

Acting member required. Send Brigg-Act-As with an approved member account ID. The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

test_idstringRequired

Keep the returned test_id for this temporary session. Expired sessions require a new test. voice.StartVoiceTest.

At least 1 character.

utterancestringRequired

What the caller says.

At least 1 character.

historyarray of objectOptional

Earlier caller and assistant lines, oldest first. Omit or use [] for the first turn. Send accumulated conversation on later turns; the current utterance belongs only in utterance, not duplicated here.

Default: [].

Item fields

rolestringRequired

Conversation speaker: caller is the simulated customer; agent is the assistant. This is not a workspace permission or member role.

Allowed: "caller", "agent".

textstringRequired

The words spoken by this participant, in conversation order.

turn_idstringRequired

Client-chosen identifier unique to one logical turn within this test. Keep it and the HTTP idempotency key unchanged when retrying that same utterance/history; choose new values for the next turn.

At least 1 character.

Inspect a test turn

Send each new caller utterance with the prior conversation, and append the returned text as an agent line for the next turn. A typed test does not require the audio socket. Keep the same approved member throughout the session.

A trace entry currently includes capabilityId, source, label, kind, result and durationMs. These are optional diagnostics within an open JSON value, not stable fields to build business logic around. The result can report success, refusal, failure or uncertainty; inspect it instead of treating HTTP 200 or plausible reply text as success. Ignore unfamiliar diagnostic properties. The test simulates changes rather than performing the corresponding customer action, but model work can consume workspace credit.

Use Review voice test with the complete transcript for feedback. Its review can be empty when no feedback was generated; that is not proof of a flawless assistant. End the test when finished. An expired, unknown or differently owned test requires a fresh session.

Run a conversation test

Start a test for the intended inbox and retain its test_id. Text clients can use Run voice test turn; an audio connection URL is only needed for an audio client. Keep temporary connection URLs secret.

Pass the simulated caller's utterance and previous conversation history in order. Keep a stable turn_id for a retried turn. Review the returned reply and capability trace; a simulated response is not evidence that a real customer call succeeded. Review voice test accepts the conversation transcript for feedback. End the session when finished; an expired session needs a new start.

Response

Returns 200 OK with a JSON body.

textstringRequired

Assistant's reply to the current utterance. Display it and append it as an agent line to the next turn's history. Text alone does not prove a capability succeeded.

tracearray of JSON valueOptional

Ordered capability attempts for this turn, not a history of the whole test. [] means no capability was attempted. Entries are diagnostic JSON; the public contract does not fix their nested shape. See Inspect a test turn for how to read available diagnostics.

timingsRunVoiceTestTurnTimingsOptional

Server-side durations in milliseconds for this turn, not audio latency or client network time. These measurements are diagnostic, not a response-time guarantee.

RunVoiceTestTurnTimings

total_msnumberRequired

Elapsed duration of the turn-processing loop. May include overhead beyond the three component measurements.

decide_msnumberRequired

Time spent on the initial model decision before any capability execution.

execute_msnumberRequired

Total time spent executing or simulating the requested capabilities.

compose_msnumberRequired

Time spent on subsequent model calls after the initial decision, including follow-up decisions and composing a reply.

Errors & retries

Set BRIGG_REQUEST_ID once for each logical action. The samples send it as Idempotency-Key. Reuse the same value and body on retries, including after a timeout; a missing response does not prove the action failed.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types. Supply a stable Idempotency-Key containing 1–200 characters.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying. Reuse the original Idempotency-Key.
403	`voice_test_expired`	The test expired, is unknown, or belongs to another member. Start a new test under the intended approved member.
409	`voice_test_ended`	The test was closed. Start a new session instead of retrying this turn.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "test_id": {
      "type": "string",
      "minLength": 1,
      "description": "Keep the returned test_id for this temporary session. Expired sessions require a new test. [voice.StartVoiceTest](/developers/reference/voice/StartVoiceTest)."
    },
    "utterance": {
      "type": "string",
      "minLength": 1,
      "description": "What the caller says."
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "caller",
              "agent"
            ],
            "description": "Conversation speaker: caller is the simulated customer; agent is the assistant. This is not a workspace permission or member role."
          },
          "text": {
            "type": "string",
            "description": "The words spoken by this participant, in conversation order."
          }
        },
        "required": [
          "role",
          "text"
        ],
        "additionalProperties": false
      },
      "default": [],
      "description": "Earlier caller and assistant lines, oldest first. Omit or use [] for the first turn. Send accumulated conversation on later turns; the current utterance belongs only in utterance, not duplicated here."
    },
    "turn_id": {
      "type": "string",
      "minLength": 1,
      "description": "Client-chosen identifier unique to one logical turn within this test. Keep it and the HTTP idempotency key unchanged when retrying that same utterance/history; choose new values for the next turn."
    }
  },
  "required": [
    "test_id",
    "utterance",
    "turn_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "test_id": "test_support_preview",
      "turn_id": "turn-1",
      "utterance": "I would like to book a meeting.",
      "history": []
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Assistant's reply to the current utterance. Display it and append it as an agent line to the next turn's history. Text alone does not prove a capability succeeded."
    },
    "trace": {
      "type": "array",
      "description": "Ordered capability attempts for this turn, not a history of the whole test. [] means no capability was attempted. Entries are diagnostic JSON; the public contract does not fix their nested shape. See Inspect a test turn for how to read available diagnostics."
    },
    "timings": {
      "description": "Server-side durations in milliseconds for this turn, not audio latency or client network time. These measurements are diagnostic, not a response-time guarantee.",
      "title": "RunVoiceTestTurnTimings",
      "type": "object",
      "properties": {
        "total_ms": {
          "type": "number",
          "description": "Elapsed duration of the turn-processing loop. May include overhead beyond the three component measurements."
        },
        "decide_ms": {
          "type": "number",
          "description": "Time spent on the initial model decision before any capability execution."
        },
        "execute_ms": {
          "type": "number",
          "description": "Total time spent executing or simulating the requested capabilities."
        },
        "compose_ms": {
          "type": "number",
          "description": "Time spent on subsequent model calls after the initial decision, including follow-up decisions and composing a reply."
        }
      },
      "required": [
        "total_ms",
        "decide_ms",
        "execute_ms",
        "compose_ms"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "text": "What day and time work best for you?",
      "trace": [],
      "timings": {
        "decide_ms": 430,
        "execute_ms": 0,
        "compose_ms": 0,
        "total_ms": 447
      }
    }
  ]
}

Try the request

Use your API key in a server environment.

Example scenario

Requires BRIGG_ACT_AS: an approved member account ID.

The assistant asks for clarification without invoking a capability, so trace is empty.

Request

cURL

curl 'https://api.brigg.app/v1/operations/voice.RunVoiceTestTurn' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "test_id": "test_support_preview",
  "turn_id": "turn-1",
  "utterance": "I would like to book a meeting.",
  "history": []
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/voice.RunVoiceTestTurn", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "test_id": "test_support_preview",
    "turn_id": "turn-1",
    "utterance": "I would like to book a meeting.",
    "history": []
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "test_id": "test_support_preview",
  "turn_id": "turn-1",
  "utterance": "I would like to book a meeting.",
  "history": []
}
request = Request(
    "https://api.brigg.app/v1/operations/voice.RunVoiceTestTurn",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "text": "What day and time work best for you?",
  "trace": [],
  "timings": {
    "decide_ms": 430,
    "execute_ms": 0,
    "compose_ms": 0,
    "total_ms": 447
  }
}

Illustrative values, not a live response.

Include earlier lines once, then send the new utterance separately. This illustrative turn reports a refused capability; no booking was created.

Request

cURL

curl 'https://api.brigg.app/v1/operations/voice.RunVoiceTestTurn' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "test_id": "test_support_preview",
  "turn_id": "turn-2",
  "utterance": "Tuesday morning, please.",
  "history": [
    {
      "role": "caller",
      "text": "I would like to book a meeting."
    },
    {
      "role": "agent",
      "text": "What day and time work best for you?"
    }
  ]
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/voice.RunVoiceTestTurn", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "test_id": "test_support_preview",
    "turn_id": "turn-2",
    "utterance": "Tuesday morning, please.",
    "history": [
      {
        "role": "caller",
        "text": "I would like to book a meeting."
      },
      {
        "role": "agent",
        "text": "What day and time work best for you?"
      }
    ]
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "test_id": "test_support_preview",
  "turn_id": "turn-2",
  "utterance": "Tuesday morning, please.",
  "history": [
    {
      "role": "caller",
      "text": "I would like to book a meeting."
    },
    {
      "role": "agent",
      "text": "What day and time work best for you?"
    }
  ]
}
request = Request(
    "https://api.brigg.app/v1/operations/voice.RunVoiceTestTurn",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "text": "Please choose a meeting type before we check times.",
  "trace": [
    {
      "capabilityId": "booking-preview",
      "source": "Support",
      "label": "Book meeting",
      "kind": "write",
      "result": {
        "status": "refused",
        "message": "Choose a meeting type."
      },
      "durationMs": 12
    }
  ],
  "timings": {
    "decide_ms": 480,
    "execute_ms": 12,
    "compose_ms": 260,
    "total_ms": 770
  }
}

Illustrative values, not a live response.