Campaigns

List Campaigns

GET /campaigns

Response

200 application/json

interface CampaignResponse {
    Campaigns: {
        OrgID: string
        ID: string
        Name: string
        State: "started" | "paused" | "ended"
        // the currently published version
        Version: number
        Data: CampaignData
        CreatedAt: string
        UpdatedAt: string
    }[]
    Org: {
        Name: string
        DefaultRole: string
        IncludedCredits: number
        IncludedConversationSeconds: number

        BillingDoMStart: number
        BillingMode: string
    }
}

interface CampaignData {
    // default caller ID (phone number we call from, in E.164 format) if the job doesn't specify one, or the specified one is not enabled
    CallerID: string

    // map of caller IDs that a job may select either explicitly, or automatically based on country/area code
    AvailableCallerIDs: Record<string, { Disabled: bool }>

    InboundMode:
        | "reject"
        | "lookup"
        | "lookup_failed"
        | "create_if_not_exists"
        | "create" // see Concepts page
    // If call is rejected because of InboundMode, this message will be sent to the caller.
    // If empty, the call will be immediately rejected (i.e. busy signal will sound)
    CallRejectionMessage: string

    // MaxActiveCalls delays calls until the number of active calls within this campaign is below this value
    MaxActiveCalls: number // int64

    // JSON schema that the final analysis
    AnalysisSchema: Record<string, any>

    // If set, a job will be considered failed if the prompt evaluates to false
    CampaignObjectivePrompt?: string

    // The name of the Cobbery agent
    BotName: string

    Constraints: any // see JobOverrides.Constraints

    // integrations enable new functions for the LLM to call. See Integrations docs.
    Integrations?: Record<string, any>

    /*
     * If the user disconnects before the end of the conversation,
     * consider this an "opt-out" and fail (possibly partially) the Job
     */
    HangUpIsOptOut?: bool

    JobMetadataSchema?: Record<string, any> // JSON schema used to validate job metadata if it exists
    JobDataSchema?: Record<string, any> // JSON schema used to validate job data if it exists
}

Get Campaign

GET /campaigns/:campaignID

Response

200 application/json

interface GetCampaignResponse {
    Campaign: {
        OrgID: string
        ID: string
        Name: string
        State: "started" | "paused" | "ended"
        // the currently published version
        Version: number
        Data: CampaignData // (see above)
        // true, if this campaign is affected by a global pause. E.g. when an AI provider that is used, is unavailable
        GlobalPause?: bool
        CreatedAt: string
        UpdatedAt: string
    }
    Metrics: {
        BillingIntervalStartMS: int64 // if this is 0 (because it hasn't been set yet), then the usage represents all-time
        UsedConversationalMinutes: int64 // if query param events=1, otherwise these are omitted
        IncludedConversationalMinutes: int64
        JobStateCounts: Record<string, int64> // if query param events=1, otherwise these are omitted
        HistogramTuples: Array<Array<number>> // float64, clickhouse histogram() format, if query param events=1 otherwise these are omitted
    }
}

Start Campaign

POST /campaigns/:campaignID/start

Starting a Campaign will begin scheduling (if scheduling is enabled) and allow inbound calling. Jobs will gradually begin after a Campaign is started.

You may start paused campaigns only, You cannot re-start an ended campaign.

Response

202: Campaign started

409: Campaign not currently paused

Pause Campaign

POST /campaigns/:campaignID/pause

Pausing a campaign will pause Jobs. In-flight calls will complete.

Response

202: Campaign paused

409: Campaign not currently started

End Campaign

POST /campaigns/:campaignID/end

Campaign must first be paused before it can be ended.

Ending a Campaign will fail all incomplete Jobs, and the Campaign will not be allowed to be restarted. This is a destructive action.

Response

202 Response: Campaign ended

409 Response: Campaign not currently paused