AGagentphone
agents

Create Agent

Changed on

Create a new agent.

An agent represents an AI persona (Support Bot, Sales Agent, etc.) that can have phone numbers attached to it.

voiceMode: "webhook" (default) forwards transcripts to your webhook. "hosted" uses a built-in LLM with systemPrompt (no webhook needed).

post/v1/agents

Request

  • Base URL
    https://api.agentphone.ai
  • URL
    https://api.agentphone.ai/v1/agents
  • Auth
    HTTP bearer

Request body

namestring required
descriptionstring nullable
voiceMode'webhook' | 'hosted' nullable
enableMessagingboolean nullable

When true, hosted-mode agents can send and read SMS/iMessage during calls. Defaults to true.

modelTier'turbo' | 'balanced' | 'max' | 'realtime' | 'live' nullable
systemPromptstring nullable
voicePromptstring nullable

Live only: speaking identity, public call purpose (who you represent and why you call), style, and verbal rules. The voice model only knows what is written here; it delegates everything else. Required with modelTier live. Business instructions stay in systemPrompt. Omit on PATCH to preserve; null or empty clears when Live is inactive.

beginMessagestring nullable
voicestring nullable
transferNumberstring nullable
voicemailMessagestring nullable
callScreeningIdentitystring nullable
callScreeningPurposestring nullable
sttMode'fast' | 'accurate' nullable

Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency).

ambientSound'none' | 'office' | 'coffee-shop' | 'outdoor' nullable

Background ambience to mask synthetic silence between turns. 'none' disables; 'office', 'coffee-shop', 'outdoor' enable a quiet bed.

denoisingMode'noise-cancellation' | 'noise-and-background-speech-cancellation' nullable

Audio denoising. 'noise-cancellation' (default) handles general noise. 'noise-and-background-speech-cancellation' is more aggressive for callers in cars, cafes, or near TVs.

maxSilenceMsinteger nullable

Hang up the call after this many milliseconds of caller silence. Default 600000 (10 min). Raise for IVR/hold-music workflows; lower to fail fast on dead lines. Range 10000 (10s) to 3600000 (1 hour).

voiceSpeednumber nullable

Voice speed multiplier. 1.0 is normal pace; lower values slow speech (0.5 is half speed), higher values speed it up (2.0 is double). Range 0.5 to 2.0.

interruptionSensitivitynumber nullable

How easily callers can interrupt the agent. 0 means the agent is never interrupted, 1 means the agent stops at the first sound. Default 0.8. Range 0.0 to 1.0.

enableBackchannelboolean nullable

When true, the agent interjects short filler words like 'uh-huh' or 'mhmm' during longer caller utterances. Set false to keep the agent silent while the caller is speaking. Defaults to true.

language'af-ZA' | 'ar-SA' | 'az-AZ' | 'bg-BG' | 'bs-BA' | 'ca-ES' | 'cs-CZ' | 'cy-GB' | 'da-DK' | 'de-DE' | 'el-GR' | 'en-AU' | 'en-GB' | 'en-IN' | 'en-NZ' | 'en-US' | 'es-419' | 'es-ES' | 'fa-IR' | 'fi-FI' | 'fil-PH' | 'fr-CA' | 'fr-FR' | 'gl-ES' | 'he-IL' | 'hi-IN' | 'hr-HR' | 'hu-HU' | 'hy-AM' | 'id-ID' | 'is-IS' | 'it-IT' | 'ja-JP' | 'kk-KZ' | 'kn-IN' | 'ko-KR' | 'lt-LT' | 'lv-LV' | 'mk-MK' | 'mr-IN' | 'ms-MY' | 'ne-NP' | 'nl-BE' | 'nl-NL' | 'no-NO' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sl-SI' | 'sr-RS' | 'sv-SE' | 'sw-KE' | 'ta-IN' | 'th-TH' | 'tr-TR' | 'uk-UA' | 'ur-IN' | 'vi-VN' | 'yue-CN' | 'zh-CN' nullable

BCP-47 locale that drives the agent's speech recognition and pronunciation. Defaults to 'en-US'. See the enum for the full set of supported codes.

Response

Successful Response

idstring required
namestring required
descriptionstring nullable required
voiceMode'webhook' | 'hosted' required
enableMessagingboolean
modelTier'turbo' | 'balanced' | 'max' | 'realtime' | 'live'
systemPromptstring nullable
voicePromptstring nullable
beginMessagestring nullable
voicestring required
transferNumberstring nullable
customToolsobject[] nullable
voicemailMessagestring nullable
callScreeningIdentitystring nullable
callScreeningPurposestring nullable
sttMode'fast' | 'accurate'

Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency).

ambientSound'none' | 'office' | 'coffee-shop' | 'outdoor'

Background ambience to mask synthetic silence between turns. 'none' disables; 'office', 'coffee-shop', 'outdoor' enable a quiet bed.

denoisingMode'noise-cancellation' | 'noise-and-background-speech-cancellation'

Audio denoising. 'noise-cancellation' (default) handles general noise. 'noise-and-background-speech-cancellation' is more aggressive for callers in cars, cafes, or near TVs.

maxSilenceMsinteger

Hang up the call after this many milliseconds of caller silence. Range 10000 (10s) to 3600000 (1 hour). Default 600000 (10 min).

voiceSpeednumber

Voice speed multiplier. Range 0.5 to 2.0. Default 1.0.

interruptionSensitivitynumber

How easily callers can interrupt the agent. Range 0.0 to 1.0. Default 0.8.

enableBackchannelboolean

When true, the agent interjects short filler words like 'uh-huh' or 'mhmm' during longer caller utterances. Defaults to true.

languagestring

BCP-47 locale that drives the agent's speech recognition and pronunciation. Defaults to 'en-US'.

createdAtstring date-time required

Changes

  • dbecff17a352Revision changes
    • warning

      added the new live enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new live enum value to the request property

    • info

      added the optional property to the response with the status

  • 0d7df4435963Revision changes
    • warning

      added the new realtime enum value to the response property for the response status

    • info

      added the new realtime enum value to the request property