Skip to main content
POST
/
v1
/
agents
Create agent
curl --request POST \
  --url https://api.callrounded.com/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "name": "My first agent",
  "language": "en",
  "initial_message": "Hello, how can I help you today?",
  "initial_message_delay": 0,
  "max_call_duration": 300,
  "presence_check_phrases": [
    "Allo, vous êtes là ?",
    "Pouvez-vous répéter s'\''il vous plaît ?"
  ],
  "presence_check_idle_threshold": 10,
  "presence_check_max_times": 1,
  "base_prompt": "You are a helpful assistant",
  "voice": {
    "provider": "openai",
    "name": "Clara",
    "instructions": "Warm, empathetic, friendly",
    "speed": 0.5
  },
  "states": [
    {
      "name": "appointment_booking",
      "prompt": "You are a helpful assistant",
      "llm": {
        "model": "gpt-4o",
        "temperature": 0.5,
        "provider": "azure_openai"
      },
      "tools": [
        {
          "description": "Wait for 2 seconds",
          "type": "wait"
        },
        {
          "description": "Hang up the call",
          "filler_sentence": "Goodbye!",
          "type": "hang_up"
        },
        {
          "description": "Transfer the call to the next available assistant",
          "filler_sentence": "I'\''m transferring you to the next available assistant...",
          "type": "transfer_call"
        },
        {
          "description": "Leave a voicemail message",
          "filler_sentence": "I tried to call you but you didn'\''t answer. Please call me back at 1234567890",
          "type": "leave_voicemail_message"
        },
        {
          "content_type": "url_params",
          "description": "Get the availability of the requested assistant by using its name",
          "filler_sentence": "I'\''m checking the availability of the requested assistant...",
          "headers": [
            {
              "description": "The API key to use to call the custom function",
              "name": "Authorization",
              "value": "Bearer 123"
            }
          ],
          "method": "GET",
          "parameters": [
            {
              "description": "The name of the assistant to check the availability of",
              "name": "assistant_name",
              "type": "string"
            }
          ],
          "response_mapping": [
            {
              "destination_variable": "assistant_availability",
              "json_path_to_data": "$.availability"
            }
          ],
          "type": "custom_function",
          "url": "https://api.example.com/availability"
        }
      ],
      "transitions": [
        {
          "condition": "User provides valid input",
          "destination_state_name": "next_state_name",
          "filler_sentence": "I'\''m sorry, I didn'\''t catch that. Can you please repeat?"
        }
      ],
      "variables": [
        {
          "description": "The variable'\''s description",
          "extraction_instructions": "The instructions for the variable extraction",
          "name": "variable_name",
          "type": "string"
        }
      ],
      "x_position": -401.1747211895911,
      "y_position": 264.2527881040892,
      "features": {
        "entity_detection": true
      }
    }
  ],
  "initial_state_name": "<string>",
  "llm": {
    "model": "gpt-4o",
    "temperature": 0.5,
    "provider": "azure_openai"
  },
  "transcriber": {
    "provider": "azure"
  },
  "secure_recording_urls": true,
  "interruptions": true,
  "interruptions_sensitivity": "high",
  "webhook_url": "https://webhook.site/123e4567-e89b-12d3-a456-426614174000",
  "webhook_subscriptions": [
    "event_variable_value_updated",
    "event_all_variables_resolved"
  ],
  "custom_vocabulary": [
    "super",
    "basta",
    "bravo",
    "gmail.com"
  ]
}'
{
  "message": "<string>",
  "data": {
    "name": "My first agent",
    "language": "en",
    "initial_message": "Hello, how can I help you today?",
    "initial_message_delay": 0,
    "max_call_duration": 300,
    "presence_check_phrases": [
      "Allo, vous êtes là ?",
      "Pouvez-vous répéter s'il vous plaît ?"
    ],
    "presence_check_idle_threshold": 10,
    "presence_check_max_times": 1,
    "base_prompt": "You are a helpful assistant",
    "voice": {
      "provider": "openai",
      "name": "Clara",
      "instructions": "Warm, empathetic, friendly",
      "speed": 0.5
    },
    "states": [
      {
        "name": "appointment_booking",
        "prompt": "You are a helpful assistant",
        "llm": {
          "model": "gpt-4o",
          "temperature": 0.5,
          "provider": "azure_openai"
        },
        "tools": [
          {
            "description": "Wait for 2 seconds",
            "type": "wait"
          },
          {
            "description": "Hang up the call",
            "filler_sentence": "Goodbye!",
            "type": "hang_up"
          },
          {
            "description": "Transfer the call to the next available assistant",
            "filler_sentence": "I'm transferring you to the next available assistant...",
            "type": "transfer_call"
          },
          {
            "description": "Leave a voicemail message",
            "filler_sentence": "I tried to call you but you didn't answer. Please call me back at 1234567890",
            "type": "leave_voicemail_message"
          },
          {
            "content_type": "url_params",
            "description": "Get the availability of the requested assistant by using its name",
            "filler_sentence": "I'm checking the availability of the requested assistant...",
            "headers": [
              {
                "description": "The API key to use to call the custom function",
                "name": "Authorization",
                "value": "Bearer 123"
              }
            ],
            "method": "GET",
            "parameters": [
              {
                "description": "The name of the assistant to check the availability of",
                "name": "assistant_name",
                "type": "string"
              }
            ],
            "response_mapping": [
              {
                "destination_variable": "assistant_availability",
                "json_path_to_data": "$.availability"
              }
            ],
            "type": "custom_function",
            "url": "https://api.example.com/availability"
          }
        ],
        "transitions": [
          {
            "condition": "User provides valid input",
            "destination_state_name": "next_state_name",
            "filler_sentence": "I'm sorry, I didn't catch that. Can you please repeat?"
          }
        ],
        "variables": [
          {
            "description": "The variable's description",
            "extraction_instructions": "The instructions for the variable extraction",
            "name": "variable_name",
            "type": "string"
          }
        ],
        "x_position": -401.1747211895911,
        "y_position": 264.2527881040892,
        "features": {
          "entity_detection": true
        }
      }
    ],
    "initial_state_name": "<string>",
    "llm": {
      "model": "gpt-4o",
      "temperature": 0.5,
      "provider": "azure_openai"
    },
    "transcriber": {
      "provider": "azure"
    },
    "secure_recording_urls": true,
    "interruptions": true,
    "interruptions_sensitivity": "high",
    "webhook_url": "https://webhook.site/123e4567-e89b-12d3-a456-426614174000",
    "webhook_subscriptions": [
      "event_variable_value_updated",
      "event_all_variables_resolved"
    ],
    "custom_vocabulary": [
      "super",
      "basta",
      "bravo",
      "gmail.com"
    ],
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 1,
    "variables": [
      {
        "name": "name",
        "type": "string",
        "description": "The name of the customer",
        "extraction_instructions": "Extract the name of the customer"
      }
    ]
  },
  "error": {
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "message": "An error occurred while processing your request",
    "status": 400,
    "type": "generic_error"
  },
  "status": 200
}

