# Request 1: Create webhook action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-456",
    "name": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "inputs": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "integration": {
      "id": "integration-uuid"
    },
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active"
  }'

// Request 1: Create webhook action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    node_id: "action-node-456",
    name: "Schedule Meeting",
    description: "Schedule a meeting with the customer",
    type: "webhook",
    inputs: [
      {
        name: "date",
        type: "string",
        required: true,
        description: "Meeting date"
      },
      {
        name: "time",
        type: "string",
        required: true,
        description: "Meeting time"
      }
    ],
    integration: {
      id: "integration-uuid"
    },
    url: "https://api.example.com/schedule",
    authorization_url: "https://api.example.com/auth",
    current_status: "active"
  })
});

const result = await response.json();
console.log(result);

{
  "success": true,
  "message": "Agent action updated successfully",
  "data": {
    "id": "action-uuid-1",
    "name": "Schedule Meeting",
    "label": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "input_schema": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "config": null,
    "action_trigger": null,
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:30:00Z"
  }
}

POST

api

agents

{agent_id}

actions

# Request 1: Create webhook action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-456",
    "name": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "inputs": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "integration": {
      "id": "integration-uuid"
    },
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active"
  }'

// Request 1: Create webhook action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    node_id: "action-node-456",
    name: "Schedule Meeting",
    description: "Schedule a meeting with the customer",
    type: "webhook",
    inputs: [
      {
        name: "date",
        type: "string",
        required: true,
        description: "Meeting date"
      },
      {
        name: "time",
        type: "string",
        required: true,
        description: "Meeting time"
      }
    ],
    integration: {
      id: "integration-uuid"
    },
    url: "https://api.example.com/schedule",
    authorization_url: "https://api.example.com/auth",
    current_status: "active"
  })
});

const result = await response.json();
console.log(result);

{
  "success": true,
  "message": "Agent action updated successfully",
  "data": {
    "id": "action-uuid-1",
    "name": "Schedule Meeting",
    "label": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "input_schema": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "config": null,
    "action_trigger": null,
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:30:00Z"
  }
}

Create/Update Action

Create new actions or update existing actions for a voice agent. Configures webhooks, call transfers, holds, and other actions that the agent can perform during conversations.

Endpoint

POST /api/v1/agents/{agent_id}/actions

Path parameters

string

required

The unique identifier of the voice agent.

Request headers

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

string

required

Must be set to application/json

Request body

string

required

Action node ID for workflow integration

string

required

Action name (max 255 characters)

string

required

What the action does

string

required

Action type. Options: webhook, transfer, hold, external.

array

Array of input parameters for the action

object

Integration configuration object

string

Webhook URL (must be a valid URL — used by webhook actions).

string

Authorization URL (must be a valid URL — used by webhook actions when the target requires a separate authorization endpoint).

string

Authorization scheme used when calling url. Options: none, bearer, basic, api_key, custom. Default: none.

array

Array of custom HTTP headers to send with the webhook request. Each item is { "key": "Header-Name", "value": "header-value" }.

string

Phrase the agent will say when the webhook is triggered (before the call to url). Useful to keep the conversation natural while the integration runs.

string

Phrase the agent will say after the webhook responds successfully. The webhook response can be referenced via template variables.

string

Defines when the action runs. Options:

during_call (default) — webhook runs during the conversation, response is consumed by the agent
post_call — webhook runs after the call ends (only valid for external action type)

integer

Hold duration in seconds (for hold actions).

string

Transfer destination phone number in E.164 format (for transfer actions).

string

Action status. Options: active, inactive. Default: active.

Example requests

# Request 1: Create webhook action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-456",
    "name": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "inputs": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "integration": {
      "id": "integration-uuid"
    },
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active"
  }'

// Request 1: Create webhook action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    node_id: "action-node-456",
    name: "Schedule Meeting",
    description: "Schedule a meeting with the customer",
    type: "webhook",
    inputs: [
      {
        name: "date",
        type: "string",
        required: true,
        description: "Meeting date"
      },
      {
        name: "time",
        type: "string",
        required: true,
        description: "Meeting time"
      }
    ],
    integration: {
      id: "integration-uuid"
    },
    url: "https://api.example.com/schedule",
    authorization_url: "https://api.example.com/auth",
    current_status: "active"
  })
});

const result = await response.json();
console.log(result);

# Request 2: Create transfer action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-789",
    "name": "Transfer Call",
    "description": "Transfer the call to a human agent",
    "type": "transfer",
    "inputs": [
      {
        "name": "transfer_to",
        "type": "string",
        "required": true,
        "description": "Transfer to",
        "value": "+1234567890"
      }
    ],
    "transfer_to": "+1234567890",
    "current_status": "active"
  }'

