Creates a new AI agent for the account. The agent will be created with the specified configuration including name, role, actions, and behavior settings.

http
POST https://services.leadconnectorhq.com/conversation-ai/agents

Authorization

NameTypeRequiredExampleDescription
AuthorizationstringYesBearer token generated from the Leadway portal. See Authentication.
VersionstringYes2021-07-28API version.

Body

NameTypeRequiredExampleDescription
namestringYesJohn DoeName of the agent.
businessNamestringNoTech CorpName of the business the agent represents.
modestringNoauto-pilotMode of operation - OFF, SUGGESTIVE, or AUTO_PILOT Possible values: 'off', 'suggestive', 'auto-pilot'
channelsstring[]NoCommunication channels the agent can operate on
isPrimarybooleanNoTrueIndicates if this agent is a primary agent.
waitTimenumberNo2Wait time before agent responds (max 5 for minutes, 300 for seconds)
waitTimeUnitstringNosecondsUnit for wait time - SECONDS or MINUTES Possible values: 'minutes', 'seconds'
sleepEnabledbooleanNoFalseIndicates if sleep functionality is enabled.
sleepTimenumberNo2Duration of sleep period (required if sleepEnabled is true). Set to null for indefinite sleep. (max 2880 for minutes, 172800 for seconds, 48 for hours)
sleepTimeUnitstringNohoursUnit of sleep time - HOURS, MINUTES, or SECONDS (required if sleepEnabled is true). Set to null for indefinite sleep. Possible values: 'hours', 'minutes', 'seconds'
personalitystringYesFriendly and helpfulPersonality traits of the agent.
goalstringYesAssist customers with inquiries.The goal of the agent.
instructionsstringYesProvide customer service.Instructions for the agent.
autoPilotMaxMessagesnumberNo75Maximum number of messages in auto-pilot mode before requiring human intervention. (max: 100, min: 1)
knowledgeBaseIdsstring[]NoArray of knowledge base IDs associated with this agent.
respondToImagesbooleanNoTrueAllow agent to respond to images
respondToAudiobooleanNoTrueAllow agent to respond to audio
sleepOnManualMessagebooleanNoFalseEnable sleep when a manual outbound message is sent.
sleepOnWorkflowMessagebooleanNoFalseEnable sleep when a workflow outbound message is sent.

Responses

201 - Successful response
  • id (string, required): Unique identifier for the agent. Example: emp_123

  • name (string, required): Name of the agent. Example: John Doe

  • businessName (string): Name of the business the agent represents. Example: Tech Corp

  • mode (string, required): Current operating mode of the agent. Possible values: 'off', 'suggestive', 'auto-pilot' Example: auto-pilot

  • channels (string[], required): Communication channels the agent operates on.

  • waitTime (number, required): Wait time before agent responds. Example: 30

  • waitTimeUnit (string, required): Unit for wait time. Possible values: 'minutes', 'seconds' Example: seconds

  • sleepEnabled (boolean, required): Indicates if sleep functionality is enabled. Example: False

  • sleepTime (number): Duration of sleep period. Example: 2

  • sleepTimeUnit (string): Unit of sleep time. Possible values: 'hours', 'minutes', 'seconds' Example: hours

  • actions (object[], required): List of actions associated with this agent.

    • id (string, required): Unique identifier for the action. Example: actionId123

    • type (string, required): type of action. Possible values: 'triggerWorkflow', 'updateContactField', 'appointmentBooking', 'stopBot', 'humanHandOver', 'advancedFollowup', 'transferBot' Example: triggerWorkflow

  • isPrimary (boolean, required): Indicates if this agent is a primary agent. Example: False

  • autoPilotMaxMessages (number, required): Maximum number of messages in auto-pilot mode before requiring human intervention. Example: 25

  • goal (string): The goal of the agent. Example: Assist customers with inquiries

  • personality (string): Personality traits of the agent. Example: Friendly and helpful

  • instructions (string): Instructions for the agent. Example: Provide excellent customer service

  • knowledgeBaseIds (string[]): Array of knowledge base IDs associated with this agent.

  • sleepOnManualMessage (boolean): Whether the bot sleeps on manual outbound messages. Example: False

  • sleepOnWorkflowMessage (boolean): Whether the bot sleeps on workflow outbound messages. Example: False

json
{
  "id": "emp_123",
  "name": "John Doe",
  "businessName": "Tech Corp",
  "mode": "auto-pilot",
  "channels": [
    "SMS",
    "Live_Chat"
  ],
  "waitTime": 30,
  "waitTimeUnit": "seconds",
  "sleepEnabled": false,
  "sleepTime": 2,
  "sleepTimeUnit": "hours",
  "actions": [
    {
      "id": "actionId123",
      "type": "triggerWorkflow"
    }
  ],
  "isPrimary": false,
  "autoPilotMaxMessages": 25,
  "goal": "Assist customers with inquiries",
  "personality": "Friendly and helpful",
  "instructions": "Provide excellent customer service",
  "knowledgeBaseIds": [
    "kb_123",
    "kb_456"
  ],
  "sleepOnManualMessage": false,
  "sleepOnWorkflowMessage": false
}
400 - Bad Request
json
{}
401 - Unauthorized
json
{}
422 - Unprocessable Entity
json
{}

Example

curl -X POST 'https://services.leadconnectorhq.com/conversation-ai/agents' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "John Doe",
  "businessName": "Tech Corp",
  "mode": "auto-pilot",
  "channels": [
    "SMS",
    "Live_Chat",
    "WhatsApp"
  ],
  "isPrimary": true,
  "waitTime": 2,
  "waitTimeUnit": "seconds",
  "sleepEnabled": false,
  "sleepTime": 2,
  "sleepTimeUnit": "hours",
  "personality": "Friendly and helpful",
  "goal": "Assist customers with inquiries.",
  "instructions": "Provide  customer service.",
  "autoPilotMaxMessages": 75,
  "knowledgeBaseIds": [
    "string"
  ],
  "respondToImages": true,
  "respondToAudio": true,
  "sleepOnManualMessage": false,
  "sleepOnWorkflowMessage": false
}'

Last updated October 26, 2026

Was this page helpful?