Create an Agent

POST 
/conversation-ai/agents

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

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

namestringrequired

Name of the agent.

businessNamestring

Name of the business the agent represents.

modestring
Mode of operation - OFF, SUGGESTIVE, or AUTO_PILOT
Available optionsoffsuggestiveauto-pilot
channelsstring[]
Communication channels the agent can operate on
Available optionsIGFBSMSWebChatWhatsAppLive_ChatEmail
isPrimaryboolean
Indicates if this agent is a primary agent.
Default value: false
waitTimenumber
Wait time before agent responds (max 5 for minutes, 300 for seconds)
Default value: 2
waitTimeUnitstring
Unit for wait time - SECONDS or MINUTES
Available optionsminutesseconds
sleepEnabledbooleandeprecated
Indicates if sleep functionality is enabled.
Default value: false
sleepOnManualMessageboolean

Enable sleep when a manual outbound message is sent.

sleepOnWorkflowMessageboolean

Enable sleep when a workflow outbound message is sent.

sleepTimenumber

Duration of sleep period (required if sleepEnabled is true). Set to null for indefinite sleep. (max 2880 for minutes, 172800 for seconds, 48 for hours)

sleepTimeUnitstring
Unit of sleep time - HOURS, MINUTES, or SECONDS (required if sleepEnabled is true). Set to null for indefinite sleep.
Available optionshoursminutesseconds
personalitystringrequired

Personality traits of the agent.

goalstringrequired

The goal of the agent.

instructionsstringrequired

Instructions for the agent.

fullPromptstring

Complete agent prompt. When set and non-empty, used as the source of truth at generation time instead of personality, goal, and instructions.

autoPilotMaxMessagesnumber
Maximum number of messages in auto-pilot mode before requiring human intervention. (max: 100, min: 1)
Default value: 75
knowledgeBaseIdsstring[]

Array of knowledge base IDs associated with this agent.

respondToImagesboolean
Allow agent to respond to images
Default value: false
respondToAudioboolean
Allow agent to respond to audio
Default value: false

Example (auto)

{
  "name": "John Doe",
  "businessName": "Tech Corp",
  "mode": "auto-pilot",
  "channels": [
    "SMS",
    "Live_Chat",
    "WhatsApp"
  ],
  "isPrimary": true,
  "waitTime": 2,
  "waitTimeUnit": "seconds",
  "sleepOnManualMessage": false,
  "sleepOnWorkflowMessage": false,
  "sleepTime": 2,
  "sleepTimeUnit": "hours",
  "personality": "Friendly and helpful",
  "goal": "Assist customers with inquiries.",
  "instructions": "Provide  customer service.",
  "fullPrompt": "string",
  "autoPilotMaxMessages": 75,
  "knowledgeBaseIds": [
    "kb_abc123",
    "kb_def456"
  ],
  "respondToImages": true,
  "respondToAudio": true
}

application/json

Successful response

application/json

Schema

Schema

idstringrequired

Unique identifier for the agent.

namestringrequired

Name of the agent.

businessNamestring

Name of the business the agent represents.

modestringrequired
Current operating mode of the agent.
Available optionsoffsuggestiveauto-pilot
channelsstring[]required
Communication channels the agent operates on.
Available optionsIGFBSMSWebChatWhatsAppLive_ChatEmail
waitTimenumberrequired

Wait time before agent responds.

waitTimeUnitstringrequired
Unit for wait time.
Available optionsminutesseconds
sleepEnabledbooleanrequireddeprecated

Indicates if sleep functionality is enabled.

sleepOnManualMessageboolean

Whether the bot sleeps on manual outbound messages.

sleepOnWorkflowMessageboolean

Whether the bot sleeps on workflow outbound messages.

sleepTimenumber

Duration of sleep period.

sleepTimeUnitstring
Unit of sleep time.
Available optionshoursminutesseconds
emailWaitTimenumber

Email-specific wait time (max 12 hours).

emailWaitTimeUnitstring
Unit for email wait time.
Available optionssecondsminuteshours
emailSettingsobject

Email channel formatting settings.

actionsobject[]required

List of actions associated with this agent.

isPrimarybooleanrequired

Indicates if this agent is a primary agent.

autoPilotMaxMessagesnumberrequired

Maximum number of messages in auto-pilot mode before requiring human intervention.

goalstring

The goal of the agent.

personalitystring

Personality traits of the agent.

instructionsstring

Instructions for the agent.

fullPromptstring

Complete agent prompt when stored; when set and non-empty, used as the source of truth at generation time.

knowledgeBaseIdsstring[]

Array of knowledge base IDs associated with this agent.

knowledgeBaseTriggersobject[]

Knowledge base trigger configurations

workingHoursobjectnullable

Working-hours schedule for this agent, or null when not configured. Manage it via the /working-hours routes.

Example (auto)

{
  "id": "emp_123",
  "name": "John Doe",
  "businessName": "Tech Corp",
  "mode": "auto-pilot",
  "channels": [
    "SMS",
    "Live_Chat"
  ],
  "waitTime": 30,
  "waitTimeUnit": "seconds",
  "sleepOnManualMessage": false,
  "sleepOnWorkflowMessage": false,
  "sleepTime": 2,
  "sleepTimeUnit": "hours",
  "emailWaitTime": 1,
  "emailWaitTimeUnit": "hours",
  "emailSettings": {},
  "actions": [
    {
      "id": "actionId123",
      "type": "triggerWorkflow"
    }
  ],
  "isPrimary": false,
  "autoPilotMaxMessages": 25,
  "goal": "Assist customers with inquiries",
  "personality": "Friendly and helpful",
  "instructions": "Provide excellent customer service",
  "fullPrompt": "string",
  "knowledgeBaseIds": [
    "kb_123",
    "kb_456"
  ],
  "knowledgeBaseTriggers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "mode": "all",
      "knowledgeBaseIds": [
        "kb_001"
      ],
      "triggerCondition": "When the customer asks about pricing or billing",
      "priority": 2
    }
  ],
  "workingHours": {
    "enabled": false,
    "channels": [
      "SMS",
      "WhatsApp"
    ],
    "timezoneMode": "contact",
    "schedule": {
      "mon": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      },
      "tue": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      },
      "wed": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      },
      "thu": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      },
      "fri": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      },
      "sat": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      },
      "sun": {
        "enabled": true,
        "slots": [
          {
            "startHour": 9,
            "startMinute": 0,
            "endHour": 17,
            "endMinute": 0
          }
        ]
      }
    },
    "continueConversations": {
      "enabled": true,
      "inactivityTimeout": {
        "value": 15,
        "unit": "minutes"
      }
    },
    "offHoursAutoReply": {
      "enabled": false,
      "message": "Thanks for reaching out! We're currently outside of business hours.",
      "sendNotification": false,
      "notificationConfig": {
        "emailNotification": {
          "enabled": false,
          "notifyAdmins": false,
          "notifyAllUsers": false,
          "notifyAssignedUser": false,
          "notifySpecificUsers": false,
          "specificUserIds": [],
          "notifyCustomEmail": false,
          "customEmail": ""
        },
        "contactTags": []
      }
    },
    "followUp": {
      "enabled": false,
      "message": "Hi {{contact.name}}, we're here now and happy to help."
    },
    "employeeId": "wK36brxPYCOikC85FkbA",
    "createdAt": "2024-07-29T15:51:28.071Z",
    "updatedAt": "2024-07-29T15:51:28.071Z"
  }
}