Create agent

Create a new agent with the specified configuration. The agent can be used to handle phone and web calls. The response includes headers about rate limiting.

POST /v1/agents

Create agent

cURL

curl --request POST \
  --url https://api.callrounded.com/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data @- <<EOF
{
  "name": "<string>",
  "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": {
    "name": "Alloy",
    "provider": "openai",
    "instructions": "Warm, empathetic, friendly",
    "speed": 1
  },
  "states": [
    {
      "name": "<string>",
      "prompt": "<string>",
      "llm": {
        "model": "gpt-3.5-turbo",
        "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-3.5-turbo",
    "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"
  ]
}
EOF

201

Example

{
  "message": "<string>",
  "data": {
    "name": "<string>",
    "language": "en",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "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": {
      "name": "Alloy",
      "provider": "openai",
      "instructions": "Warm, empathetic, friendly",
      "speed": 1
    },
    "states": [
      {
        "name": "<string>",
        "prompt": "<string>",
        "llm": {
          "model": "gpt-3.5-turbo",
          "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-3.5-turbo",
      "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"
    ],
    "version": 1,
    "variables": [
      {
        "name": "<string>",
        "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.

• You can create it by going to the "API Keys" settings of your profile.
• Need help? You can email us at [e-mail] or join our Discord community.

Body

application/json

name · string · required

The name of the agent

Required string length: 1 - 100

Example:

"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

Maximum string length: 1000

Example:

"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

Example:

0

max_call_duration · number | null · default: 1800

The maximum duration of the call in seconds

Example:

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.

Example:

[
  "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

Example:

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

Example:

1

base_prompt · string | null

The base prompt of the agent

Maximum string length: 100000

Example:

"You are a helpful assistant"

voice · AgentCreateOpenAIVoiceConfigurationApiRequest · object

The voice of the agent

AgentCreateOpenAIVoiceConfigurationApiRequest

AgentCreateElevenLabsVoiceConfigurationApiRequest

AgentCreateCartesiaVoiceConfigurationApiRequest

AgentCreateAzureVoiceConfigurationApiRequest

AgentCreateGoogleVoiceConfigurationApiRequest

Show child attributes

states · AgentCreateStatesApiRequest · object[] | null

Show child attributes

initial_state_name · string | null

llm · AgentCreateLLMConfigurationApiRequest · object

Show child attributes

transcriber · AgentCreateTranscriberConfigurationApiRequest · object

Show child attributes

secure_recording_urls · boolean | null · default: true

Whether to secure the recording URLs

Example:

true

interruptions · boolean | null · default: false

Whether to allow interruptions

Example:

true

interruptions_sensitivity · enum<string> | null · default: high

The sensitivity of the interruptions

Available options: high, medium, low

Example:

"high"

webhook_url · string | null

The webhook URL of the agent

Example:

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

webhook_subscriptions · enum<string>[] | null

The webhook subscriptions of the agent

Available options: event_variable_value_updated, event_all_variables_resolved, event_call_status_updated, event_call_recording_status_updated, event_call_answer_type_updated, event_task_transition, event_transcript, event_transcript_complete, event_phone_call_connected, event_phone_call_ended, event_phone_call_did_not_connect, event_web_call_connected, event_web_call_ended, event_recording, event_action, event_synthesizer_consumption, event_post_call, event_pipedream_connection

Example:

[
  "event_variable_value_updated",
  "event_all_variables_resolved"
]

custom_vocabulary · string[] | null

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

Example:

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

Response

201

application/json

Successfully created agent

message · string · required

data · AgentGetApiResponseData · object · required

Show child attributes

error · ApiResponseError · object

Show child attributes

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.