Update campaign

Update campaign settings through their owning sections.

Read the campaign with GET /api/agent-builder/agents/{id}/campaign before changing it. Send only the sections you want to change.

Section	Settings
trigger	Outbound entry/exclusion tags; reminder appointment calendar; inbound call entry.
capabilities	Installed booking, transfer and tagging settings.
tools	Installed service-area and tag-check tools.
calling	Dialing rules and the campaign’s single cadence, including its ordered steps.
outcomes	Wording used to recognize call results.

Capability/tool maps are partial: omitted entries stay unchanged; null removes one. Arrays replace only their field.

When the agent is shared with another campaign outside a master agent family, capability and outcome changes are refused with 409. A partial save returns 502 with actionResults. Use Idempotency-Key for retries: the same key replays the recorded result, including a partial failure, without repeating completed effects. Read the campaign before sending remaining changes with a new key. Required scope: campaigns:write.

smsFromNumber is the number the campaign’s texts come from: its cadence’s text steps and a chat campaign’s replies. An empty string or null clears it.

chatChannels is the list of chat channels its TFU Live agent answers on: SMS, always kept, plus any of FB (Facebook Messenger), IG (Instagram) and WHATSAPP. Each direct-message channel needs that page, account or number connected in GoHighLevel; on another CRM, the built-in one included, adding one is refused with 400 ChatChannelsNeedGhl. The agent only answers a lead who writes there first, within 24 hours of their last message.

answerWaitingMessage, true, makes a TFU Live agent answer the message a lead sent before they were tagged onto the campaign, when it is the latest in the conversation, unanswered and at most 24 hours old. It covers leads with no phone number who wrote on Messenger or Instagram. Off unless true: the agent then answers only messages sent after the tag.

A TFU Live agent. Send its tfu_live: id with locationId, its sub-account (campaignId only when several campaigns use it). An API key or OAuth client also needs agents:write. Its campaign takes the same settings as any campaign: trigger tags (start tags also add a tag start when it has none), calling (window, switches and the cadence of calls and texts), smsFromNumber, chatChannels, answerWaitingMessage and testing, through the same checks. Settings that belong to the TFU Live agent itself are refused with 422 TFU_LIVE_CAMPAIGN_SETTING_ELSEWHERE, and details.use gives the API route that changes each one. Capabilities, tools and outcomes are its workflows, changed with PUT /api/tfu-live-agents/{id}/workflows/{workflowId}. For fromNumbers, use POST /api/tfu-live-agents/{id}/numbers/attach. For active, use POST /api/tfu-live-agents/{id}/go-live, which runs the go-live check, or POST /api/tfu-live-agents/{id}/pause. For masterCampaignEnabled, use PUT /api/agent-builder/projects/{locationId}/tfu-live-families/{profileId}. Its agentId cannot change. Sent back unchanged, the value the read gives for active, agentId, fromNumbers, masterCampaignEnabled or testing changes nothing. See Set up a TFU Live agent’s campaign.

Required API key scope: campaigns:write.

PATCH

api

agent-builder

agents

{id}

campaign

cURL

curl --request PATCH \
  --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcomes": {
    "callback": {
      "prompt": "The person explicitly agreed to another call."
    }
  }
}'

import requests

url = "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "campaign": {
    "id": "cmp_123",
    "name": "Follow up",
    "active": false,
    "agentId": "agent_123",
    "campaignType": "outbound",
    "trigger": {
      "type": "outbound",
      "activeTags": [
        "new_lead"
      ],
      "inactiveTags": []
    },
    "capabilities": {},
    "tools": {},
    "calling": {
      "window": null,
      "speedToLead": true,
      "powerDialer": false
    },
    "testing": {
      "collectContextFields": false
    }
  },
  "actionResults": {
    "abilities": "unchanged",
    "settings": "saved",
    "cadence": "unchanged",
    "outcomes": "unchanged"
  }
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Headers

Idempotency-Key

string

Reuse a unique key for retries of the exact same change. A retry returns its saved result or partial-failure receipt without repeating effects. Pending or changed-payload reuse returns 409. After a partial failure, read the campaign before submitting only the remaining changes with a new key.

Required string length: 1 - 128

Path Parameters

string

required

Agent id, or a TFU Live agent’s tfu_live: id.

Minimum string length: 1

Query Parameters

locationId

string

Pair with campaignId; omit both for primary campaign.

Minimum string length: 1

campaignId

string

Pair with locationId; omit both for primary campaign.

Minimum string length: 1

Body

application/json

Partial update of the selected campaign. Trigger fields must match its stored campaignType. Omitted sections and named abilities stay unchanged. null removes one named capability/tool; arrays replace only that field. An absent ability requires enabled:true to install. Root config, calendarId, transferNumber, activeTags and inactiveTags are not accepted.

name

string

Minimum string length: 1

description

string

A note about the campaign for people. Calls do not use it.

active

boolean

True switches the campaign live. False pauses it.

agentId

string | null

Change the bound agent separately from capability, tool or outcome edits.

campaignType

enum<string>

Optional assertion about the selected campaign; its type cannot be changed.

Available options:

outbound,

confirmation,

inbound

trigger

object

