Skip to main content
POST
/
agents
Create Agent
curl --request POST \
  --url https://api.revring.ai/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "promptTemplate": "<string>",
  "sipTrunkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "active",
  "defaultVariables": {},
  "firstMessage": "<string>",
  "turnTimeoutSeconds": 0,
  "silenceEndCallTimeoutSeconds": 0,
  "maxConversationDurationSeconds": 2,
  "llmTemperature": 1,
  "timezone": "<string>",
  "language": "<string>",
  "preCallWebhookUrl": "<string>",
  "postCallWebhookUrl": "<string>",
  "endCallEnabled": true,
  "endCallRulesOverride": "<string>",
  "transferEnabled": true,
  "transferRoutes": [
    {
      "to_number": "<string>",
      "condition": "<string>"
    }
  ],
  "transferDescriptionOverride": "<string>",
  "voicemailEnabled": true,
  "voicemailAction": "hangup",
  "voicemailMessage": "<string>",
  "voiceId": "<string>",
  "voiceTemperature": 1,
  "voiceSpeed": 1,
  "runtimeConfig": {},
  "mode": "single_prompt",
  "flowDefinition": {},
  "testVariables": {},
  "llmReasoningEffort": "low",
  "disableInterruptions": true,
  "transferMode": "cold",
  "warmTransferConfig": {
    "holdMessage": "<string>",
    "holdMusicEnabled": true,
    "summaryPrompt": "<string>",
    "introMessage": "<string>"
  },
  "playKeypadTouchToneEnabled": true,
  "playKeypadTouchToneDescriptionOverride": "<string>",
  "knowledgeBaseRetrievalMode": "automatic",
  "knowledgeBaseChunks": 10,
  "knowledgeBaseSimilarityThreshold": 0.5
}
'
{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "active",
    "promptTemplate": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "sipTrunkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sipTrunk": {
      "friendlyName": "<string>"
    },
    "defaultVariables": {},
    "firstMessage": "<string>",
    "turnTimeoutSeconds": 123,
    "silenceEndCallTimeoutSeconds": 123,
    "maxConversationDurationSeconds": 123,
    "llmTemperature": 1,
    "timezone": "<string>",
    "language": "<string>",
    "preCallWebhookUrl": "<string>",
    "postCallWebhookUrl": "<string>",
    "endCallEnabled": true,
    "endCallRulesOverride": "<string>",
    "transferEnabled": true,
    "transferRoutes": [
      {
        "to_number": "<string>",
        "condition": "<string>"
      }
    ],
    "transferDescriptionOverride": "<string>",
    "voicemailEnabled": true,
    "voicemailAction": "hangup",
    "voicemailMessage": "<string>",
    "voiceId": "<string>",
    "voiceTemperature": 1,
    "voiceSpeed": 1,
    "runtimeConfig": {},
    "phoneNumbers": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "e164": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "customTools": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "webhookUrl": "<string>",
        "enabled": true,
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "schema": {},
        "httpMethod": "GET",
        "headers": [
          {
            "key": "<string>",
            "value": "<string>"
          }
        ],
        "queryParams": [
          {
            "key": "<string>",
            "value": "<string>"
          }
        ],
        "sendRawRequestBody": true
      }
    ],
    "mode": "single_prompt",
    "flowDefinition": {},
    "testVariables": {},
    "llmReasoningEffort": "low",
    "disableInterruptions": true,
    "transferMode": "cold",
    "warmTransferConfig": {
      "holdMessage": "<string>",
      "holdMusicEnabled": true,
      "summaryPrompt": "<string>",
      "introMessage": "<string>"
    },
    "playKeypadTouchToneEnabled": true,
    "playKeypadTouchToneDescriptionOverride": "<string>",
    "knowledgeBaseRetrievalMode": "automatic",
    "knowledgeBaseChunks": 10,
    "knowledgeBaseSimilarityThreshold": 0.5
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication. Generate API keys from the RevRing dashboard.

