Add transcription context

Two levers make the agent’s speech-to-text transcribe the caller more accurately: a free-form transcription prompt that describes the call, and a key terms list of exact words to boost. Use them together: the prompt sets the scene, and key terms nail specific names and codes. Both live under input, set when you create or update the agent, or inline via session.update. For how both work under the hood, see Prompting and keyterms in the Streaming docs.

Contextual prompt

input.transcription_prompt tells the speech-to-text model what the call is about so it resolves jargon, product names, and homophones in what the caller says. Describe the domain and scenario in plain language.

This is not the same as system_prompt. system_prompt shapes what the agent says; transcription_prompt shapes how the caller’s speech is transcribed. Give it context (“this is a pharmacy support call”), not instructions (“use formal punctuation”); behavioral commands are ignored.

curl -X POST https://agents.assemblyai.com/v1/agents \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pharmacy Assistant",
    "system_prompt": "You help patients with prescription refills.",
    "voice": { "voice_id": "alba" },
    "input": {
      "transcription_prompt": "A pharmacy support call. Callers mention medication names, dosages in mg, insurance carriers, and pharmacy locations."
    }
  }'

# pip install requests
import os
import requests

resp = requests.post(
    "https://agents.assemblyai.com/v1/agents",
    headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
    json={
        "name": "Pharmacy Assistant",
        "system_prompt": "You help patients with prescription refills.",
        "voice": {"voice_id": "alba"},
        "input": {
            "transcription_prompt": "A pharmacy support call. Callers mention medication names, dosages in mg, insurance carriers, and pharmacy locations."
        },
    },
)
resp.raise_for_status()
print(resp.json())

// Node 18+ has fetch built in
const res = await fetch("https://agents.assemblyai.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: process.env.ASSEMBLYAI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Pharmacy Assistant",
    system_prompt: "You help patients with prescription refills.",
    voice: { voice_id: "alba" },
    input: {
      transcription_prompt:
        "A pharmacy support call. Callers mention medication names, dosages in mg, insurance carriers, and pharmacy locations.",
    },
  }),
});
const data = await res.json();
console.log(data);

Field	Type	Required	Notes
`input.transcription_prompt`	string	No	Free-form context about the call, up to 1750 characters. Updatable mid-session.

Key terms

input.keyterms is an explicit list of rare or domain-specific words to boost, like a person’s name, a product, or an acronym. It works as a word boost, biasing the speech recognition model toward each term. Reach for it when you have specific strings to nail, and use the prompt above for the surrounding context.

curl -X POST https://agents.assemblyai.com/v1/agents \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
    "voice": { "voice_id": "alba" },
    "input": { "keyterms": ["AssemblyAI", "Lemur", "Ozempic"] }
  }'

# pip install requests
import os
import requests

resp = requests.post(
    "https://agents.assemblyai.com/v1/agents",
    headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
    json={
        "name": "Support Assistant",
        "system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
        "voice": {"voice_id": "alba"},
        "input": {"keyterms": ["AssemblyAI", "Lemur", "Ozempic"]},
    },
)
resp.raise_for_status()
print(resp.json())

// Node 18+ has fetch built in
const res = await fetch("https://agents.assemblyai.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: process.env.ASSEMBLYAI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support Assistant",
    system_prompt: "You are a friendly support agent. Keep replies under two sentences.",
    voice: { voice_id: "alba" },
    input: { keyterms: ["AssemblyAI", "Lemur", "Ozempic"] },
  }),
});
const data = await res.json();
console.log(data);

Field	Type	Required	Notes
`input.keyterms`	string[] \| null	No	Up to 100 transcription-bias strings. `null` or `[]` clears the boost.

Add:

Brand, product, and feature names that aren’t in everyday English ("AssemblyAI", "Lemur", "Ozempic").
Proper nouns specific to this caller: their full name, their account holder’s name, the agent’s name if it’s unusual.
Domain jargon the model might otherwise transcribe as a common-word homophone ("hemochromatosis", "polysomnography").
Acronyms you want spelled in full ("PCI DSS", "FedRAMP").

Don’t add:

Common English words. Each entry boosts that string, and adding common words at the same weight as your rare terms dilutes the boost.
Whole sentences or phrases. The boost is per-term, not per-phrase.
Punctuation, formatting, or instructions. The list is transcription hints, not prompt context.

Replace the list any time by sending a new keyterms array; it takes effect on the next user utterance. Refresh it when the conversation enters a new domain, for example when a support call moves from billing to technical.

Getting started

Create & manage agents

Agent behavior

Conversational experience

Deploy

After a session

Reference

API reference

Add transcription context

Contextual prompt

Key terms

​Contextual prompt

​Key terms

Contextual prompt

Key terms