Skip to main content
POST
/
api
/
v1
/
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"
  }'

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

​
agent
string
required
The unique identifier of the voice agent.

​
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
What the action does
​
type
string
required
Action type. Options: webhook, transfer, hold, external.
​
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.

​
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

CodeDescriptionHTTP Status
AGENT_NOT_FOUNDSpecified agent does not exist404
INVALID_TOKENAuthentication token is invalid or missing401
UNAUTHORIZEDUser does not have permission to create actions for this agent403
VALIDATION_ERRORRequest data validation failed422
SERVER_ERRORInternal server error occurred500

​
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