Authorizations

​
X-Api-Key
string
header
required

The API Key created in Rounded Studio.

Body

application/json
​
name
string
required

The name of the agent

Required string length: 1 - 100
Examples:

"My first agent"

​
language
enum<string>
required

The language of the agent, expressed as a BCP 47 language tag by using its ISO 639-1 code (e.g. 'en', 'fr', 'es'). For French, regional variants using a region code from ISO 3166-1 are also supported (e.g. 'fr-BE').

Available options:
en,
fr,
fr-FR,
fr-BE,
fr-CA,
es,
de,
it,
nl,
pl,
ar,
pt,
el,
hr,
zh
Examples:

"en"

"fr"

"fr-BE"

"es"

​
initial_message
string | null
default:Bonjour ! Que puis-je faire pour vous ?

The initial message of the agent

Required string length: 1 - 1000
Examples:

"Hello, how can I help you today?"

​
initial_message_delay
number | null
default:0

The delay of the initial message in seconds

Required range: 0 <= x <= 5
Examples:

0

​
max_call_duration
number | null
default:1800

The maximum duration of the call in seconds

Examples:

300

​
presence_check_phrases
string[] | null

A series of phrases that the agent will say to re-engage the interlocutor after a period of silence. The phrases should be in the same language as the agent.

Examples:
[
  "Allo, vous êtes là ?",
  "Pouvez-vous répéter s'il vous plaît ?"
]
​
presence_check_idle_threshold
integer | null
default:15

The number of seconds of silence after which the agent will say the presence check phrases

Required range: 3 <= x <= 120
Examples:

10

​
presence_check_max_times
integer | null
default:10

The maximum number of times the agent will say the presence check phrases

Required range: 1 <= x <= 100
Examples:

1

​
base_prompt
string | null

The base prompt of the agent

Maximum length: 100000
Examples:

"You are a helpful assistant"

​
voice
object | null

The voice of the agent

  • AgentCreateOpenAIVoiceConfigurationApiRequest
  • AgentCreateElevenLabsVoiceConfigurationApiRequest
  • AgentCreateCartesiaVoiceConfigurationApiRequest
  • AgentCreateAzureVoiceConfigurationApiRequest
​
states
AgentCreateStatesApiRequest · object[] | null
​
initial_state_name
string | null
​
llm
object | null
​
transcriber
object | null
​
secure_recording_urls
boolean | null
default:true

Whether to secure the recording URLs

Examples:

true

​
interruptions
boolean | null
default:false

Whether to allow interruptions

Examples:

true

​
interruptions_sensitivity
enum<string> | null
default:high

The sensitivity of the interruptions

Available options:
high,
medium,
low
Examples:

"high"

​
webhook_url
string | null

The webhook URL of the agent

Examples:

"https://webhook.site/123e4567-e89b-12d3-a456-426614174000"

​
webhook_subscriptions
enum<string>[] | null

The webhook subscriptions of the agent

Examples:
[
  "event_variable_value_updated",
  "event_all_variables_resolved"
]
​
custom_vocabulary
string[] | null

The custom vocabulary of the agent, used mainly to improve transcription accuracy.

Examples:
["super", "basta", "bravo", "gmail.com"]

Response

Successfully created agent

​
message
string
required
​
data
object
required
​
error
object | null
Example:
{
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "message": "An error occurred while processing your request",
  "status": 400,
  "type": "generic_error"
}
​
status
integer
default:200

HTTP status code of the response.