Skip to main content
POST
/
api
/
v2
/
agent
Update Agent
curl --request POST \
  --url 'https://api.vida.dev/api/v2/agent?token=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "chatAgent",
  "title": "Call Screener",
  "description": "Description",
  "welcomeMessage": "This brought to you by Wolf Cola",
  "links": [
    "https://vida.io/faq"
  ],
  "actions": [
    "transfer"
  ],
  "timezone": "America/Chicago, America/New_York, Europe/London, etc",
  "agentVoice": "en-US Female",
  "agentLang": "en-US",
  "agentInstructions": "I want you to payout rewards for users that answer a few questions about this promotional video.",
  "agentModel": "gpt-4o-2024-08-06",
  "agentThinking": "low",
  "agentThinkingModel": "gpt-5.2",
  "postConvoForceThinking": false,
  "agentS2SEngine": null,
  "agentSttEngine": "deepgram",
  "agentSttSmartFormatting": true,
  "postAnswerDtmf": "<string>",
  "waitOnAnswer": 123,
  "backgroundAudio": "<string>",
  "interruptionWordCount": 3,
  "interruptionMinimumSpeakingTime": 3,
  "speakingTimeout": 1200,
  "speechProcessingDelay": 500,
  "speechProcessingDelayInterruptionStep": 500,
  "speechProcessingDelayMaxMultiplier": 4,
  "callerResponseTimeout": 13,
  "callerResponseTimeoutHangupCounter": 3,
  "noContactInjection": false,
  "noConvoHistory": false,
  "autoRecordingNotification": "true",
  "recordingNotificationPhrase": "This call is being recorded.",
  "preAnswerRingTime": null,
  "preAnswerSkipProcessingResults": false,
  "cnamAutoRejectRegex": null,
  "cnamAutoRejectCode": 603,
  "cnamAutoTransferRegex": null,
  "cnamAutoTransferDestination": null,
  "confirmTransfers": false,
  "monitorTransfers": false,
  "attendedTransfers": false,
  "attendedTransferBridgeTrigger": null,
  "transferConfirmTimeout": 30,
  "apps": []
}
'
{
  "success": true,
  "message": "Agent created.",
  "campaignId": "camp931829b5857f...."
}

Documentation Index

Fetch the complete documentation index at: https://vida.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

token
string
query
required

Vida API Token

Body

application/json
type
enum<string>
required

Type for this agent

Available options:
chatAgent
title
string
required

Title for Agent

Example:

"Call Screener"

description
string
required

Some description

Example:

"Description"

welcomeMessage
string

Message users see when initially visiting a agent

Example:

"This brought to you by Wolf Cola"

Array of any http links to reference for external knowledge for your agent

Example:
["https://vida.io/faq"]
actions
string[]

Actions that your agent can take including instructions and settings

Example:
["transfer"]
timezone
string

The IANA (Internet Assigned Numbers Authority) formatted timezone your AI agent operates in.

Example:

"America/Chicago, America/New_York, Europe/London, etc"

agentVoice
string

Agent voice model to use

Example:

"en-US Female"

agentLang
enum<string>
default:en-US

Agent language to be used for voice and transcriptions

Available options:
en-US,
multi,
es-MX,
es-ES,
es-US
agentInstructions
string

Agent instructions for user interaction. This is for chatAgents only

Example:

"I want you to payout rewards for users that answer a few questions about this promotional video."

agentModel
string

Agent LLM model to use for its intelligence

Example:

"gpt-4o-2024-08-06"

agentThinking
enum<string> | null

Optional reasoning budget for models that support thinking. Use null to disable or low for short thinking.

Available options:
low
agentThinkingModel
string

Model to use for pauseAndThink function reasoning. Defaults to gpt-5.2.

Example:

"gpt-5.2"

postConvoForceThinking
boolean

Force post-conversation summary/reporting/spam detection to use a thinking-capable model when agentThinking is off and the selected model does not support thinking. Uses agentThinkingModel (default gpt-5.2).

Example:

false

agentS2SEngine
enum<string>

(Requires Specific Paid Plan) The Speech-to-Speech Voice engine to use for voice, AI, and transcriptions

Available options:
null,
openai,
gemini
agentSttEngine
enum<string>
default:deepgram

Speech to text engine for this agent

