Create/Update Action

Create new actions or update existing actions for a voice agent. This endpoint allows you to configure webhooks, call transfers, holds, and other actions that the agent can perform during conversations.

Endpoint

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

Path Parameters

agent

string

required

The unique identifier of the voice agent. You can find this in your dashboard under Voice Agents.

Request Headers

Authorization

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Content-Type

string

required

Must be set to application/json

Request Body

node_id

string

required

Action node ID for workflow integration

name

string

required

Action name (max 255 characters)

description

string

required

Detailed description of what the action does

type

string

required

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

inputs

array

Array of input parameters for the action

integration

object

Integration configuration object

url

string

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

authorization_url

string

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

authorization_scheme

string

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

custom_headers

array

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

speak_on_send

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.

speak_on_receive

string

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

execution_mode

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)

hold_duration

integer

Hold duration in seconds (for hold actions).

transfer_to

string

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

current_status

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 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 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"
  }'

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

success

boolean

required

Indicates if the operation was successful.

message

string

required

Success message confirming the action was created or updated.

data

object

required

The created or updated action object.

Show Action Object

string

required

Unique identifier for the action.

name

string

required

The name of the action.

label

string

required

Display label for the action.

description

string

required

Detailed description of what the action does.

type

string

required

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

input_schema

array

required

Array of input parameters required for the action.

config

object

Configuration object for the action (if applicable).

action_trigger

object

Trigger conditions for the action (if applicable).

url

string

Webhook URL for webhook-type actions.

authorization_url

string

Authorization URL for webhook-type actions.

current_status

string

required

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

created_at

string

required

ISO 8601 timestamp when the action was created.

updated_at

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.

Best Practices

Test webhook URLs - Always test webhook URLs before creating actions
Use descriptive names - Give actions clear, descriptive names
Validate inputs - Ensure all required input parameters are properly defined
Handle errors gracefully - Implement proper error handling for action execution
Monitor action performance - Track how often actions are triggered and their success rates
Document action behavior - Provide clear descriptions of what each action does

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

Best Practices

Get Started

Concepts

API Reference

Guides

Documentation Index

​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

​Best Practices

​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

Best Practices

Related Endpoints