Agents — Create an agent from a template

POST

/v1/tenants/{tenantId}/agent-templates/{templateId}/instantiate

Copies the template's instructions, variables and voice settings into a new draft agent in the tenant, with a default widget configuration whose settings are all unset (the widget's defaults apply). Phone number, knowledge bases and tools are not copied.

Required permission: agents:write

Authorization

Bearer

headerAuthorizationBearer <token>

Tenant API key (evk_…), created in Studio → Vault → API keys.

Path Parameters

tenantId*string

Tenant id, or current for the key's own tenant. Must be the key's tenant or one of its sub-tenants.

templateId*string

Template id (from the template list).

Request Body

Name of the new agent.

body

Options for creating an agent from a template.

name*string

Name of the new agent.

Response Body

Created. The Location header points to the new agent.

response

An AI voice/chat agent.

id*string

Agent id.

version?integer

Concurrency version. Send it back when updating; it increases on every update.

Formatint32

name*string

Display name.

description?string

Internal description for people; not given to the AI.

instructions?string

System prompt for the AI. May reference prompt variables as {{name}} (see variableDefinitionsJson) and system variables such as {{system_caller_number}}.

variableDefinitionsJson?string

Prompt variables as a JSON-encoded string: an array of {"name", "jsonType", "placeholder", "description", "required"}. Referenced as {{name}} in the instructions and filled at conversation time (e.g. from tool output); placeholder is used when no value is available.

status?string

Lifecycle status.

Value in"draft""active""archived"

model?string

Realtime model, e.g. gpt-realtime or gpt-realtime-1.5. Empty means the platform default.

voice?string

Voice used for speech output.

Value in"alloy""ash""ballad""coral""echo""sage""shimmer""verse""marin""cedar"

knowledgeBaseIds?array<string>

Ids of linked knowledge bases.

phoneNumberId?string

Id of the assigned phone number, if any. Change it with the agent phone-number endpoints.

phoneNumber?string

The assigned phone number in E.164 format (read only).

allowFollowUpEmail?boolean

Give the AI a send_email tool that emails conversation details to followUpEmailAddress.

followUpEmailAddress?string

Recipient of follow-up emails (e.g. a team inbox). Required when allowFollowUpEmail is true.

allowCallTransfer?boolean

Give the AI a transfer_call tool on phone calls.

callTransferType?string

How phone calls are transferred.

Value in"direct""semi_attended"

isTemplate?boolean

When true the agent is a template that this tenant and its sub-tenants can create agents from.

type?string

Optional free-text label for your own classification; not used by the platform.

allowEndCall?boolean

Give the AI an end_call tool to end the conversation after saying goodbye.

tenantId*string

Tenant the agent belongs to (cannot be changed).

turnDetectionType?string

How the AI decides the user finished speaking: server_vad (silence based), semantic_vad (meaning based) or none (no automatic turn taking).

Value in"server_vad""semantic_vad""none"

turnDetectionEagerness?string

semantic_vad only: how quickly the AI responds.

Value in"auto""low""medium""high"

turnDetectionThreshold?number

server_vad only: speech detection sensitivity, 0.0–1.0 (higher needs louder speech). Default 0.5.

Formatdouble

turnDetectionPrefixPadding?integer

server_vad only: milliseconds of audio kept before detected speech. Default 300.

Formatint32

turnDetectionSilenceDuration?integer

server_vad only: milliseconds of silence that end the user's turn. Default 500.

Formatint32

turnDetectionTimeout?boolean

server_vad only: when true, the AI speaks up after turnDetectionTimeoutTime of user silence.

turnDetectionTimeoutTime?integer

Idle timeout in milliseconds; required when turnDetectionTimeout is true.

Formatint32

turnDetectionInterruptResponse?boolean

Whether the user can interrupt the AI while it is speaking. Default true.

transcriptionModel?string

Speech-to-text model for transcripts: gpt-4o-transcribe (precision) or gpt-4o-mini-transcribe (speed). off disables transcription.

transcriptionLanguage?string

Expected language as an ISO 639-1 code (e.g. sv, en), or auto to detect.

transcriptionInstructions?string

Optional hints for the transcriber, e.g. product names or spelling.

noiseReductionType?string

Input noise reduction: near_field (headsets, phones), far_field (laptops, rooms) or none.

Value in"none""near_field""far_field"

toolAssignments?

Not filled here; use GET /v1/tenants/{tenantId}/agents/{id}/tools.

Example Request

curl -X POST 'https://api.envocal.ai/v1/tenants/string/agent-templates/string/instantiate' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'

Example Request

curl -X POST 'https://api.envocal.ai/v1/tenants/string/agent-templates/string/instantiate' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'

Example ResponseSchema

{
  "id": "string",
  "version": 0,
  "name": "string",
  "description": "string",
  "instructions": "string",
  "variableDefinitionsJson": "string",
  "status": "draft",
  "model": "string",
  "voice": "alloy",
  "knowledgeBaseIds": [
    "string"
  ],
  "phoneNumberId": "string",
  "phoneNumber": "string",
  "allowFollowUpEmail": true,
  "followUpEmailAddress": "string",
  "allowCallTransfer": true,
  "callTransferType": "direct",
  "isTemplate": true,
  "type": "string",
  "allowEndCall": true,
  "tenantId": "string",
  "turnDetectionType": "server_vad",
  "turnDetectionEagerness": "auto",
  "turnDetectionThreshold": 0.1,
  "turnDetectionPrefixPadding": 0,
  "turnDetectionSilenceDuration": 0,
  "turnDetectionTimeout": true,
  "turnDetectionTimeoutTime": 0,
  "turnDetectionInterruptResponse": true,
  "transcriptionModel": "string",
  "transcriptionLanguage": "string",
  "transcriptionInstructions": "string",
  "noiseReductionType": "none",
  "toolAssignments": {
    "before": [
      "8e6267db-32ed-454a-a2cc-6beef2f6f00e"
    ],
    "during": [
      "e3ae3f0a-5397-4416-b273-f7833a7fddc8"
    ],
    "after": [
      "3f00dd4a-56f2-49c5-940c-69eed8a9fb5b"
    ]
  }
}

{  "id": "string",  "version": 0,  "name": "string",  "description": "string",  "instructions": "string",  "variableDefinitionsJson": "string",  "status": "draft",  "model": "string",  "voice": "alloy",  "knowledgeBaseIds": [    "string"  ],  "phoneNumberId": "string",  "phoneNumber": "string",  "allowFollowUpEmail": true,  "followUpEmailAddress": "string",  "allowCallTransfer": true,  "callTransferType": "direct",  "isTemplate": true,  "type": "string",  "allowEndCall": true,  "tenantId": "string",  "turnDetectionType": "server_vad",  "turnDetectionEagerness": "auto",  "turnDetectionThreshold": 0.1,  "turnDetectionPrefixPadding": 0,  "turnDetectionSilenceDuration": 0,  "turnDetectionTimeout": true,  "turnDetectionTimeoutTime": 0,  "turnDetectionInterruptResponse": true,  "transcriptionModel": "string",  "transcriptionLanguage": "string",  "transcriptionInstructions": "string",  "noiseReductionType": "none",  "toolAssignments": {    "before": [      "8e6267db-32ed-454a-a2cc-6beef2f6f00e"    ],    "during": [      "e3ae3f0a-5397-4416-b273-f7833a7fddc8"    ],    "after": [      "3f00dd4a-56f2-49c5-940c-69eed8a9fb5b"    ]  }}

Create an agent from a template

Create an agent from a template

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Path Parameters

Request Body

Response Body