# Request 1: List all actions for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: List all actions for an agent
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"success": true,
"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-15T10:30:00Z"
},
{
"id": "action-uuid-2",
"name": "Transfer Call",
"label": "Transfer Call",
"description": "Transfer the call to a human agent",
"type": "transfer",
"input_schema": [
{
"name": "transfer_to",
"type": "string",
"required": true,
"description": "Transfer to",
"value": "+1234567890"
}
],
"config": null,
"action_trigger": null,
"url": null,
"authorization_url": null,
"current_status": "active",
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z"
},
{
"id": "action-uuid-3",
"name": "Put Call on Hold",
"label": "Put Call on Hold",
"description": "Put the current call on hold for a specified duration",
"type": "hold",
"input_schema": [
{
"name": "hold_duration",
"type": "integer",
"required": true,
"description": "Hold duration in seconds",
"value": 30
}
],
"config": null,
"action_trigger": null,
"url": null,
"authorization_url": null,
"current_status": "inactive",
"created_at": "2024-01-15T12:00:00Z",
"updated_at": "2024-01-15T12:00:00Z"
}
]
}
Actions
List Actions
Retrieve a list of actions for a specific voice agent
GET
/
api
/
v1
/
agents
/
{agent_id}
/
actions
# Request 1: List all actions for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: List all actions for an agent
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"success": true,
"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-15T10:30:00Z"
},
{
"id": "action-uuid-2",
"name": "Transfer Call",
"label": "Transfer Call",
"description": "Transfer the call to a human agent",
"type": "transfer",
"input_schema": [
{
"name": "transfer_to",
"type": "string",
"required": true,
"description": "Transfer to",
"value": "+1234567890"
}
],
"config": null,
"action_trigger": null,
"url": null,
"authorization_url": null,
"current_status": "active",
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z"
},
{
"id": "action-uuid-3",
"name": "Put Call on Hold",
"label": "Put Call on Hold",
"description": "Put the current call on hold for a specified duration",
"type": "hold",
"input_schema": [
{
"name": "hold_duration",
"type": "integer",
"required": true,
"description": "Hold duration in seconds",
"value": 30
}
],
"config": null,
"action_trigger": null,
"url": null,
"authorization_url": null,
"current_status": "inactive",
"created_at": "2024-01-15T12:00:00Z",
"updated_at": "2024-01-15T12:00:00Z"
}
]
}
List Actions
Retrieve all actions associated with a specific voice agent. This endpoint returns a list of webhooks, call transfers, holds, and other actions that the agent can perform during conversations.Endpoint
GET /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_hereExample requests
# Request 1: List all actions for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: List all actions for an agent
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# Request 2: List actions with error handling
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-w "\nHTTP Status: %{http_code}\n"
// Request 2: List actions with error handling
try {
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
console.log('Actions:', result.data);
} catch (error) {
console.error('Error fetching actions:', error);
}
Response
Success Response (200 OK)
{
"success": true,
"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-15T10:30:00Z"
},
{
"id": "action-uuid-2",
"name": "Transfer Call",
"label": "Transfer Call",
"description": "Transfer the call to a human agent",
"type": "transfer",
"input_schema": [
{
"name": "transfer_to",
"type": "string",
"required": true,
"description": "Transfer to",
"value": "+1234567890"
}
],
"config": null,
"action_trigger": null,
"url": null,
"authorization_url": null,
"current_status": "active",
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z"
},
{
"id": "action-uuid-3",
"name": "Put Call on Hold",
"label": "Put Call on Hold",
"description": "Put the current call on hold for a specified duration",
"type": "hold",
"input_schema": [
{
"name": "hold_duration",
"type": "integer",
"required": true,
"description": "Hold duration in seconds",
"value": 30
}
],
"config": null,
"action_trigger": null,
"url": null,
"authorization_url": null,
"current_status": "inactive",
"created_at": "2024-01-15T12:00:00Z",
"updated_at": "2024-01-15T12:00:00Z"
}
]
}
Response fields
boolean
required
Indicates if the operation was successful.
array
required
Array of action objects associated with the agent.
Show 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
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 access this agent's actions."
}
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 access this agent | 403 |
SERVER_ERROR | Internal server error occurred | 500 |
Important notes
Empty response is normal. If an agent has no actions configured, the response will be an empty array
[] rather than an error.Status filtering. The response includes both active and inactive actions. You can filter by
current_status on the client side if needed.Action types vary. Different action types (webhook, transfer, hold) have different properties and configurations.
Related endpoints
- Create/Update Action:
POST /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} - List Agents:
GET /api/v1/agents
Was this page helpful?