Body

application/json

Create a new AI voice agent

​
name
string
required

Agent name

Maximum string length: 128
​
promptTemplate
string
required

System prompt with {{variable}} placeholders

​
sipTrunkId
string<uuid> | null

SIP trunk ID to use for this agent's calls

​
status
enum<string>

Agent status (active = can receive calls, disabled = inactive)

Available options:
active,
disabled
​
defaultVariables
object

Default values for template variables

​
firstMessage
string

Agent's opening message

Maximum string length: 4000
​
turnTimeoutSeconds
integer

Seconds to wait for user response (-1 = no timeout)

Required range: x >= -1
​
silenceEndCallTimeoutSeconds
integer

Silence duration before ending call (-1 = no timeout)

Required range: x >= -1
​
maxConversationDurationSeconds
integer

Maximum call duration in seconds

Required range: x >= 1
​
llmTemperature
number

LLM temperature for response randomness (0-2)

Required range: 0 <= x <= 2
​
timezone
string

IANA timezone identifier (e.g., America/New_York)

​
language
string

Language code (e.g., en, es, fr)

​
preCallWebhookUrl
string<uri>

Webhook URL called before answering (optional)

​
postCallWebhookUrl
string<uri>

Webhook URL called after call ends (optional)

​
endCallEnabled
boolean

Allow agent to end calls

​
endCallRulesOverride
string

Custom instructions for ending calls

​
transferEnabled
boolean

Allow agent to transfer calls

​
transferRoutes
object[]

Available transfer destinations

​
transferDescriptionOverride
string

Custom transfer instructions

​
voicemailEnabled
boolean

Detect voicemail

​
voicemailAction
enum<string>

Action when voicemail detected

Available options:
hangup,
leave_message
​
voicemailMessage
string

Message to leave on voicemail

​
voiceId
string

Voice ID (copy from dashboard Voice Library)

​
voiceTemperature
number

Voice randomness (0-2)

Required range: 0 <= x <= 2
​
voiceSpeed
number

Speech speed (0.5-1.5)

Required range: 0.5 <= x <= 1.5
​
runtimeConfig
object

Advanced runtime configuration (optional)

​
mode
enum<string>

Agent mode (immutable after creation). Defaults to single_prompt.

Available options:
single_prompt,
conversation_flow
​
flowDefinition
object

Conversation flow definition (only used when mode is conversation_flow)

​
testVariables
object

Variables used for test calls initiated from the dashboard

​
llmReasoningEffort
enum<string>

Controls the reasoning effort of the language model. Higher values produce more thorough but slower responses.

Available options:
low,
medium,
high
​
disableInterruptions
boolean

When enabled, the agent will not be interrupted by the caller while speaking

​
transferMode
enum<string>

Transfer mode. cold disconnects the AI before connecting to the destination. warm keeps the AI on the line to introduce the caller.

Available options:
cold,
warm
​
warmTransferConfig
object

Configuration for warm transfers (only used when transferMode is warm)

​
playKeypadTouchToneEnabled
boolean

Enable the keypad input (DTMF) tool, allowing callers to press phone keys during the conversation

​
playKeypadTouchToneDescriptionOverride
string | null

Custom instructions for the keypad input tool behavior

Maximum string length: 2000
​
knowledgeBaseRetrievalMode
enum<string>

How the agent queries linked knowledge bases. automatic retrieves context on every turn. query_tool lets the agent decide when to search.

Available options:
automatic,
query_tool
​
knowledgeBaseChunks
integer

Number of text chunks to retrieve per knowledge base query

Required range: 1 <= x <= 20
​
knowledgeBaseSimilarityThreshold
number

Minimum similarity score for retrieved chunks (0-1). Higher values return only highly relevant results.

Required range: 0 <= x <= 1

Response

Agent created

​
data
object

AI Voice Agent configuration