Skip to main content

Outbound Call

Outbound call requests manage AI-powered telephony campaigns with scheduling, retry logic, and calling hours compliance. Supports immediate execution, scheduled calls, and recurring patterns with configurable time windows for TCPA compliance.

Source: src/core/conversation/outbound-call.schema.ts

BusinessCallRequest​

Complete outbound call request with all configuration options for AI-powered telephony campaigns. Supports immediate execution, scheduled calls, and recurring patterns with configurable retry logic.

Schema: BusinessCallRequestSchema

Schedule Types​

TypeDescription
immediateExecutes as soon as possible within calling hours
scheduledExecutes at specific scheduledAt timestamp
recurringExecutes on callingHours schedule pattern

Call Request Lifecycle​

StatusDescription
pendingCreated, awaiting execution window
scheduledQueued for specific time
in_progressCall currently active
completedCall finished successfully
failedCall failed after all retries
cancelledManually cancelled before execution

Attributes​

AttributeTypeRequiredDefaultDescription
idstringYes—Unique identifier for this call request
phoneConfigurationIdstring | nullNo—Phone configuration ID for caller ID display and telephony routing
tostringYes—Destination phone number in E.164 format (e.g., '+12125551234')
fromstringYes—Caller ID phone number in E.164 format
agentConfigurationIdstringYes—Agent configuration ID defining AI behavior for this call
instructionConfigurationIdstring | nullNo—Optional instruction configuration ID to override agent defaults
maxDurationnumberNo—Maximum call duration in seconds
scheduleTypeenumYes—Call timing strategy. One of immediate, scheduled, or recurring.
serviceConversationConfigIdstring | nullNo—Linked conversation record ID for tracking
timeZonestringNo—IANA timezone identifier (e.g., 'America/New_York')
scheduledAtnumberNo—Unix timestamp in milliseconds for scheduled execution
callingHoursCallingHours | nullNo—Permitted calling window configuration
maxRetriesnumberNo—Maximum retry attempts (0-5)
retryDelayMinutesnumberNo—Delay in minutes between retry attempts
statusenumYespendingCurrent status of the call request lifecycle
metadataobjectNo—Additional custom metadata for campaign tracking
createdAtnumberNo—Unix timestamp when created
updatedAtnumber | nullNo—Unix timestamp when last updated

CallingHours​

Permitted time window configuration for outbound calls. Ensures TCPA compliance and respects customer preferences. Calls scheduled outside these hours are queued until the next available window.

Schema: CallingHoursSchema

Attributes​

AttributeTypeRequiredDefaultDescription
startTimestringYes—Start time in HH:MM 24-hour format (e.g., '09:00')
endTimestringYes—End time in HH:MM 24-hour format (e.g., '17:00')
daysOfWeekarray<number>No[1,2,3,4,5]Permitted days (0=Sunday through 6=Saturday)

CreateCallRequest​

Schema for creating a new outbound call request. Omits auto-generated fields (id, timestamps, audit fields).

Schema: CreateCallRequestSchema

Attributes​

Same as BusinessCallRequest, excluding: id, createdAt, updatedAt, createdBy, updatedBy, deletedAt, deletedBy, uniqueKey, version.

Example​

Business Call Request​

{
  "id": "call_abc123",
  "to": "+12125551234",
  "from": "+12125559999",
  "agentConfigurationId": "agent_456",
  "scheduleType": "immediate",
  "callingHours": {
    "startTime": "09:00",
    "endTime": "17:00",
    "daysOfWeek": [1, 2, 3, 4, 5]
  },
  "maxRetries": 3,
  "retryDelayMinutes": 30,
  "status": "pending",
  "metadata": {
    "campaignId": "camp_789",
    "leadSource": "website"
  },
  "createdAt": 1709856000000
}

Scheduled Call​

{
  "to": "+12125551234",
  "from": "+12125559999",
  "agentConfigurationId": "agent_456",
  "scheduleType": "scheduled",
  "scheduledAt": 1709942400000,
  "timeZone": "America/New_York",
  "maxDuration": 600,
  "status": "scheduled"
}