Create an agent

POST

agents

Create Agent

curl --request POST \
  --url https://api.vocily.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme COD Confirmation",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back the order.\n3. Ask whether they will accept delivery.",
  "greeting": {
    "mode": "custom",
    "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon.",
    "delay_ms": 0
  },
  "language": {
    "default": "hi-IN",
    "additional": [
      "en-IN"
    ]
  },
  "voice": {
    "provider": "vocily",
    "voice_id": "hi-IN-aman",
    "speed": 1
  },
  "model": {
    "model": "gpt-5.4-nano",
    "temperature": 0.4
  },
  "transcriber": {
    "provider": "sarvam",
    "model": "saaras:v4",
    "keywords": [
      "Acme",
      "COD"
    ]
  },
  "call": {
    "max_duration_minutes": 5,
    "recording_enabled": true
  },
  "builtin_tools": {
    "transfer_call": {
      "enabled": true,
      "numbers": [
        {
          "number": "+919876543210",
          "priority": 1,
          "start_hour": 9,
          "end_hour": 20,
          "timezone": "Asia/Kolkata"
        }
      ]
    }
  },
  "variables": [
    {
      "key": "order_id",
      "default_value": null
    }
  ]
}
'

import requests

url = "https://api.vocily.ai/v1/agents"

payload = {
    "name": "Acme COD Confirmation",
    "system_prompt": "## Agent Purpose
You confirm cash-on-delivery orders for Acme Store.

## Response Style
Warm, brief, one question at a time.

## Call Flow
1. Greet {{callee_name}}.
2. Read back the order.
3. Ask whether they will accept delivery.",
    "greeting": {
        "mode": "custom",
        "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon.",
        "delay_ms": 0
    },
    "language": {
        "default": "hi-IN",
        "additional": ["en-IN"]
    },
    "voice": {
        "provider": "vocily",
        "voice_id": "hi-IN-aman",
        "speed": 1
    },
    "model": {
        "model": "gpt-5.4-nano",
        "temperature": 0.4
    },
    "transcriber": {
        "provider": "sarvam",
        "model": "saaras:v4",
        "keywords": ["Acme", "COD"]
    },
    "call": {
        "max_duration_minutes": 5,
        "recording_enabled": True
    },
    "builtin_tools": { "transfer_call": {
            "enabled": True,
            "numbers": [
                {
                    "number": "+919876543210",
                    "priority": 1,
                    "start_hour": 9,
                    "end_hour": 20,
                    "timezone": "Asia/Kolkata"
                }
            ]
        } },
    "variables": [
        {
            "key": "order_id",
            "default_value": None
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Acme COD Confirmation',
    system_prompt: '## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back the order.\n3. Ask whether they will accept delivery.',
    greeting: {
      mode: 'custom',
      message: 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.',
      delay_ms: 0
    },
    language: {default: 'hi-IN', additional: ['en-IN']},
    voice: {provider: 'vocily', voice_id: 'hi-IN-aman', speed: 1},
    model: {model: 'gpt-5.4-nano', temperature: 0.4},
    transcriber: {provider: 'sarvam', model: 'saaras:v4', keywords: ['Acme', 'COD']},
    call: {max_duration_minutes: 5, recording_enabled: true},
    builtin_tools: {
      transfer_call: {
        enabled: true,
        numbers: [
          {
            number: '+919876543210',
            priority: 1,
            start_hour: 9,
            end_hour: 20,
            timezone: 'Asia/Kolkata'
          }
        ]
      }
    },
    variables: [{key: 'order_id', default_value: null}]
  })
};