// Request 2: Create transfer action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    node_id: "action-node-789",
    name: "Transfer Call",
    description: "Transfer the call to a human agent",
    type: "transfer",
    inputs: [
      {
        name: "transfer_to",
        type: "string",
        required: true,
        description: "Transfer to",
        value: "+1234567890"
      }
    ],
    transfer_to: "+1234567890",
    current_status: "active"
  })
});

const result = await response.json();
console.log(result);

# Request 3: Create hold action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-101",
    "name": "Put Call on Hold",
    "description": "Put the current call on hold for a specified duration",
    "type": "hold",
    "inputs": [
      {
        "name": "hold_duration",
        "type": "integer",
        "required": true,
        "description": "Hold duration in seconds",
        "value": 30
      }
    ],
    "hold_duration": 30,
    "current_status": "active"
  }'

// Request 3: Create hold action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    node_id: "action-node-101",
    name: "Put Call on Hold",
    description: "Put the current call on hold for a specified duration",
    type: "hold",
    inputs: [
      {
        name: "hold_duration",
        type: "integer",
        required: true,
        description: "Hold duration in seconds",
        value: 30
      }
    ],
    hold_duration: 30,
    current_status: "active"
  })
});

const result = await response.json();
console.log(result);

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Agent action updated successfully",
  "data": {
    "id": "action-uuid-1",
    "name": "Schedule Meeting",
    "label": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "input_schema": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "config": null,
    "action_trigger": null,
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:30:00Z"
  }
}

Response fields

boolean

required

Indicates if the operation was successful.

string

required

Success message confirming the action was created or updated.

object

required

The created or updated action object.

Show Action Object

string

required

Unique identifier for the action.

string

required

The name of the action.

string

required

Display label for the action.

string

required

What the action does.

string

required

Type of action. Options: webhook, transfer, hold, external.

array

required

Array of input parameters required for the action.

object

Configuration object for the action (if applicable).

object

Trigger conditions for the action (if applicable).

string

Webhook URL for webhook-type actions.

string

Authorization URL for webhook-type actions.

string

required

Current status of the action. Options: active, inactive.

string

required

ISO 8601 timestamp when the action was created.

string

required

ISO 8601 timestamp when the action was last updated.

Error responses

Validation Error (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "type": [
      "The selected type is invalid."
    ],
    "url": [
      "The url must be a valid URL."
    ],
    "authorization_url": [
      "The authorization url must be a valid URL."
    ]
  }
}

404 Not Found

{
  "success": false,
  "message": "Agent not found"
}

401 Unauthorized

{
  "success": false,
  "message": "Unauthenticated."
}

403 Forbidden

{
  "success": false,
  "message": "You are not authorized to create actions for this agent."
}

500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

Error codes

Code	Description	HTTP Status
`AGENT_NOT_FOUND`	Specified agent does not exist	404
`INVALID_TOKEN`	Authentication token is invalid or missing	401
`UNAUTHORIZED`	User does not have permission to create actions for this agent	403
`VALIDATION_ERROR`	Request data validation failed	422
`SERVER_ERROR`	Internal server error occurred	500

Important notes

Agent status will be set to draft. After creating or updating actions, the agent will be automatically set to “draft” status and will need to be published again to become active.

Action types have different requirements. Different action types (webhook, transfer, hold) require different parameters and configurations.

URL validation. For webhook actions, both url and authorization_url must be valid URLs.

List Actions: GET /api/v1/agents/{agent_id}/actions
Delete Action: DELETE /api/v1/agents/{agent_id}/actions/{action_id}
Get Agent: GET /api/v1/agents/{agent_id}
Publish Agent: POST /api/v1/agents/{agent_id}/publish

Get Started

Concepts

API Reference

Guides

Create/Update Action

Create/Update Action

Endpoint

Path parameters

Request headers

Request body

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

Validation Error (422)

404 Not Found

401 Unauthorized

403 Forbidden

500 Server Error

Error codes

Important notes

​Create/Update Action

​Endpoint

​Path parameters

​Request headers

​Request body

​Example requests

​Response

​Success Response (200 OK)

​Response fields

​Error responses

​Validation Error (422)

​404 Not Found

​401 Unauthorized

​403 Forbidden

​500 Server Error

​Error codes

​Important notes

​Related endpoints

Create/Update Action

Endpoint

Path parameters

Request headers

Request body

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

Validation Error (422)

404 Not Found

401 Unauthorized

403 Forbidden

500 Server Error

Error codes

Important notes

Related endpoints