Create an agent

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": {
    "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon."
  },
  "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": { "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon." },
    "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: {message: 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.'},
    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' => [
        'message' => 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.'
    ],
    '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    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\"\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    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\"\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    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\"\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": {},
  "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"
        }
      ],
      "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 and someone will call them back on this number. Do not ask a question and do not promise a specific callback time.",
        "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, and that we will call back if the call drops. Do not ask a question and do not promise a specific person or wait time.",
        "text": "Ek minute, main aapko connect karti hoon."
      }
    },
    "send_whatsapp_template": {
      "enabled": false,
      "allowed_templates": [],
      "phone_number_id": ""
    }
  },
  "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": ""
    }
  }
}

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": {
    "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon."
  },
  "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": { "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon." },
    "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: {message: 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.'},
    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' => [
        'message' => 'Namaste {{callee_name}}, main Acme Store se bol rahi hoon.'
    ],
    '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    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\"\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    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\"\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    \"message\": \"Namaste {{callee_name}}, main Acme Store se bol rahi hoon.\"\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": {},
  "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"
        }
      ],
      "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 and someone will call them back on this number. Do not ask a question and do not promise a specific callback time.",
        "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, and that we will call back if the call drops. Do not ask a question and do not promise a specific person or wait time.",
        "text": "Ek minute, main aapko connect karti hoon."
      }
    },
    "send_whatsapp_template": {
      "enabled": false,
      "allowed_templates": [],
      "phone_number_id": ""
    }
  },
  "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: Hindi with English alongside it, a Vocily voice, gpt-5.4-nano, Sarvam speech recognition, the eleven 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. Greet {{callee_name}}.\n2. Read back the order.\n3. Ask whether they will accept delivery.",
  "greeting": { "message": "Namaste {{callee_name}}, main Acme Store se bol rahi hoon." },
  "language": { "default": "hi-IN", "additional": ["en-IN"] }
}

Writing the prompt

Three headings structure it, and they are the same three boxes the dashboard shows: ## Agent Purpose, ## Response Style, ## Call Flow. A prompt with no headings is treated as Agent Purpose. Four kinds of token do work inside it:

Token	Meaning
`{{order_id}}`	A variable. Keys you use here are added to the agent automatically; supply values per call in `POST /v1/calls`. `{{callee_name}}` and `{{callee_number}}` are always available
`<confirm_order>`	Arms a tool. A tool exists but cannot be called until the prompt names it this way
`\|\|confirm_order.status\|\|`	A value a during-call tool returned
`((fetch_order.amount))`	A value a pre-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

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.

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

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.

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.

Calls

Chats

Phone Numbers

Knowledge Bases

Agents

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

Create an agent

The smallest useful request

Writing the prompt

Picking values you cannot guess

Authorizations

Body

Response

​The smallest useful request

​Writing the prompt

​Picking values you cannot guess

Authorizations

Body

Response

The smallest useful request

Writing the prompt

Picking values you cannot guess