Agentic - Campaigns

Update campaign configuration and settings

Changed on

Update an existing campaign's configuration. You can modify:

  • Campaign details: Name, description, status
  • Scheduling: Business hours, frequency, timezone
  • Call settings: Retry attempts, concurrent call limits
  • Agent assignment: Change the AI agent handling calls
  • SIP trunks: Update sipTrunkIds used for outbound calls
  • Notifications: Email notification settings

Common Use Cases:

  • Pause a running campaign by setting status: "paused"
  • Adjust concurrent call limits during peak hours
  • Update schedule to match business hours
  • Change AI agent to test different conversation flows
put/api/v1/agentic/campaigns/:id

Request

  • Base URL: https://api.voicelogica.ai
  • URL: https://api.voicelogica.ai/api/v1/agentic/campaigns/:id
  • Auth: API key in header x-api-key

Headers

x-api-keystring required

Your API key for authentication. Required for all endpoints.

x-company-idstring

Optional company ID for resellers. When provided, the API request will operate on behalf of the specified subsidiary company. The API key must have access to the specified company.

Request body

namestring required

Name of the campaign

descriptionstring

Description of the campaign purpose and goals

type'email' | 'phone' | 'sms'

Primary channel type for the campaign

purpose'appointment' | 'lead_qualification' | 'event_invite' | 'payment_collection' | 'custom'

What the campaign is trying to achieve. Non-custom purposes seed campaign-level analysis fields and call instructions; "custom" (default) leaves everything as-is

promptSectionstring

Campaign call instructions injected into the agent context at the start of every campaign call

appointmentServiceKeysstring[]

Appointment campaigns only: the agent services (serviceKey, from appointmentSettings.services) this campaign books. Left empty, a lead counts as already booked when ANY upcoming calendar event carries their phone number or email. With services picked, the event must ALSO name one of them — an upcoming event with only the phone number means a different service, so the lead is still called. Ignored for other goals.

dynamicWelcomeMessageboolean

When true, campaign calls open with an AI-generated greeting built from the campaign goal and lead context instead of the agent's fixed welcome message. Explicit opt-in: each call is then billed with a minimum duration of 10 seconds, even if it ends unanswered

welcomeMessagestring

Static opening spoken on every campaign call. Used only when dynamicWelcomeMessage is not true. Empty means the agent welcome

acceptDynamicVariablesboolean

When true (default if omitted), extra columns on a lead list become dynamicVariables automatically. When false, only leadColumns (plus phone) are accepted as extra lead fields

status'draft' | 'active' | 'paused' | 'completed'

Current status of the campaign

retriesinteger

Number of retries for the campaign (0-10; defaults to 3)

maximumConcurrentCallsnumber

Maximum number of concurrent calls for the campaign (max 100)

retryDelayMinutesinteger

Delay between retry attempts in minutes (60-40320; defaults to 240 = 4 hours)

agentIdstring

ID of the agent responsible for the campaign

sipTrunkIdsstring[]

SIP trunks to dial out from. Get IDs from POST /phones/sip-trunks/query. Required to go live unless verifiedCallerId is set.

verifiedCallerIdstring

Verified phone number used as caller ID when dialing on the company trunk

defaultCallerIdsstring[]

Pool of numbers presented to the people being called, for every lead that does not carry its own callerId. Each entry must be a number the campaign SIP trunks own (the trunk default number or an inbound trunk number / DID). One entry = every lead sees that number; several = the pool is spread across leads, each lead keeping the same number across its retries. Empty = the trunk decides, as before

lastRunAtstring date-time

ISO 8601 date string

allowedPhoneNumbersstring[]

Array of phone numbers that are allowed to be called

defaultCampaignboolean

Whether this is the default campaign for the company

processingNowboolean

Whether the campaign is currently being processed by the job service

processingNowSincestring date-time

ISO 8601 date string

Example request

{
  "name": "Q4 Sales Campaign",
  "description": "Outbound sales campaign for Q4 revenue generation",
  "type": "phone",
  "status": "draft",
  "agentId": "507f1f77bcf86cd799439012",
  "sipTrunkIds": [
    "507f1f77bcf86cd799439011"
  ],
  "retries": 3,
  "retryDelayMinutes": 240,
  "maximumConcurrentCalls": 5,
  "schedule": {
    "days": [
      {
        "day": "monday",
        "runFromTime": {
          "hours": 9,
          "minutes": 0
        },
        "runToTime": {
          "hours": 17,
          "minutes": 0
        }
      },
      {
        "day": "tuesday",
        "runFromTime": {
          "hours": 9,
          "minutes": 0
        },
        "runToTime": {
          "hours": 17,
          "minutes": 0
        }
      }
    ],
    "timeZone": "Europe/Athens",
    "runEverySeconds": 60
  }
}

