Create Agent

POST

api

vendors

{vendorId}

organizations

{organizationId}

agents

Create Agent

curl --request POST \
  --url https://app.phonebot.io:80/api/v1/vendors/{vendorId}/organizations/{organizationId}/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Sales Bot Alpha",
  "userValueTypes": {
    "customer_name": "STRING",
    "product_interest": "STRING",
    "order_id": "NUMBER"
  },
  "systemPromptTemplate": "You are a helpful sales assistant for ACME Corp. Your goal is to qualify leads.",
  "telephoneNumberId": "11223344-5566-7788-9900-aabbccddeeff",
  "llmAudioContentGenerationStrategyId": "abcdef01-2345-6789-abcd-ef0123456789",
  "extensions": [
    {
      "type": "crm_lookup_v1",
      "parameters": {
        "crm_system_url": "https://mycrm.example.com/api",
        "api_key_secret": "secret_crm_key"
      }
    }
  ],
  "callEventHooks": [
    {
      "type": "webhook_call_ended_v1",
      "parameters": {
        "target_url": "https://my.service.com/call_event",
        "auth_token": "bearer_abc123"
      }
    }
  ]
}
'

{
  "success": true,
  "timestamp": "2025-04-17T14:23:30Z",
  "message": "<string>",
  "data": {
    "id": "98765432-10fe-dcba-9876-543210fedcba",
    "name": "Sales Bot Alpha",
    "systemPromptTemplate": "You are a helpful sales assistant for ACME Corp. Your goal is to qualify leads.",
    "userValueTypes": {
      "customer_name": "STRING",
      "product_interest": "STRING",
      "order_id": "NUMBER"
    },
    "llmAudioContentGenerationStrategyId": "abcdef01-2345-6789-abcd-ef0123456789",
    "telephoneNumberId": "11223344-5566-7788-9900-aabbccddeeff",
    "extensions": [
      {
        "id": "deadbeef-cafe-babe-feed-faceabadb001",
        "name": "CRM Lookup",
        "type": "crm_lookup_v1",
        "parameters": {
          "crm_system_url": "https://mycrm.example.com/api",
          "api_key_secret": "secret_crm_key"
        }
      }
    ],
    "callEventHooks": [
      {
        "id": "b00bface-1337-badd-cafe-d00df00dcafe",
        "type": "webhook_call_ended_v1",
        "parameters": {
          "target_url": "https://my.service.com/call_event",
          "auth_token": "bearer_abc123"
        }
      }
    ]
  },
  "traceId": "<string>"
}

Path Parameters

vendorId

string

required

ID of the Vendor (UUID)

organizationId

string

required

ID of the Organization (UUID)

Body

application/json

Agent creation data

Data required to create a new Agent

name

string

required

Name of the agent.

Example:

"Sales Bot Alpha"

userValueTypes

object

required

Map defining user-specific value types the agent can handle.

Show child attributes

userValueTypes.{key}

enum<string>

Available options:

STRING,

STRING_REDACTED,

INTEGER,

FLOAT

Example:

{
  "customer_name": "STRING",
  "product_interest": "STRING",
  "order_id": "NUMBER"
}

systemPromptTemplate

string

required

Template for the system prompt used by the agent's underlying LLM.

Example:

"You are a helpful sales assistant for ACME Corp. Your goal is to qualify leads."

telephoneNumberId

string

required

ID of the telephone number assigned to this agent (UUID).

Example:

"11223344-5566-7788-9900-aabbccddeeff"

llmAudioContentGenerationStrategyId

string

required

ID of the LLM Audio Content Generation Strategy used by the agent (UUID).

Example:

"abcdef01-2345-6789-abcd-ef0123456789"

extensions

object[]

required

List of LLM extensions configured for this agent.

Show child attributes

extensions.type

string

required

Type identifier for the LLM extension.

Example:

"crm_lookup_v1"

extensions.parameters

object

required

Specific parameters for this extension instance (structure depends on the extension type).

Show child attributes

extensions.parameters.{key}

object

Example:

{
  "crm_system_url": "https://mycrm.example.com/api",
  "api_key_secret": "secret_crm_key"
}

callEventHooks

object[]

required

List of Call Event Hooks configured for this agent.

Show child attributes

callEventHooks.type

string

required

Type identifier for the call event hook.

Example:

"webhook_call_ended_v1"

callEventHooks.parameters

object

required

Specific parameters for this hook instance (structure depends on the hook type).

Show child attributes

callEventHooks.parameters.{key}

string

Example:

{
  "target_url": "https://my.service.com/call_event",
  "auth_token": "bearer_abc123"
}

Response

Agent successfully created

Standard API response wrapper

success

boolean

required

Indicates if the request was successful

Example:

true

timestamp

string<date-time>

required

Response timestamp in ISO-8601 format

Example:

"2025-04-17T14:23:30Z"

message

string

Human-readable message

data

object

Payload data object

Show child attributes

data.id

string

required

Unique identifier of the agent (UUID).

Example:

"98765432-10fe-dcba-9876-543210fedcba"