Available options:
google,
deepgram,
deepgramflux,
openai
agentSttSmartFormatting
boolean
default:true

Enable Deepgram smart formatting for speech-to-text (punctuation + numerals stay enabled regardless). Default true.

postAnswerDtmf
string

DTMF your agent will send upon answering a call. Useful if you are forwarding calls to your agent from a platform that requires a DTMF verification before the call is connected.

waitOnAnswer
integer

The amount of time in milliseconds your Agent will wait before speaking the greeting (welcomeMessage).

backgroundAudio

Optional background audio to play on calls. Accepts a URL string or an object with url, loop (true or false), gain, and startAfterGreeting fields. Only HTTP(S) URLs are supported.

interruptionWordCount
integer
default:3

how many words a caller needs to speak before it is treated as an interruption

interruptionMinimumSpeakingTime
integer
default:3

(in seconds) How long the agent needs to be speaking before it can be interrupted

speakingTimeout
integer
default:1200

(in milliseconds) the default amount of time between words before we consider caller speaking to be finished. Increasing this can help prevent unintentional interruptions for slow talkers.

speechProcessingDelay
integer
default:500

(in milliseconds) the default amount of delay before processed speech is sent to the LLM for a response. Increasing this can help prevent unintentional interruptions for slow talkers. Note that this delay automatically increases and decreases depending on the number of interruptions over a period of time.

speechProcessingDelayInterruptionStep
integer
default:500

(in milliseconds) how much speech processing delay is added per interruption.

speechProcessingDelayMaxMultiplier
integer
default:4

the maximum number of interruptions that will influence the speech processing delay.

callerResponseTimeout
integer
default:13

(in seconds) how much silence (nothing said by the caller) before the agent asks are you still there?.

callerResponseTimeoutHangupCounter
integer
default:3

the maximum number of times your agent can ask are you there (callerResponseTimeout) before hanging up the call.

noContactInjection
boolean
default:false

Whether the contact card for the caller should be injected into the agent context

noConvoHistory
boolean
default:false

Whether the call summary history for the caller should be injected into the agent context

autoRecordingNotification
string
default:true

Whether to automatically notify callers that recording is happening: true (string) means notify callers from area codes where it is legally required. false (string) means never notify callers. always (string) means notify every caller whether legally required or not that recording is in progress.

recordingNotificationPhrase
string
default:This call is being recorded.

The phrase that will be spoken to the caller notifying them that recording is in progress: This call is being recorded is the default.

preAnswerRingTime
integer

In seconds. How many seconds should the caller experience ringing before the agent answers. Valid value range is 1-60

preAnswerSkipProcessingResults
boolean
default:false

When true, pre-answer functions return their raw results directly to agent context instead of sending those results back to the LLM for another processing step.

cnamAutoRejectRegex
string

Optional JavaScript regex string. On inbound voice calls, if the inbound SIP CNAM matches this pattern, the call is immediately rejected before answer. Reject wins if both reject and transfer match.

cnamAutoRejectCode
integer
default:603

Optional SIP reject code to use when cnamAutoRejectRegex matches. Defaults to 603 when omitted.

cnamAutoTransferRegex
string

Optional JavaScript regex string. On inbound voice calls, if the inbound SIP CNAM matches this pattern and reject did not match, the call is immediately transferred silently.

cnamAutoTransferDestination
string

Destination used when cnamAutoTransferRegex matches. Accepts E.164 phone numbers or PBX/extension targets like ext:1234 or pbx:1234.

confirmTransfers
boolean
default:false

Require callee to press 1 before a transfer is completed

monitorTransfers
boolean
default:false

Continue to monitor and transcribe transferred calls.

attendedTransfers
boolean
default:false

Your agent will stay on the line with the caller while transfer attempts are made. Those answering the transfer attempts will need to say Yes to accept the call. This will override the confirmTransfers option.

attendedTransferBridgeTrigger
string

What is required to be spoken by the transferee in order for the call to be bridged. Values can be null (defaults to Yes), any, or a regex.

transferConfirmTimeout
integer
default:30

The length of time in seconds we will wait for confirmation after a transferred call with confirmTransfers or attendedTransfers is answered.

apps
object[]

Array of apps to enable for this given agent

Response

200 - application/json

Successful response

success
boolean
Example:

true

message
string
Example:

"Agent created."

campaignId
string
Example:

"camp931829b5857f...."