Response

Campaign updated successfully

idstring required

Unique identifier

createdAtstring date-time required

Creation timestamp

activeboolean required

Whether the entity is active

createdBystring required

Name of the user who created the entity

createdByIdstring required

ID of the user who created the entity

modifiedAtstring date-time

ISO 8601 date string

modifiedBystring

Name of the user who last modified the entity

modifiedByIdstring

ID of the user who last modified the entity

companyIdstring required

Company identifier

companyobject

Any valid JSON value

groupIdsstring[]

Linked group IDs

namestring required

Name of the campaign

descriptionstring

Description of the campaign purpose and goals

type'email' | 'phone' | 'sms'

Primary channel type for the campaign

purpose'appointment' | 'lead_qualification' | 'event_invite' | 'payment_collection' | 'custom'

What the campaign is trying to achieve. Non-custom purposes seed campaign-level analysis fields and call instructions; "custom" (default) leaves everything as-is

promptSectionstring

Campaign call instructions injected into the agent context at the start of every campaign call

appointmentServiceKeysstring[]

Appointment campaigns only: the agent services (serviceKey, from appointmentSettings.services) this campaign books. Left empty, a lead counts as already booked when ANY upcoming calendar event carries their phone number or email. With services picked, the event must ALSO name one of them — an upcoming event with only the phone number means a different service, so the lead is still called. Ignored for other goals.

dynamicWelcomeMessageboolean

When true, campaign calls open with an AI-generated greeting built from the campaign goal and lead context instead of the agent's fixed welcome message. Explicit opt-in: each call is then billed with a minimum duration of 10 seconds, even if it ends unanswered

welcomeMessagestring

Static opening spoken on every campaign call. Used only when dynamicWelcomeMessage is not true. Empty means the agent welcome

acceptDynamicVariablesboolean

When true (default if omitted), extra columns on a lead list become dynamicVariables automatically. When false, only leadColumns (plus phone) are accepted as extra lead fields

status'draft' | 'active' | 'paused' | 'completed'

Current status of the campaign

retriesinteger

Number of retries for the campaign (0-10; defaults to 3)

maximumConcurrentCallsnumber

Maximum number of concurrent calls for the campaign (max 100)

retryDelayMinutesinteger

Delay between retry attempts in minutes (60-40320; defaults to 240 = 4 hours)

agentIdstring

ID of the agent responsible for the campaign

voipPhoneIdsstring[]

Legacy VoIP phone IDs. Prefer sipTrunkIds.

sipTrunkIdsstring[]

SIP trunks to dial out from. Get IDs from POST /phones/sip-trunks/query. Required to go live unless verifiedCallerId is set.

verifiedCallerIdstring

Verified phone number used as caller ID when dialing on the company trunk

defaultCallerIdsstring[]

Pool of numbers presented to the people being called, for leads without their own callerId

lastRunAtstring date-time

ISO 8601 date string

allowedPhoneNumbersstring[]

Array of phone numbers that are allowed to be called

defaultCampaignboolean

Whether this is the default campaign for the company

processingNowboolean

Whether the campaign is currently being processed by the job service

processingNowSincestring date-time

ISO 8601 date string

extensionNumberstring

Autogenerated 2–3 digit extension users dial to join the campaign

Example response

{
  "id": "123",
  "companyId": "123",
  "name": "Q4 Sales Campaign",
  "description": "Outbound sales campaign for Q4 revenue generation",
  "type": "phone",
  "status": "active",
  "retries": 3,
  "retryDelayMinutes": 30,
  "maximumConcurrentCalls": 10,
  "notificationSettings": {
    "enabled": true,
    "emails": [
      "test@example.com"
    ],
    "sendAtHour": 10
  }
}

Changes

  • 30f76840084eRevision changes
    • breaking

      the request property type changed from number to integer

    • breaking

      the request property type changed from number to integer

    • warning

      the request property's max was set to 40320.00

    • warning

      the request property's min was set to 60.00