Must match the selected campaign type. Outbound accepts activeTags/inactiveTags. Confirmation/reminder accepts calendarId, which also supplies rescheduling. Inbound accepts neither tags nor an appointment calendar. Include type when changing a trigger; it cannot change the campaign type.

Option 1
Option 2
Option 3

Show child attributes

capabilities

object

Named installed capabilities. Outbound/inbound booking calendarId/calendarRules/collectAddress belong inside appointment_booking. Confirmation uses trigger.calendarId and has no separate booking routing/address settings. Transfer destinations, messages and routing belong inside live_transfer. An absent entry requires enabled:true to install; null removes it, and omitted siblings survive. Zero capabilities is valid. Optionally send campaign.metadata.inventoryVersion from Get campaign as expectedVersion to reject a stale inventory edit. Agents shared outside one explicit Master agent family must be separated before editing installations.

Show child attributes

tools

object

Partial map of named platform tool installations. An absent entry requires enabled:true; null removes only that entry. Omitted tools, capabilities and instruction playbooks stay unchanged. Shares the inventory expectedVersion guard.

Show child attributes

calling

object

The campaign’s dialing rules and single cadence. Patch cadence.name or cadence.activeDays independently; cadence.steps replaces the complete step list. No cadenceId is accepted. Outbound and confirmation campaigns support independent speedToLead and powerDialer switches. For reminders, skipWhenAiBooked suppresses only the immediate booking-time call, preserving scheduled reminders. Inbound refuses this section.

Show child attributes

fromNumbers

string[]

The campaign's phone numbers. Calls go out from them, and an inbound campaign answers on them.

answerCalls

string[]

Use with fromNumbers. Numbers whose incoming calls this campaign takes over. A number nobody answers is taken without being listed. Other numbers keep their answering campaign.

Maximum array length: 100

smsFromNumber

string | null

The number this campaign’s texts come from. That covers the text steps of its cadence and a chat campaign’s replies. A number on the sub-account’s own phone system, in international format (+14155550123). An empty string or null clears it, so texts go from the sub-account’s default number.

Pattern: ^(\+[1-9]\d{7,14})?$

chatChannels

string[] | null

TFU Live chat channels: SMS (always kept), FB (Messenger), IG (Instagram), WHATSAPP. Whether the agent texts at all is its Chat switch. With FB, IG or WHATSAPP the agent also answers a lead who writes on that channel, within 24 hours of their last message, and never starts a conversation there. Each needs the Facebook page, Instagram account or WhatsApp number connected in GoHighLevel; on a sub-account with another CRM, the built-in one included, adding one is refused with 400 ChatChannelsNeedGhl. Case does not matter and repeats are removed; any other value is refused with 400 ChatChannelsInvalid. The list replaces the stored one. [] or null means SMS only. EMAIL, which some older campaigns carry, is kept as stored.

answerWaitingMessage

boolean

TFU Live: true makes the agent answer the message a lead sent before they were tagged onto this campaign. It applies when that message is the latest in the conversation, nobody has replied to it, it is at most 24 hours old and it is on a chat channel the campaign answers. It covers leads with no phone number who wrote on Messenger or Instagram. Off unless true: the agent then answers only messages sent after the tag.

testing

object

Settings for the campaign's shareable test form.

Show child attributes

maxCallMinutes

integer | null

Longest call on this campaign, in minutes, 1 to 120, for every campaign type. null restores the default, 15. A call also stops when its funded minutes run out. Not used by TFU Live campaigns, which keep their own limit.

Required range: 1 <= x <= 120

masterCampaignEnabled

boolean

True makes this campaign a master agent. Link other sub-accounts to it with POST /api/agent-builder/agents/{id}/campaign/master/projects.

outcomes

object

Partial map of outcome prompts, each { prompt: text }. Omitted outcomes are unchanged. Outcome prompts are stored on the bound agent, so an edit returns 409 if that agent is shared outside one explicit Master agent family. Split variants continue sharing their campaign settings.

Show child attributes

expectedVersion

integer

Optional stale-edit guard. Copy campaign.metadata.inventoryVersion from Get campaign. A mismatch returns 409 before capability/tool changes. This guards inventory edits, not the whole campaign.

Required range: 0 <= x <= 9007199254740991

Response

Campaign facet updated.

success

any

required

campaign

object

required

Show child attributes

actionResults

object

required

Show child attributes

cURL

curl --request PATCH \
  --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcomes": {
    "callback": {
      "prompt": "The person explicitly agreed to another call."
    }
  }
}'

import requests

url = "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "campaign": {
    "id": "cmp_123",
    "name": "Follow up",
    "active": false,
    "agentId": "agent_123",
    "campaignType": "outbound",
    "trigger": {
      "type": "outbound",
      "activeTags": [
        "new_lead"
      ],
      "inactiveTags": []
    },
    "capabilities": {},
    "tools": {},
    "calling": {
      "window": null,
      "speedToLead": true,
      "powerDialer": false
    },
    "testing": {
      "collectContextFields": false
    }
  },
  "actionResults": {
    "abilities": "unchanged",
    "settings": "saved",
    "cadence": "unchanged",
    "outcomes": "unchanged"
  }
}

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Caller ID

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

Update campaign

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response