data.name

string

required

Name of the agent.

Example:

"Sales Bot Alpha"

data.systemPromptTemplate

string

required

Template for the system prompt used by the agent's underlying LLM.

Example:

"You are a helpful sales assistant for ACME Corp. Your goal is to qualify leads."

data.userValueTypes

object

required

Map defining user-specific value types the agent can handle.

Show child attributes

data.userValueTypes.{key}

enum<string>

Available options:

STRING,

STRING_REDACTED,

INTEGER,

FLOAT

Example:

{
  "customer_name": "STRING",
  "product_interest": "STRING",
  "order_id": "NUMBER"
}

data.llmAudioContentGenerationStrategyId

string

required

ID of the LLM Audio Content Generation Strategy used by the agent (UUID).

Example:

"abcdef01-2345-6789-abcd-ef0123456789"

data.telephoneNumberId

string

required

ID of the telephone number assigned to this agent (UUID).

Example:

"11223344-5566-7788-9900-aabbccddeeff"

data.extensions

object[]

required

List of LLM extensions configured for this agent.

Show child attributes

data.extensions.id

string

required

Unique identifier of the LLM extension instance (UUID).

Example:

"deadbeef-cafe-babe-feed-faceabadb001"

data.extensions.name

string

required

Name of the LLM extension.

Example:

"CRM Lookup"

data.extensions.type

string

required

Type identifier for the LLM extension.

Example:

"crm_lookup_v1"

data.extensions.parameters

object

required

Specific parameters for this extension instance (structure depends on the extension type).

Show child attributes

data.extensions.parameters.{key}

object

Example:

{
  "crm_system_url": "https://mycrm.example.com/api",
  "api_key_secret": "secret_crm_key"
}

data.callEventHooks

object[]

required

List of Call Event Hooks configured for this agent.

Show child attributes

data.callEventHooks.id

string

required

Unique identifier of the call event hook instance (UUID).

Example:

"b00bface-1337-badd-cafe-d00df00dcafe"

data.callEventHooks.type

string

required

Type identifier for the call event hook.

Example:

"webhook_call_ended_v1"

data.callEventHooks.parameters

object

required

Specific parameters for this hook instance (structure depends on the hook type).

Show child attributes

data.callEventHooks.parameters.{key}

string

Example:

{
  "target_url": "https://my.service.com/call_event",
  "auth_token": "bearer_abc123"
}

traceId

string

Correlation or trace ID

Get AgentRetrieves detailed information about a specific agent.

⌘I

Create Agent

curl --request POST \
  --url https://app.phonebot.io:80/api/v1/vendors/{vendorId}/organizations/{organizationId}/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Sales Bot Alpha",
  "userValueTypes": {
    "customer_name": "STRING",
    "product_interest": "STRING",
    "order_id": "NUMBER"
  },
  "systemPromptTemplate": "You are a helpful sales assistant for ACME Corp. Your goal is to qualify leads.",
  "telephoneNumberId": "11223344-5566-7788-9900-aabbccddeeff",
  "llmAudioContentGenerationStrategyId": "abcdef01-2345-6789-abcd-ef0123456789",
  "extensions": [
    {
      "type": "crm_lookup_v1",
      "parameters": {
        "crm_system_url": "https://mycrm.example.com/api",
        "api_key_secret": "secret_crm_key"
      }
    }
  ],
  "callEventHooks": [
    {
      "type": "webhook_call_ended_v1",
      "parameters": {
        "target_url": "https://my.service.com/call_event",
        "auth_token": "bearer_abc123"
      }
    }
  ]
}
'

{
  "success": true,
  "timestamp": "2025-04-17T14:23:30Z",
  "message": "<string>",
  "data": {
    "id": "98765432-10fe-dcba-9876-543210fedcba",
    "name": "Sales Bot Alpha",
    "systemPromptTemplate": "You are a helpful sales assistant for ACME Corp. Your goal is to qualify leads.",
    "userValueTypes": {
      "customer_name": "STRING",
      "product_interest": "STRING",
      "order_id": "NUMBER"
    },
    "llmAudioContentGenerationStrategyId": "abcdef01-2345-6789-abcd-ef0123456789",
    "telephoneNumberId": "11223344-5566-7788-9900-aabbccddeeff",
    "extensions": [
      {
        "id": "deadbeef-cafe-babe-feed-faceabadb001",
        "name": "CRM Lookup",
        "type": "crm_lookup_v1",
        "parameters": {
          "crm_system_url": "https://mycrm.example.com/api",
          "api_key_secret": "secret_crm_key"
        }
      }
    ],
    "callEventHooks": [
      {
        "id": "b00bface-1337-badd-cafe-d00df00dcafe",
        "type": "webhook_call_ended_v1",
        "parameters": {
          "target_url": "https://my.service.com/call_event",
          "auth_token": "bearer_abc123"
        }
      }
    ]
  },
  "traceId": "<string>"
}

Overview

Realtime

Assistants

Agents

Agent Tasks

Organizations

Plans

Vendors

Path Parameters

Body

Response