fetch('https://api.vocily.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Acme COD Confirmation',
    'system_prompt' => '## Agent Purpose
You confirm cash-on-delivery orders for Acme Store.

## Response Style
Warm, brief, one question at a time.

## Call Flow
1. Greet {{callee_name}}.
2. Read back the order.
3. Ask whether they will accept delivery.',
    'greeting' => [
        'mode' => 'custom',
        'message' => 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.',
        'delay_ms' => 0
    ],
    'language' => [
        'default' => 'hi-IN',
        'additional' => [
                'en-IN'
        ]
    ],
    'voice' => [
        'provider' => 'vocily',
        'voice_id' => 'hi-IN-aman',
        'speed' => 1
    ],
    'model' => [
        'model' => 'gpt-5.4-nano',
        'temperature' => 0.4
    ],
    'transcriber' => [
        'provider' => 'sarvam',
        'model' => 'saaras:v4',
        'keywords' => [
                'Acme',
                'COD'
        ]
    ],
    'call' => [
        'max_duration_minutes' => 5,
        'recording_enabled' => true
    ],
    'builtin_tools' => [
        'transfer_call' => [
                'enabled' => true,
                'numbers' => [
                                [
                                                                'number' => '+919876543210',
                                                                'priority' => 1,
                                                                'start_hour' => 9,
                                                                'end_hour' => 20,
                                                                'timezone' => 'Asia/Kolkata'
                                ]
                ]
        ]
    ],
    'variables' => [
        [
                'key' => 'order_id',
                'default_value' => null
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocily.ai/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"Acme COD Confirmation\",\n  \"system_prompt\": \"## Agent Purpose\\nYou confirm cash-on-delivery orders for Acme Store.\\n\\n## Response Style\\nWarm, brief, one question at a time.\\n\\n## Call Flow\\n1. Greet {{callee_name}}.\\n2. Read back the order.\\n3. Ask whether they will accept delivery.\",\n  \"greeting\": {\n    \"mode\": \"custom\",\n    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\",\n    \"delay_ms\": 0\n  },\n  \"language\": {\n    \"default\": \"hi-IN\",\n    \"additional\": [\n      \"en-IN\"\n    ]\n  },\n  \"voice\": {\n    \"provider\": \"vocily\",\n    \"voice_id\": \"hi-IN-aman\",\n    \"speed\": 1\n  },\n  \"model\": {\n    \"model\": \"gpt-5.4-nano\",\n    \"temperature\": 0.4\n  },\n  \"transcriber\": {\n    \"provider\": \"sarvam\",\n    \"model\": \"saaras:v4\",\n    \"keywords\": [\n      \"Acme\",\n      \"COD\"\n    ]\n  },\n  \"call\": {\n    \"max_duration_minutes\": 5,\n    \"recording_enabled\": true\n  },\n  \"builtin_tools\": {\n    \"transfer_call\": {\n      \"enabled\": true,\n      \"numbers\": [\n        {\n          \"number\": \"+919876543210\",\n          \"priority\": 1,\n          \"start_hour\": 9,\n          \"end_hour\": 20,\n          \"timezone\": \"Asia/Kolkata\"\n        }\n      ]\n    }\n  },\n  \"variables\": [\n    {\n      \"key\": \"order_id\",\n      \"default_value\": null\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vocily.ai/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme COD Confirmation\",\n  \"system_prompt\": \"## Agent Purpose\\nYou confirm cash-on-delivery orders for Acme Store.\\n\\n## Response Style\\nWarm, brief, one question at a time.\\n\\n## Call Flow\\n1. Greet {{callee_name}}.\\n2. Read back the order.\\n3. Ask whether they will accept delivery.\",\n  \"greeting\": {\n    \"mode\": \"custom\",\n    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\",\n    \"delay_ms\": 0\n  },\n  \"language\": {\n    \"default\": \"hi-IN\",\n    \"additional\": [\n      \"en-IN\"\n    ]\n  },\n  \"voice\": {\n    \"provider\": \"vocily\",\n    \"voice_id\": \"hi-IN-aman\",\n    \"speed\": 1\n  },\n  \"model\": {\n    \"model\": \"gpt-5.4-nano\",\n    \"temperature\": 0.4\n  },\n  \"transcriber\": {\n    \"provider\": \"sarvam\",\n    \"model\": \"saaras:v4\",\n    \"keywords\": [\n      \"Acme\",\n      \"COD\"\n    ]\n  },\n  \"call\": {\n    \"max_duration_minutes\": 5,\n    \"recording_enabled\": true\n  },\n  \"builtin_tools\": {\n    \"transfer_call\": {\n      \"enabled\": true,\n      \"numbers\": [\n        {\n          \"number\": \"+919876543210\",\n          \"priority\": 1,\n          \"start_hour\": 9,\n          \"end_hour\": 20,\n          \"timezone\": \"Asia/Kolkata\"\n        }\n      ]\n    }\n  },\n  \"variables\": [\n    {\n      \"key\": \"order_id\",\n      \"default_value\": null\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Acme COD Confirmation\",\n  \"system_prompt\": \"## Agent Purpose\\nYou confirm cash-on-delivery orders for Acme Store.\\n\\n## Response Style\\nWarm, brief, one question at a time.\\n\\n## Call Flow\\n1. Greet {{callee_name}}.\\n2. Read back the order.\\n3. Ask whether they will accept delivery.\",\n  \"greeting\": {\n    \"mode\": \"custom\",\n    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\",\n    \"delay_ms\": 0\n  },\n  \"language\": {\n    \"default\": \"hi-IN\",\n    \"additional\": [\n      \"en-IN\"\n    ]\n  },\n  \"voice\": {\n    \"provider\": \"vocily\",\n    \"voice_id\": \"hi-IN-aman\",\n    \"speed\": 1\n  },\n  \"model\": {\n    \"model\": \"gpt-5.4-nano\",\n    \"temperature\": 0.4\n  },\n  \"transcriber\": {\n    \"provider\": \"sarvam\",\n    \"model\": \"saaras:v4\",\n    \"keywords\": [\n      \"Acme\",\n      \"COD\"\n    ]\n  },\n  \"call\": {\n    \"max_duration_minutes\": 5,\n    \"recording_enabled\": true\n  },\n  \"builtin_tools\": {\n    \"transfer_call\": {\n      \"enabled\": true,\n      \"numbers\": [\n        {\n          \"number\": \"+919876543210\",\n          \"priority\": 1,\n          \"start_hour\": 9,\n          \"end_hour\": 20,\n          \"timezone\": \"Asia/Kolkata\"\n        }\n      ]\n    }\n  },\n  \"variables\": [\n    {\n      \"key\": \"order_id\",\n      \"default_value\": null\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "00000005-0000-4000-8000-000000000005",
  "name": "Support line",
  "version": 0,
  "version_id": "00000006-0000-4000-8000-000000000006",
  "is_published": false,
  "is_live": false,
  "live_version": null,
  "latest_version": 0,
  "document_revision": 1,
  "label": null,
  "notes": null,
  "blocked_reasons": [],
  "created_at": "2026-09-16T19:38:03.767024Z",
  "updated_at": "2026-09-16T19:38:03.767024Z",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back order {{order_id}}.\n3. Ask whether they accept delivery.\n4. Close politely.",
  "greeting": {
    "message": "Hello! I am your AI voice agent. How can I help you today?",
    "prompt": "The voice call has connected and the caller has not spoken. Generate the opening greeting using the agent identity, purpose, response style, call flow and any prepared call information in the system instructions. Follow the configured primary language. Keep it to one or two short spoken sentences and at most one question. Do not invent caller details or completed actions. Do not output placeholders, tool calls, stage directions or an explanation. Return only the words to speak.",
    "mode": "custom",
    "delay_ms": 0
  },
  "language": {
    "default": "hi-IN",
    "additional": [
      "en-IN"
    ],
    "switch_trigger": "requested_or_auto"
  },
  "transcriber": {
    "provider": "sarvam",
    "model": "saaras:v4",
    "keywords": [
      "Acme",
      "COD"
    ],
    "fallback": {
      "provider": "deepgram",
      "model": "nova-3-general"
    }
  },
  "model": {
    "provider": "openai",
    "model": "gpt-5.4-nano",
    "temperature": 0.4,
    "max_tokens": 128,
    "fallback": {
      "provider": "gemini",
      "model": "gemini-3.5-flash-lite"
    }
  },
  "voice": {
    "provider": "vocily",
    "model": "v2",
    "voice_id": "hi-IN-aman",
    "speed": 1,
    "emotion": null,
    "fallback": {
      "provider": "sarvam",
      "model": "bulbul:v3",
      "voice_id": "shubh"
    }
  },
  "conversation": {
    "interruption_sensitivity": 0.5,
    "response_eagerness": 0.75,
    "noise_handling": {
      "mode": "standard",
      "level": 50
    },
    "silence_reminder": {
      "enabled": true,
      "seconds": 15
    }
  },
  "call": {
    "max_duration_minutes": 5,
    "end_on_silence_seconds": 25,
    "recording_enabled": true,
    "custom_analysis_enabled": true,
    "max_duration_message": {
      "mode": "default",
      "prompt": "The call has reached its maximum allowed duration and must end now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: the maximum call time has been reached, so the call is ending now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    },
    "end_on_silence_message": {
      "mode": "default",
      "prompt": "The caller has been silent for too long and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you could not hear anything on the line, so you are ending the call now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    }
  },
  "builtin_tools": {
    "end_call": {
      "enabled": true
    },
    "hold_call": {
      "enabled": true,
      "max_seconds": 90,
      "follow_up_seconds": 45,
      "acknowledgement_message": {
        "mode": "default",
        "prompt": "Write one short sentence to say to the caller as you start waiting, in the language you have been speaking — confirming you heard them and will wait. Do not ask a question and do not guess why they need the moment.",
        "text": ""
      },
      "follow_up_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away for a moment (they may be fetching a card, a document, or checking something). Generate one very short, gentle check-in in the same language and tone as the conversation above. Keep it to one short sentence, e.g. asking if they are back or reassuring them you are still on the line. Do not say goodbye. Do not say the call is ending. Do not repeat earlier content or ask new questions.",
        "text": ""
      },
      "timeout_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away, but they have not returned and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you waited but could not reach them, so you are ending the call; they are welcome to call back. Keep it to one short sentence. Do not ask a question.",
        "text": ""
      }
    },
    "transfer_call": {
      "enabled": true,
      "numbers": [
        {
          "number": "+919876543210",
          "priority": 1,
          "start_hour": 9,
          "end_hour": 20,
          "timezone": "Asia/Kolkata",
          "max_concurrent_calls": 1
        }
      ],
      "busy_message": {
        "mode": "default",
        "prompt": "You tried to transfer the caller to a human teammate, but nobody is available. Generate one short line in the same language and tone as the conversation above, saying the team is busy right now and asking them to try again a little later. Do not ask a question and do not promise a callback.",
        "text": ""
      },
      "intro_message": {
        "mode": "custom",
        "prompt": "You are about to transfer the caller to a human teammate. Generate one short line in the same language and tone as the conversation above, telling them to hold while you connect them. Do not ask a question and do not promise a specific person, a wait time or a callback.",
        "text": "Ek minute, main aapko connect karti hoon."
      }
    },
    "send_whatsapp_template": {
      "enabled": false,
      "templates": []
    }
  },
  "variables": [
    {
      "key": "callee_name",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    },
    {
      "key": "callee_number",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    }
  ],
  "knowledge_base_ids": [],
  "analysis_group_ids": [
    "00000007-0000-4000-8000-000000000007"
  ],
  "memory": {
    "enabled": true,
    "channels": [
      "outbound",
      "whatsapp"
    ],
    "allow_ai_labels": true,
    "label_instructions": "Record anything about the caller worth knowing next time, even when it is not one of the fields above: who they are, other ways to reach them, how they prefer to be dealt with, their standing with the business, or anything situational. Only what will still be true later; nothing said in passing.",
    "max_facts": 150,
    "transcript_turns": 12,
    "fields": [
      {
        "key": "delivery_pincode",
        "label": "Delivery PIN code",
        "type": "string",
        "enum_values": null,
        "description": "The PIN code the caller wants deliveries sent to.",
        "category": "contact"
      }
    ]
  },
  "numbers": null,
  "dashboard_url": "https://app.vocily.ai/agents/00000005-0000-4000-8000-000000000005",
  "inbound": {
    "business_hours_closed_message": {
      "mode": "default",
      "prompt": "This inbound call arrived outside business hours. Generate one short line telling the caller we are closed right now and inviting them to call back during business hours. Keep it to one sentence. Do not ask a question and do not invent the opening hours.",
      "text": ""
    },
    "fallback_message": {
      "mode": "default",
      "prompt": "This inbound call cannot be handled right now. Generate one short, apologetic line asking the caller to try again later. Keep it to one sentence. Do not ask a question and do not explain the technical reason.",
      "text": ""
    }
  }
}

A new agent is created as an unpublished draft (V0). It answers no calls until you publish a version and make it live — both explicit, both deliberate.

The smallest useful request

Everything you leave out takes the platform default: English (India), a Vocily AI voice, Sarvam-105B, Soniox speech recognition, the system messages, and the Default Analysis group.

{
  "name": "Acme COD Confirmation",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Confirm you are speaking with {{callee_name}}.\n2. Read back the order.\n3. Ask whether they will accept delivery.",
  "greeting": { "mode": "custom", "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon.", "delay_ms": 0 },
  "language": { "default": "hi-IN", "additional": ["en-IN"] }
}

Configuring the greeting

The same greeting controls apply to phone calls, browser Talk Test, and widget voice.

Field	Meaning
`greeting.mode`	`custom` (default) speaks `message`; `ai_generate` generates an opening from system instructions and prepared call context, without a separate greeting prompt.
`greeting.message`	Exact words for Custom mode. Must be nonblank when that mode is selected. Supports `{{variables}}`.
`greeting.delay_ms`	Integer milliseconds from 0 to 120000. Defaults to 0, which starts immediately. The dashboard displays seconds.

For an AI-generated opening, put any opening guidance in system_prompt and send:

{
  "greeting": {
    "mode": "ai_generate",
    "delay_ms": 2000
  }
}

If the caller speaks during the delay or while generation is in progress, the opening is skipped and the agent responds to the caller. Otherwise the selected greeting starts after the delay; AI generation begins then and adds model latency. Chat and WhatsApp do not use this opening timer. The saved Custom message is retained when switching modes, but is spoken only in Custom mode. The greeting uses the primary language and selected voice; there is no greeting.language field. See Greeting Message for the dashboard controls.

Writing the prompt

system_prompt is one field in the API and one System Prompt editor in the dashboard. Write the agent’s role, response style, and call flow there. Headings can make it easier to read, but they are optional and do not create separate fields. Four kinds of token do work inside it:

Token	Meaning
`{{order_id}}`	A variable reference. Declare custom variables in `variables` or the dashboard, then supply values per call in `POST /v1/calls`. `{{callee_name}}` and `{{callee_number}}` are system variables
`<confirm_order>`	Arms a tool. A tool exists but cannot be called until the prompt names it this way
`{{api.confirm_order.status}}`	A value a during-call tool returned
`{{pre.fetch_order.amount}}`	A value a before-the-call tool fetched before the call connected

Tools are built in the dashboard, not here. This body neither accepts nor returns them. Naming one the agent does not have is rejected with prompt_tool_reference_invalid, so create the tool on the agent’s Tools tab first, then write a prompt that arms it.

Picking values you cannot guess

Field	Where its values come from
`voice.voice_id`	List voices
`voice.model`	Only for a provider with more than one. The Vocily voice has one, `v2`, filled in when omitted
`model.model`	List models
`transcriber.model`	List transcribers
`language.default`	List languages
`numbers.inbound_phone`	List phone numbers
`numbers.inbound_whatsapp`	List WhatsApp numbers
`knowledge_base_ids`	List knowledge bases
`analysis_group_ids`	The analysis library
`conversation.background_sound`	`"none"` or one of the ten built-in ids listed in Update an agent

A voice provider must be able to speak language.default, or the agent is refused with voice_config_invalid — an agent that saved but could not speak would fail every call. TTS capabilities says which provider covers which language.

Channel instructions

system_prompt is the shared prompt. channel_prompts holds optional additions for phone_inbound, phone_outbound, web_voice, web_chat, and whatsapp. Only the matching addition is appended during a conversation. Each addition allows up to 65,536 characters.

{
  "system_prompt": "Help customers with their orders. Never invent order details.",
  "channel_prompts": {
    "phone_outbound": "Explain why you are calling before asking questions.",
    "whatsapp": "Keep messages short."
  }
}

To change channel additions later, see Update an agent.

Authorizations

Authorization

string

header

required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Body

application/json

Create an agent, fully configured, in one request.

name is the only required field — everything else takes the platform default, so the smallest useful body is a name, a prompt and a greeting. The agent is created as an unpublished draft (V0): it answers nothing until you publish a version and make it live, which stays two explicit calls.

name

string

required

What the agent is called. The one required field. Never spoken to a caller.

Required string length: 1 - 255

system_prompt

string | null

The agent's instructions. Naming a tool as <tool_name> here is what ARMS it: a tool the prompt never names is never called, and naming one the version does not have is refused on save.

Required string length: 1 - 65536

channel_prompts

Channel Prompts · object | null

Optional instructions added to system_prompt for the active channel. PATCH merges keys; null removes a channel. Blank uses shared instructions only.

Show child attributes

default_instructions

DefaultInstructions · object | null

Optional. Ready-made behaviour rules added before system_prompt. Send only the rules you want to change: the rest stay as they are. On create, anything you leave out takes its default.

Show child attributes

greeting

Greeting · object | null

What the agent says first.

Show child attributes

language

LanguageConfig · object | null

The language it opens in, which others it may switch to, and what triggers a switch.

Show child attributes

transcriber

Transcriber · object | null

Speech recognition. GET /v1/transcribers lists valid model values.

Show child attributes

model

Model · object | null

The LLM. GET /v1/models lists valid model and provider values.

Show child attributes

voice

Voice · object | null

Text to speech. GET /v1/voices lists valid voice_id values, and a voice that cannot speak language.default is refused on save.

Show child attributes

conversation

Conversation · object | null

Turn-taking, interruption and noise handling — how it behaves in the back-and-forth.

Show child attributes

call

CallSettings · object | null

Limits on the call itself: maximum duration, silence timeout, and what ends it.

Show child attributes

inbound

Inbound · object | null

Lines for inbound calls that cannot be handled normally.

Show child attributes

builtin_tools

BuiltinTools · object | null

The tools Vocily ships: end the call, hold, transfer, send a WhatsApp template. Each still has to be armed from the prompt.

Show child attributes

variables

RuntimeVariable · object[] | null

The {{placeholders}} the prompt and tools can use. Reference them namespaced as {{custom.your_key}}, never bare. Sending this list replaces the whole set.

Show child attributes

knowledge_base_ids

string[] | null

Which knowledge bases this agent can search, from GET /v1/knowledge-bases. This list IS the attachment — there is no separate attach endpoint, and sending it replaces the whole set. An id this workspace does not hold is refused, not ignored.

analysis_group_ids

string[] | null

Which custom-analysis groups run after each call, from GET /v1/custom-analysis. The list is the attachment, and an id this workspace does not hold is refused, not ignored.

memory

Memory · object | null

Whether the agent remembers callers between calls, and what it is allowed to remember.

Show child attributes

numbers

Numbers · object | null

Which phone and WhatsApp numbers this agent answers on. GET /v1/numbers and GET /v1/whatsapp/numbers list what you may use.

Show child attributes

Response

The created agent, at its V0 draft. It answers no calls until a version is published and made live.

One agent at one version — the response of every agent read, create and update.

A request body is this same object minus the read-only fields, so what you send is what you read back.

string

required

The agent's id. Stable across every version.

name

string

required

What the agent is called. Yours to choose; never spoken to a caller.

version

integer

required

Which version this body describes. 0-based, and the identity you use in /versions/{n} and ?version=.

version_id

string

required

This version's uuid. Pass it as agent_version_id on POST /v1/calls to pin a call to this exact version — that field takes a uuid, not a number.

is_published

boolean

required

True once frozen. A published version's configuration can never be edited again; branch a draft instead.

is_live

boolean

required

True if this is the version answering calls right now.

latest_version

integer

required

The highest version number this agent has.

document_revision

integer

required

This version's edit counter. Echo it back as If-Match on your next write and the write becomes a compare-and-set, so you cannot silently overwrite an edit made between your read and your write.

created_at

string<date-time>

required

When this version was created (UTC, ISO 8601).

updated_at

string<date-time>

required

When this version was last edited (UTC, ISO 8601).

live_version

integer | null

Which version is live, if any. null means the agent is off air and answers nothing.

label

string | null

Short name for this version, e.g. Shorter greeting. Editable even after publishing — it is metadata, not configuration.

notes

string | null

Longer free text about this version.

blocked_reasons

string[]

Why this version cannot be made live, if it cannot — e.g. it pins a model that has since been retired. Empty means it can go live.

system_prompt

string | null

The agent's instructions. Naming a tool as <tool_name> here is what ARMS it: a tool the prompt never names is never called, and naming one the version does not have is refused on save.

channel_prompts

Channel Prompts · object

Additional instructions appended to the shared system_prompt only in the matching conversation context.

Show child attributes

default_instructions

DefaultInstructions · object | null

Ready-made behaviour rules added before system_prompt. See each field. A rule that is missing or null is off.

Show child attributes

greeting

Greeting · object | null

What the agent says first.

Show child attributes

language

LanguageConfig · object | null

The language it opens in, which others it may switch to, and what triggers a switch.

Show child attributes

transcriber

Transcriber · object | null

Speech recognition. GET /v1/transcribers lists valid model values.

Show child attributes

model

Model · object | null

The LLM. GET /v1/models lists valid model and provider values.

Show child attributes

voice

Voice · object | null

Text to speech. GET /v1/voices lists valid voice_id values, and a voice that cannot speak language.default is refused on save.

Show child attributes

conversation

Conversation · object | null

Turn-taking, interruption and noise handling — how it behaves in the back-and-forth.

Show child attributes

call

CallSettings · object | null

Limits on the call itself: maximum duration, silence timeout, and what ends it.

Show child attributes

inbound

Inbound · object | null

Lines for inbound calls that cannot be handled normally.

Show child attributes

builtin_tools

BuiltinTools · object | null

The tools Vocily ships: end the call, hold, transfer, send a WhatsApp template. Each still has to be armed from the prompt.

Show child attributes

variables

RuntimeVariable · object[]

The {{placeholders}} the prompt and tools can use. Reference them namespaced as {{custom.your_key}}, never bare.

Show child attributes

knowledge_base_ids

string[]

analysis_group_ids

string[]

Which custom-analysis groups run after each call, from GET /v1/custom-analysis. Same rule as knowledge_base_ids: the list is the attachment, and an id this workspace does not hold is refused, not ignored.

memory

Memory · object | null

Whether the agent remembers callers between calls, and what it is allowed to remember.

Show child attributes

numbers

Numbers · object | null

Which phone and WhatsApp numbers this agent answers on. GET /v1/numbers and GET /v1/whatsapp/numbers list what you may use.

Show child attributes

dashboard_url

string | null

Deep link to this agent in the Vocily dashboard, for your own UI to link out to.

Create Agent

curl --request POST \
  --url https://api.vocily.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme COD Confirmation",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back the order.\n3. Ask whether they will accept delivery.",
  "greeting": {
    "mode": "custom",
    "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon.",
    "delay_ms": 0
  },
  "language": {
    "default": "hi-IN",
    "additional": [
      "en-IN"
    ]
  },
  "voice": {
    "provider": "vocily",
    "voice_id": "hi-IN-aman",
    "speed": 1
  },
  "model": {
    "model": "gpt-5.4-nano",
    "temperature": 0.4
  },
  "transcriber": {
    "provider": "sarvam",
    "model": "saaras:v4",
    "keywords": [
      "Acme",
      "COD"
    ]
  },
  "call": {
    "max_duration_minutes": 5,
    "recording_enabled": true
  },
  "builtin_tools": {
    "transfer_call": {
      "enabled": true,
      "numbers": [
        {
          "number": "+919876543210",
          "priority": 1,
          "start_hour": 9,
          "end_hour": 20,
          "timezone": "Asia/Kolkata"
        }
      ]
    }
  },
  "variables": [
    {
      "key": "order_id",
      "default_value": null
    }
  ]
}
'

import requests

url = "https://api.vocily.ai/v1/agents"

payload = {
    "name": "Acme COD Confirmation",
    "system_prompt": "## Agent Purpose
You confirm cash-on-delivery orders for Acme Store.

## Response Style
Warm, brief, one question at a time.

## Call Flow
1. Greet {{callee_name}}.
2. Read back the order.
3. Ask whether they will accept delivery.",
    "greeting": {
        "mode": "custom",
        "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon.",
        "delay_ms": 0
    },
    "language": {
        "default": "hi-IN",
        "additional": ["en-IN"]
    },
    "voice": {
        "provider": "vocily",
        "voice_id": "hi-IN-aman",
        "speed": 1
    },
    "model": {
        "model": "gpt-5.4-nano",
        "temperature": 0.4
    },
    "transcriber": {
        "provider": "sarvam",
        "model": "saaras:v4",
        "keywords": ["Acme", "COD"]
    },
    "call": {
        "max_duration_minutes": 5,
        "recording_enabled": True
    },
    "builtin_tools": { "transfer_call": {
            "enabled": True,
            "numbers": [
                {
                    "number": "+919876543210",
                    "priority": 1,
                    "start_hour": 9,
                    "end_hour": 20,
                    "timezone": "Asia/Kolkata"
                }
            ]
        } },
    "variables": [
        {
            "key": "order_id",
            "default_value": None
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Acme COD Confirmation',
    system_prompt: '## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back the order.\n3. Ask whether they will accept delivery.',
    greeting: {
      mode: 'custom',
      message: 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.',
      delay_ms: 0
    },
    language: {default: 'hi-IN', additional: ['en-IN']},
    voice: {provider: 'vocily', voice_id: 'hi-IN-aman', speed: 1},
    model: {model: 'gpt-5.4-nano', temperature: 0.4},
    transcriber: {provider: 'sarvam', model: 'saaras:v4', keywords: ['Acme', 'COD']},
    call: {max_duration_minutes: 5, recording_enabled: true},
    builtin_tools: {
      transfer_call: {
        enabled: true,
        numbers: [
          {
            number: '+919876543210',
            priority: 1,
            start_hour: 9,
            end_hour: 20,
            timezone: 'Asia/Kolkata'
          }
        ]
      }
    },
    variables: [{key: 'order_id', default_value: null}]
  })
};

fetch('https://api.vocily.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Acme COD Confirmation',
    'system_prompt' => '## Agent Purpose
You confirm cash-on-delivery orders for Acme Store.

## Response Style
Warm, brief, one question at a time.

## Call Flow
1. Greet {{callee_name}}.
2. Read back the order.
3. Ask whether they will accept delivery.',
    'greeting' => [
        'mode' => 'custom',
        'message' => 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.',
        'delay_ms' => 0
    ],
    'language' => [
        'default' => 'hi-IN',
        'additional' => [
                'en-IN'
        ]
    ],
    'voice' => [
        'provider' => 'vocily',
        'voice_id' => 'hi-IN-aman',
        'speed' => 1
    ],
    'model' => [
        'model' => 'gpt-5.4-nano',
        'temperature' => 0.4
    ],
    'transcriber' => [
        'provider' => 'sarvam',
        'model' => 'saaras:v4',
        'keywords' => [
                'Acme',
                'COD'
        ]
    ],
    'call' => [
        'max_duration_minutes' => 5,
        'recording_enabled' => true
    ],
    'builtin_tools' => [
        'transfer_call' => [
                'enabled' => true,
                'numbers' => [
                                [
                                                                'number' => '+919876543210',
                                                                'priority' => 1,
                                                                'start_hour' => 9,
                                                                'end_hour' => 20,
                                                                'timezone' => 'Asia/Kolkata'
                                ]
                ]
        ]
    ],
    'variables' => [
        [
                'key' => 'order_id',
                'default_value' => null
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocily.ai/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"Acme COD Confirmation\",\n  \"system_prompt\": \"## Agent Purpose\\nYou confirm cash-on-delivery orders for Acme Store.\\n\\n## Response Style\\nWarm, brief, one question at a time.\\n\\n## Call Flow\\n1. Greet {{callee_name}}.\\n2. Read back the order.\\n3. Ask whether they will accept delivery.\",\n  \"greeting\": {\n    \"mode\": \"custom\",\n    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\",\n    \"delay_ms\": 0\n  },\n  \"language\": {\n    \"default\": \"hi-IN\",\n    \"additional\": [\n      \"en-IN\"\n    ]\n  },\n  \"voice\": {\n    \"provider\": \"vocily\",\n    \"voice_id\": \"hi-IN-aman\",\n    \"speed\": 1\n  },\n  \"model\": {\n    \"model\": \"gpt-5.4-nano\",\n    \"temperature\": 0.4\n  },\n  \"transcriber\": {\n    \"provider\": \"sarvam\",\n    \"model\": \"saaras:v4\",\n    \"keywords\": [\n      \"Acme\",\n      \"COD\"\n    ]\n  },\n  \"call\": {\n    \"max_duration_minutes\": 5,\n    \"recording_enabled\": true\n  },\n  \"builtin_tools\": {\n    \"transfer_call\": {\n      \"enabled\": true,\n      \"numbers\": [\n        {\n          \"number\": \"+919876543210\",\n          \"priority\": 1,\n          \"start_hour\": 9,\n          \"end_hour\": 20,\n          \"timezone\": \"Asia/Kolkata\"\n        }\n      ]\n    }\n  },\n  \"variables\": [\n    {\n      \"key\": \"order_id\",\n      \"default_value\": null\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vocily.ai/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme COD Confirmation\",\n  \"system_prompt\": \"## Agent Purpose\\nYou confirm cash-on-delivery orders for Acme Store.\\n\\n## Response Style\\nWarm, brief, one question at a time.\\n\\n## Call Flow\\n1. Greet {{callee_name}}.\\n2. Read back the order.\\n3. Ask whether they will accept delivery.\",\n  \"greeting\": {\n    \"mode\": \"custom\",\n    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\",\n    \"delay_ms\": 0\n  },\n  \"language\": {\n    \"default\": \"hi-IN\",\n    \"additional\": [\n      \"en-IN\"\n    ]\n  },\n  \"voice\": {\n    \"provider\": \"vocily\",\n    \"voice_id\": \"hi-IN-aman\",\n    \"speed\": 1\n  },\n  \"model\": {\n    \"model\": \"gpt-5.4-nano\",\n    \"temperature\": 0.4\n  },\n  \"transcriber\": {\n    \"provider\": \"sarvam\",\n    \"model\": \"saaras:v4\",\n    \"keywords\": [\n      \"Acme\",\n      \"COD\"\n    ]\n  },\n  \"call\": {\n    \"max_duration_minutes\": 5,\n    \"recording_enabled\": true\n  },\n  \"builtin_tools\": {\n    \"transfer_call\": {\n      \"enabled\": true,\n      \"numbers\": [\n        {\n          \"number\": \"+919876543210\",\n          \"priority\": 1,\n          \"start_hour\": 9,\n          \"end_hour\": 20,\n          \"timezone\": \"Asia/Kolkata\"\n        }\n      ]\n    }\n  },\n  \"variables\": [\n    {\n      \"key\": \"order_id\",\n      \"default_value\": null\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Acme COD Confirmation\",\n  \"system_prompt\": \"## Agent Purpose\\nYou confirm cash-on-delivery orders for Acme Store.\\n\\n## Response Style\\nWarm, brief, one question at a time.\\n\\n## Call Flow\\n1. Greet {{callee_name}}.\\n2. Read back the order.\\n3. Ask whether they will accept delivery.\",\n  \"greeting\": {\n    \"mode\": \"custom\",\n    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\",\n    \"delay_ms\": 0\n  },\n  \"language\": {\n    \"default\": \"hi-IN\",\n    \"additional\": [\n      \"en-IN\"\n    ]\n  },\n  \"voice\": {\n    \"provider\": \"vocily\",\n    \"voice_id\": \"hi-IN-aman\",\n    \"speed\": 1\n  },\n  \"model\": {\n    \"model\": \"gpt-5.4-nano\",\n    \"temperature\": 0.4\n  },\n  \"transcriber\": {\n    \"provider\": \"sarvam\",\n    \"model\": \"saaras:v4\",\n    \"keywords\": [\n      \"Acme\",\n      \"COD\"\n    ]\n  },\n  \"call\": {\n    \"max_duration_minutes\": 5,\n    \"recording_enabled\": true\n  },\n  \"builtin_tools\": {\n    \"transfer_call\": {\n      \"enabled\": true,\n      \"numbers\": [\n        {\n          \"number\": \"+919876543210\",\n          \"priority\": 1,\n          \"start_hour\": 9,\n          \"end_hour\": 20,\n          \"timezone\": \"Asia/Kolkata\"\n        }\n      ]\n    }\n  },\n  \"variables\": [\n    {\n      \"key\": \"order_id\",\n      \"default_value\": null\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "00000005-0000-4000-8000-000000000005",
  "name": "Support line",
  "version": 0,
  "version_id": "00000006-0000-4000-8000-000000000006",
  "is_published": false,
  "is_live": false,
  "live_version": null,
  "latest_version": 0,
  "document_revision": 1,
  "label": null,
  "notes": null,
  "blocked_reasons": [],
  "created_at": "2026-09-16T19:38:03.767024Z",
  "updated_at": "2026-09-16T19:38:03.767024Z",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back order {{order_id}}.\n3. Ask whether they accept delivery.\n4. Close politely.",
  "greeting": {
    "message": "Hello! I am your AI voice agent. How can I help you today?",
    "prompt": "The voice call has connected and the caller has not spoken. Generate the opening greeting using the agent identity, purpose, response style, call flow and any prepared call information in the system instructions. Follow the configured primary language. Keep it to one or two short spoken sentences and at most one question. Do not invent caller details or completed actions. Do not output placeholders, tool calls, stage directions or an explanation. Return only the words to speak.",
    "mode": "custom",
    "delay_ms": 0
  },
  "language": {
    "default": "hi-IN",
    "additional": [
      "en-IN"
    ],
    "switch_trigger": "requested_or_auto"
  },
  "transcriber": {
    "provider": "sarvam",
    "model": "saaras:v4",
    "keywords": [
      "Acme",
      "COD"
    ],
    "fallback": {
      "provider": "deepgram",
      "model": "nova-3-general"
    }
  },
  "model": {
    "provider": "openai",
    "model": "gpt-5.4-nano",
    "temperature": 0.4,
    "max_tokens": 128,
    "fallback": {
      "provider": "gemini",
      "model": "gemini-3.5-flash-lite"
    }
  },
  "voice": {
    "provider": "vocily",
    "model": "v2",
    "voice_id": "hi-IN-aman",
    "speed": 1,
    "emotion": null,
    "fallback": {
      "provider": "sarvam",
      "model": "bulbul:v3",
      "voice_id": "shubh"
    }
  },
  "conversation": {
    "interruption_sensitivity": 0.5,
    "response_eagerness": 0.75,
    "noise_handling": {
      "mode": "standard",
      "level": 50
    },
    "silence_reminder": {
      "enabled": true,
      "seconds": 15
    }
  },
  "call": {
    "max_duration_minutes": 5,
    "end_on_silence_seconds": 25,
    "recording_enabled": true,
    "custom_analysis_enabled": true,
    "max_duration_message": {
      "mode": "default",
      "prompt": "The call has reached its maximum allowed duration and must end now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: the maximum call time has been reached, so the call is ending now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    },
    "end_on_silence_message": {
      "mode": "default",
      "prompt": "The caller has been silent for too long and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you could not hear anything on the line, so you are ending the call now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    }
  },
  "builtin_tools": {
    "end_call": {
      "enabled": true
    },
    "hold_call": {
      "enabled": true,
      "max_seconds": 90,
      "follow_up_seconds": 45,
      "acknowledgement_message": {
        "mode": "default",
        "prompt": "Write one short sentence to say to the caller as you start waiting, in the language you have been speaking — confirming you heard them and will wait. Do not ask a question and do not guess why they need the moment.",
        "text": ""
      },
      "follow_up_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away for a moment (they may be fetching a card, a document, or checking something). Generate one very short, gentle check-in in the same language and tone as the conversation above. Keep it to one short sentence, e.g. asking if they are back or reassuring them you are still on the line. Do not say goodbye. Do not say the call is ending. Do not repeat earlier content or ask new questions.",
        "text": ""
      },
      "timeout_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away, but they have not returned and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you waited but could not reach them, so you are ending the call; they are welcome to call back. Keep it to one short sentence. Do not ask a question.",
        "text": ""
      }
    },
    "transfer_call": {
      "enabled": true,
      "numbers": [
        {
          "number": "+919876543210",
          "priority": 1,
          "start_hour": 9,
          "end_hour": 20,
          "timezone": "Asia/Kolkata",
          "max_concurrent_calls": 1
        }
      ],
      "busy_message": {
        "mode": "default",
        "prompt": "You tried to transfer the caller to a human teammate, but nobody is available. Generate one short line in the same language and tone as the conversation above, saying the team is busy right now and asking them to try again a little later. Do not ask a question and do not promise a callback.",
        "text": ""
      },
      "intro_message": {
        "mode": "custom",
        "prompt": "You are about to transfer the caller to a human teammate. Generate one short line in the same language and tone as the conversation above, telling them to hold while you connect them. Do not ask a question and do not promise a specific person, a wait time or a callback.",
        "text": "Ek minute, main aapko connect karti hoon."
      }
    },
    "send_whatsapp_template": {
      "enabled": false,
      "templates": []
    }
  },
  "variables": [
    {
      "key": "callee_name",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    },
    {
      "key": "callee_number",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    }
  ],
  "knowledge_base_ids": [],
  "analysis_group_ids": [
    "00000007-0000-4000-8000-000000000007"
  ],
  "memory": {
    "enabled": true,
    "channels": [
      "outbound",
      "whatsapp"
    ],
    "allow_ai_labels": true,
    "label_instructions": "Record anything about the caller worth knowing next time, even when it is not one of the fields above: who they are, other ways to reach them, how they prefer to be dealt with, their standing with the business, or anything situational. Only what will still be true later; nothing said in passing.",
    "max_facts": 150,
    "transcript_turns": 12,
    "fields": [
      {
        "key": "delivery_pincode",
        "label": "Delivery PIN code",
        "type": "string",
        "enum_values": null,
        "description": "The PIN code the caller wants deliveries sent to.",
        "category": "contact"
      }
    ]
  },
  "numbers": null,
  "dashboard_url": "https://app.vocily.ai/agents/00000005-0000-4000-8000-000000000005",
  "inbound": {
    "business_hours_closed_message": {
      "mode": "default",
      "prompt": "This inbound call arrived outside business hours. Generate one short line telling the caller we are closed right now and inviting them to call back during business hours. Keep it to one sentence. Do not ask a question and do not invent the opening hours.",
      "text": ""
    },
    "fallback_message": {
      "mode": "default",
      "prompt": "This inbound call cannot be handled right now. Generate one short, apologetic line asking the caller to try again later. Keep it to one sentence. Do not ask a question and do not explain the technical reason.",
      "text": ""
    }
  }
}

Calls

Chats

Phone Numbers

Knowledge Bases

Files

Agents

Speech

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

Create an agent

The smallest useful request

Configuring the greeting

Writing the prompt

Picking values you cannot guess

Channel instructions

Authorizations

Body

Response