# Get Action by ID GET https://services.leadconnectorhq.com/conversation-ai/agents/{agentId}/actions/{actionId} Retrieves detailed information about a specific action using its unique identifier. Returns the action configuration, associated agents, and performance metrics. Supports both classic actions and the `customApi` ("API Call") type. ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `conversation-ai.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `actionId` | string | Yes | The unique identifier of the action ID Attached to the agent | | `agentId` | string | Yes | The unique identifier of the AI agent | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "LeadConnector API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/conversation-ai/agents/{agentId}/actions/{actionId}": { "get": { "summary": "Get Action by ID", "operationId": "getActionById", "description": "Retrieves detailed information about a specific action using its unique identifier. Returns the action configuration, associated agents, and performance metrics. Supports both classic actions and the `customApi` (\"API Call\") type.", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } }, { "name": "actionId", "required": true, "in": "path", "description": "The unique identifier of the action ID Attached to the agent", "schema": { "example": "6578278e879ad2646715ba9c", "type": "string" } }, { "name": "agentId", "required": true, "in": "path", "description": "The unique identifier of the AI agent", "schema": { "example": "ve9EPM428h8vShlRW1KT", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fetchActionDetailsResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO" } } } } }, "security": [ { "bearer": [ "conversation-ai.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "fetchActionDetailsResponseDTO": { "type": "object", "properties": { "data": { "description": "Action details (classic action or customApi API Call action)", "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "example": "actionId123", "description": "Unique identifier for the action" }, "name": { "type": "string", "example": "Trigger Workflow", "description": "Name of the action" }, "type": { "type": "string", "enum": [ "triggerWorkflow", "updateContactField", "appointmentBooking", "stopBot", "humanHandOver", "advancedFollowup", "transferBot", "customApi" ], "example": "triggerWorkflow", "description": "Type of the action" }, "agentId": { "type": "string", "example": "agentId123", "description": "Agent ID where the action belongs" }, "details": { "description": "Action-specific details. The structure depends on the action type. For TRIGGER_WORKFLOW use triggerWorkflowDto, for UPDATE_CONTACT_FIELD use updateContactFieldDto, for APPOINTMENT_BOOKING use appointmentBookingDto, for STOP_BOT use stopBotDto, for HUMAN_HAND_OVER use humanHandOverDto, for ADVANCED_FOLLOWUP use advancedFollowupDto, and for TRANSFER_BOT use transferBotDto.", "example": { "workflowIds": [ "workflow123" ], "triggerCondition": "When user requests appointment" }, "oneOf": [ { "type": "object", "properties": { "workflowIds": { "example": [ "workflow123", "workflow456" ], "description": "Array of workflow IDs to trigger", "type": "array", "items": { "type": "string" } }, "triggerCondition": { "type": "string", "example": "When user requests appointment", "description": "Condition that triggers the workflow" }, "triggerMessage": { "type": "string", "example": "Workflow triggered successfully", "description": "Optional message to send when triggering the workflow" } }, "required": [ "workflowIds", "triggerCondition" ], "title": "triggerWorkflowDto" }, { "type": "object", "properties": { "contactFieldId": { "type": "string", "example": "123", "description": "ID of the contact field in Contacts Table" }, "description": { "type": "string", "example": "Business Name", "description": "Description of the contact field in Contacts Table" }, "contactUpdateExamples": { "example": [ "Example 1" ], "default": [], "description": "Contact update examples in Contacts Table. Not required when using standard fields, Monetory or Date Custom fields.", "type": "array", "items": { "type": "string" } } }, "required": [ "contactFieldId", "description" ], "title": "updateContactFieldDto" }, { "type": "object", "properties": { "actionId": { "type": "string", "example": "action123", "description": "Optional action ID reference" }, "calendarId": { "type": "string", "example": "calendar123", "description": "Calendar ID for appointment booking" }, "onlySendLink": { "type": "boolean", "example": false, "description": "If true, only sends the appointment link without booking" }, "triggerWorkflow": { "type": "boolean", "example": true, "description": "Whether to trigger a workflow after booking (cannot be true when onlySendLink is true)" }, "workflowIds": { "example": [ "workflow123" ], "description": "Workflow IDs to trigger after booking (required when triggerWorkflow is true)", "type": "array", "items": { "type": "string" } }, "sleepAfterBooking": { "type": "boolean", "example": true, "description": "Whether to put the agent to sleep after booking (cannot be true when onlySendLink is true)" }, "sleepTimeUnit": { "type": "string", "enum": [ "days", "hours", "minutes" ], "example": "hours", "description": "Unit for sleep time (required when sleepAfterBooking is true)" }, "sleepTime": { "type": "number", "example": 24, "description": "Sleep duration (required when sleepAfterBooking is true)" }, "transferBot": { "type": "boolean", "example": false, "description": "Whether to transfer to another agent after booking (cannot be true when onlySendLink is true)" }, "transferAgent": { "type": "string", "example": "employee456", "description": "Agent ID to transfer to (required when transferBot is true)" }, "rescheduleEnabled": { "type": "boolean", "default": false, "example": true, "description": "Whether to allow appointment rescheduling (cannot be true when onlySendLink is true)" }, "cancelEnabled": { "type": "boolean", "default": false, "example": true, "description": "Whether to allow appointment cancellation (cannot be true when onlySendLink is true)" } }, "required": [ "calendarId", "onlySendLink", "triggerWorkflow", "sleepAfterBooking", "transferBot", "rescheduleEnabled", "cancelEnabled" ], "title": "appointmentBookingDto" }, { "type": "object", "properties": { "stopBotDetectionType": { "type": "string", "enum": [ "Goodbye", "Custom" ], "example": "Custom", "description": "Type of stop bot detection - Goodbye or Custom" }, "stopBotTriggerCondition": { "type": "string", "example": "When the user says they no longer need assistance or want to end the conversation", "description": "Condition that triggers stopping the bot" }, "reactivateEnabled": { "type": "boolean", "example": true, "description": "Whether the bot can be reactivated after being stopped" }, "sleepTimeUnit": { "type": "string", "enum": [ "days", "hours", "minutes" ], "example": "hours", "description": "Time unit for reactivation delay (required when reactivateEnabled is true)" }, "sleepTime": { "type": "number", "example": 24, "description": "Time duration before reactivation (required when reactivateEnabled is true)" }, "enabled": { "type": "boolean", "example": true, "description": "Whether this action is enabled for the agent" }, "stopBotExamples": { "example": [ "goodbye", "thank you", "no more questions" ], "description": "Example phrases that trigger stop bot action (minimum 2 required)", "type": "array", "items": { "type": "string" } }, "finalMessage": { "type": "string", "example": "Thank you for contacting us. Have a great day!", "description": "Final message sent when stopping the bot" }, "tags": { "example": [ "resolved", "no-response" ], "description": "Tags to apply when stopping the bot", "type": "array", "items": { "type": "string" } } }, "required": [ "stopBotDetectionType", "stopBotTriggerCondition", "reactivateEnabled", "enabled", "stopBotExamples", "finalMessage" ], "title": "stopBotDto" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true, "description": "Whether human handover action is enabled" }, "triggerCondition": { "type": "string", "example": "When the user requests to speak with a human agent or expresses frustration", "description": "Condition that triggers human handover" }, "examples": { "example": [ "speak to human", "talk to agent", "need help from person" ], "description": "Example phrases that trigger human handover (required when handoverType is custom or contactRequest)", "type": "array", "items": { "type": "string" } }, "assignToUserId": { "type": "string", "example": "user123", "description": "ID of the user to assign the conversation to" }, "skipAssignToUser": { "type": "boolean", "example": false, "description": "Whether to skip assigning to a specific user" }, "createTask": { "type": "boolean", "example": true, "description": "Whether to create a task when handing over" }, "reactivateEnabled": { "type": "boolean", "example": true, "description": "Whether the agent can be reactivated after handover" }, "sleepTimeUnit": { "type": "string", "enum": [ "days", "hours", "minutes" ], "example": "hours", "description": "Time unit for reactivation delay (required when reactivateEnabled is true)" }, "sleepTime": { "type": "number", "example": 24, "description": "Time duration before reactivation (required when reactivateEnabled is true)" }, "finalMessage": { "type": "string", "example": "I am transferring you to a human agent who will assist you shortly.", "description": "Final message sent when handing over to human" }, "tags": { "example": [ "escalated", "human-requested" ], "description": "Tags to apply during handover", "type": "array", "items": { "type": "string" } }, "handoverType": { "type": "string", "enum": [ "contactRequest", "lackOfInformation", "failedToResolveIssue", "custom" ], "example": "contactRequest", "description": "Type of human handover detection" } }, "required": [ "enabled", "triggerCondition", "reactivateEnabled", "finalMessage", "handoverType" ], "title": "humanHandOverDto" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true, "description": "Whether advanced followup is enabled" }, "scenarioId": { "type": "string", "example": "contactIsBusy", "enum": [ "contactStoppedReplying", "contactIsBusy", "contactRequested" ], "description": "ID of the followup scenario" }, "followupSequence": { "description": "Sequence of followup actions to perform", "example": [ { "id": 1, "followupTimeUnit": "hours", "followupTime": 2, "aiEnabledMessage": true } ], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "description": "Unique identifier for this followup step" }, "followupTimeUnit": { "type": "string", "enum": [ "days", "hours", "minutes" ], "example": "hours", "description": "Time unit for followup delay" }, "followupTime": { "type": "number", "example": 2, "description": "Time duration before followup (max: 60 minutes, 24 hours, or 180 days depending on unit)" }, "aiEnabledMessage": { "type": "boolean", "example": true, "default": true, "description": "Whether to use AI to generate the followup message" }, "triggerWorkflow": { "type": "boolean", "example": false, "default": false, "description": "Whether to trigger a workflow during this followup" }, "customMessage": { "type": "string", "example": "Hi! Just following up on our previous conversation. Do you have any questions?", "description": "Custom message to send (when aiEnabledMessage is false)" }, "workflowId": { "type": "string", "example": "workflow789", "description": "Workflow ID to trigger (when triggerWorkflow is true)" }, "contactRequested": { "type": "boolean", "example": false, "description": "Whether contact was requested in this followup" } }, "required": [ "id", "followupTimeUnit", "followupTime" ], "title": "FollowupSequence" } }, "followupSettings": { "description": "Additional settings for followup behavior", "example": { "dynamicChannelSwitching": true, "followUpHours": false, "timezoneToUse": "contact" }, "allOf": [ { "type": "object", "properties": { "dynamicChannelSwitching": { "type": "boolean", "example": true, "default": true, "description": "Whether to dynamically switch channels for followups" }, "followUpHours": { "type": "boolean", "example": true, "description": "Whether to respect working hours for followups" }, "workingHours": { "description": "Working hours configuration for followups", "example": [ { "dayOfTheWeek": 1, "intervals": [ { "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 0 } ] } ], "type": "array", "items": { "type": "object", "properties": { "dayOfTheWeek": { "type": "number", "example": 1, "description": "Day of the week (0=Sunday, 1=Monday, etc.)" }, "intervals": { "description": "Time intervals for this day", "example": [ { "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 0 } ], "type": "array", "items": { "type": "object", "properties": { "startHour": { "type": "number", "example": 9, "description": "Start hour (24-hour format)" }, "startMinute": { "type": "number", "example": 0, "description": "Start minute" }, "endHour": { "type": "number", "example": 17, "description": "End hour (24-hour format)" }, "endMinute": { "type": "number", "example": 30, "description": "End minute" } }, "required": [ "startHour", "startMinute", "endHour", "endMinute" ], "title": "Interval" } } }, "required": [ "dayOfTheWeek" ], "title": "WorkingHours" } }, "timezoneToUse": { "type": "string", "enum": [ "contact", "business" ], "description": "Timezone to use for followups, contact or location", "example": "contact" } }, "required": [ "dynamicChannelSwitching" ], "title": "FollowupSettings" } ] } }, "required": [ "enabled", "scenarioId", "followupSequence" ], "title": "advancedFollowupDto" }, { "type": "object", "properties": { "transferBotType": { "type": "string", "enum": [ "Default", "Custom" ], "example": "Custom", "description": "Type of transfer - Default or Custom" }, "transferToBot": { "type": "string", "example": "employee789", "description": "ID of the bot/agent to transfer to" }, "enabled": { "type": "boolean", "example": true, "description": "Whether this transfer action is enabled" }, "transferBotTriggerCondition": { "type": "string", "example": "When the user asks to speak with sales or needs pricing information", "description": "Condition that triggers the transfer (required for Custom type)" }, "transferBotExamples": { "example": [ "talk to sales", "pricing information", "speak to specialist" ], "description": "Example phrases that trigger transfer (required for Custom type, minimum 2)", "type": "array", "items": { "type": "string" } } }, "required": [ "transferBotType", "transferToBot", "enabled" ], "title": "transferBotDto" } ] } }, "required": [ "id", "name", "type", "details" ], "title": "ActionDataDTO" }, { "type": "object", "properties": { "id": { "type": "string", "example": "instanceId123", "description": "Unique identifier for the API Call action" }, "name": { "type": "string", "example": "Get Orders", "description": "Name of the API Call action" }, "type": { "type": "string", "enum": [ "customApi" ], "example": "customApi", "description": "Always customApi" }, "agentId": { "type": "string", "example": "agentId123", "description": "Agent ID where the action belongs" }, "details": { "description": "API Call config — description, triggerCondition, and the HTTP definition (secrets redacted on read).", "allOf": [ { "type": "object", "properties": { "triggerCondition": { "type": "string", "maxLength": 500, "description": "\"use this when…\" rule shown to the agent. REQUIRED on CREATE (enforced in the handler) to match the builder; on UPDATE it may be OMITTED to leave it unchanged, but sending it blank is rejected.", "example": "When the customer asks where their order is or for a delivery date." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional description of the API Call action", "example": "Looks up an order in the fulfilment system and returns its status and delivery date." }, "postActionPrompt": { "type": "string", "maxLength": 300, "description": "Guidance the agent follows AFTER the call returns (e.g. how to phrase the reply, what not to reveal). REQUIRED on CREATE (enforced in the handler) to match the builder; on UPDATE it may be OMITTED to leave it unchanged (partial merge), but sending it blank is rejected." }, "apiConfig": { "description": "The self-contained HTTP definition. Required on CREATE (enforced in the handler). OPTIONAL on UPDATE — omit it to edit just name/description/triggerCondition. When sent on update it is merged ONE LEVEL DEEP over the stored config: top-level keys present replace the stored value, keys absent are kept, and nested objects/arrays (headers, queryParams, bodyTemplate, parameters, outputFields) are replaced whole — send the complete value, not just the entry that changed. Secrets are redacted on read; see `authentication` for how they round-trip.", "allOf": [ { "type": "object", "properties": { "url": { "type": "string", "example": "https://api.example.com/orders/{{orderId}}", "description": "HTTPS endpoint; supports {{var}}. REQUIRED on create. Optional on update — omit it to keep the stored url (apiConfig merges by top-level key)." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "example": "GET", "description": "HTTP method used for the call. REQUIRED on create. Optional on update — omit it to keep the stored method." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Static HTTP headers sent with every call. Secrets belong in `authentication`, not here. On update this object REPLACES the stored headers — send them all, not just the changed one.", "example": { "Content-Type": "application/json", "X-Source": "conversation-ai" } }, "queryParams": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Static query-string parameters appended to the URL.", "example": { "status": "active", "limit": "10" } }, "bodyTemplate": { "type": "object", "description": "Request body template — object or raw JSON string. Supports {{variable}} placeholders.", "example": { "orderId": "{{parameters.orderId}}", "email": "{{contact.email}}" } }, "parameters": { "type": "object", "additionalProperties": true, "description": "JSON Schema of LLM-supplied params", "example": { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order number the caller gave" } }, "required": [ "orderId" ] } }, "authentication": { "type": "object", "description": "Auth config; secrets stored per-instance, write-only", "example": { "type": "bearer", "token": "••••••••" } }, "timeoutMs": { "type": "number", "example": 15000, "description": "Per-request timeout in milliseconds (max 60000)." }, "retryOnFailure": { "type": "boolean", "example": false, "description": "Retry the call once on a network error or a 5xx. 4xx is never retried." }, "useSimpleRequestBody": { "type": "boolean", "example": false, "description": "Send the body template verbatim as raw JSON instead of building it from the parameter schema." }, "outputFields": { "example": [ "data.id", "data.status" ], "description": "Dot-paths of the response fields handed back to the agent. Omit to return the whole body; use [] notation for arrays, e.g. `result[].id`.", "type": "array", "items": { "type": "string" } }, "sampleResponse": { "type": "object", "additionalProperties": true, "description": "Trimmed sample of a real response (editor Test tab). Prompt-only — inlined so the agent knows the response shape; never executed. Secrets are masked on read." } }, "title": "ApiCallConfigDTO" } ] } }, "title": "CustomApiDetailsDTO" } ] } }, "required": [ "id", "name", "type" ], "title": "CustomApiActionDataDTO" } ], "example": { "id": "actionId123", "name": "Trigger Workflow", "type": "triggerWorkflow" } }, "success": { "type": "boolean", "example": true, "description": "Success status of the request" } }, "required": [ "data", "success" ], "title": "fetchActionDetailsResponseDTO" }, "BadRequestDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" }, "UnprocessableDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/conversation-ai/agents//actions/' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/conversation-ai/agents//actions/', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/conversation-ai/agents/{agentId}/actions/{actionId}" headers = { "Authorization": "Bearer ", "Version": "v3" } response = requests.get(url, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/conversation-ai/agents//actions/', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/conversation-ai/agents//actions/") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/conversation-ai/agents//actions/" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/conversation-ai/agents//actions/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/conversation-ai/agents//actions/' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```