Skip to main content
Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified account. locationId is required in the request body. Session Management:
  • For the first message in a new session, do not include the executionId in the request payload.
  • The API will return an executionId along with the agent response, which uniquely identifies this conversation session.
  • To continue the conversation within the same session, include the executionId from the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions.
POST https://services.leadconnectorhq.com/agent-studio/agent/{agentId}/execute

​
Autorización

​
Authorization
string
required
Bearer token generado desde el portal Leadway. Ver Autenticación.
​
Version
string
default:"2021-07-28"
required
Versión de la API.

​
Path parameters

​
agentId
string
default:"p1q2r3s4t5u6v7w8x9y0z1a2"
required

​
Query parameters

​
source
string
default:"api"

​
Body

​
message
string
default:"How can you help me with my marketing?"
required
Message to send to the agent
​
executionId
string
default:"a1b2c3d4e5f6g7h8i9j0k1l2"
Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Omit this field for the first message in a new session. Include the executionId returned from the previous response to maintain context in subsequent messages.
​
inputVariables
object
Input variables to pass to the agent. These should match the input variables defined in the agent configuration.
​
versionId
string
default:"b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
Published version ID to execute. If not provided, the latest published production version will be used.
​
attachments
object[]
Attachments for the message
​
locationId
string
default:"C2QujeCh8ZnC7al2InWR"
required
Account ID
​
contactId
string
default:"cid_abc123def456"
Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.

​
Respuestas

​
success
boolean
default:"True"
required
Success status
​
executionId
string
default:"a1b2c3d4e5f6g7h8i9j0k1l2"
required
Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Use this ID in subsequent requests to continue the conversation.
​
interactionId
string
default:"m9n8o7p6q5r4s3t2u1v0w9x8"
required
Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId.
​
response
string
default:"I can help you with various tasks..."
required
Agent response text
​
type
string
default:"text"
required
Response type
​
nextExpectedInput
string
default:"text"
required
Expected input type for next interaction
​
goalCompletion
boolean
default:"False"
required
When end node is added in the graph, this will be true if the agent reached the end node in the graph
​
executionStatus
string
default:"completed"
required
Execution status
​
flowSwitch
boolean
default:"False"
required
Whether flow was switched
​
attachments
object[]
required
Response attachments
​
generativeOutputs
object[]
required
Generated outputs
{
  "success": true,
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
  "response": "I can help you with various tasks...",
  "type": "text",
  "nextExpectedInput": "text",
  "goalCompletion": false,
  "executionStatus": "completed",
  "flowSwitch": false,
  "attachments": [],
  "generativeOutputs": []
}

{}

{}
​
statusCode
number
default:"500"
​
message
string
default:"Internal Server Error"
{
  "statusCode": 500,
  "message": "Internal Server Error"
}

​
Ejemplo

curl -X POST 'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [
    {
      "type": "image",
      "imageUrl": "https://example.com/image.png"
    }
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}'

const response = await fetch('https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEADWAY_TOKEN}`,
    Version: '2021-07-28',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"message": "How can you help me with my marketing?", "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2", "inputVariables": {"customerName": "John Doe", "orderNumber": "ORD-12345"}, "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "attachments": [{"type": "image", "imageUrl": "https://example.com/image.png"}], "locationId": "C2QujeCh8ZnC7al2InWR", "contactId": "cid_abc123def456"}),
});
const data = await response.json();

import os, requests
response = requests.request(
    'POST',
    'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute',
    headers={
        'Authorization': f"Bearer {os.environ['LEADWAY_TOKEN']}",
        'Version': '2021-07-28',
        'Content-Type': 'application/json',
    },
    json={"message": "How can you help me with my marketing?", "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2", "inputVariables": {"customerName": "John Doe", "orderNumber": "ORD-12345"}, "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "attachments": [{"type": "image", "imageUrl": "https://example.com/image.png"}], "locationId": "C2QujeCh8ZnC7al2InWR", "contactId": "cid_abc123def456"},
)
data = response.json()

<?php
$ch = curl_init('https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('LEADWAY_TOKEN'),
        'Version: 2021-07-28',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode({'message': 'How can you help me with my marketing?', 'executionId': 'a1b2c3d4e5f6g7h8i9j0k1l2', 'inputVariables': {'customerName': 'John Doe', 'orderNumber': 'ORD-12345'}, 'versionId': 'b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d', 'attachments': [{'type': 'image', 'imageUrl': 'https://example.com/image.png'}], 'locationId': 'C2QujeCh8ZnC7al2InWR', 'contactId': 'cid_abc123def456'}),
]);
$data = json_decode(curl_exec($ch), true);