Outbound campaigns¶
An outbound campaign contacts people for you: it imports contacts, then calls and texts them, moving each contact from node to node. The ADK syncs each campaign's draft (its settings and nodes) and the code of its node functions.
Drafts only
Your files hold the campaign's draft. What is live changes only when the campaign is published. Archived campaigns are not pulled.
Location¶
outbound_campaigns/
└── {campaign_name}/
├── campaign.yaml # name, description, settings, nodes
└── functions/
└── {node_name}.py # a node function's code, only when it has code
Optional. The folder name is the campaign's name, lowercased, with punctuation replaced by _. Agent Studio allows two campaigns the same name, but each needs its own folder. When two names are the same ignoring case and punctuation, the oldest campaign keeps its name and a pull renames the other {name} (1), numbered on, with a warning. That campaign shows as changed, so a pull followed by a push sends the new name to Agent Studio.
To rename a campaign, change name and rename the folder to match. The campaign keeps its identity, contacts and history when its nodes keep their names and types, though the trigger may be renamed too. Otherwise the push deletes the old campaign and creates a new one, with a new id.
A campaign that has been published can't be deleted. Pause it, then archive it, with poly campaign pause and poly campaign archive. It stops being pulled once it's archived.
When a campaign is renamed in Agent Studio, a pull moves its folder, and your edits to its saved nodes and code move too, as for a renamed flow. Nodes and function files you added since the last pull stay in the old folder: move them across by hand.
When two campaigns swap names in Agent Studio, or one is deleted and another renamed to its name, the folder then holds a different campaign. Edits you made there before the pull now apply to the campaign that has that name, and the next push sends them to it. Pull before editing after such changes.
What a campaign contains¶
Fields¶
| Field | Required | Description |
|---|---|---|
name |
Yes | The campaign's name, under 256 characters. |
description |
No | Text under 1024 characters. A pull leaves it out when there is none. |
settings |
No | The campaign's settings (below). Fields left out take their defaults, and a pull leaves out settings that aren't set. |
nodes |
No | The campaign's nodes (below), in any order you like. |
Settings¶
| Field | Description |
|---|---|
start_date, end_date |
ISO dates the campaign runs between. |
from_number, sms_from_number |
Numbers calls and texts come from. |
sip_trunk_id |
The SIP trunk calls go out through. |
default_variant |
Name of the variant the campaign's calls use. |
country |
ISO 3166-1 alpha-2 code in capitals, e.g. US. Required to publish. |
use_case |
transactional or marketing. Required to publish. |
daily_contact_limit |
Most times a contact is reached per day. Defaults to 3. |
voice_dispatch_limits, sms_dispatch_limits |
max_concurrent, per_hour and per_day caps. Left out when no cap is set. |
default_timezone |
IANA time zone, used for a contact with none. |
contact_window |
days_of_week (monday to sunday), and start_time and end_time as "HH:mm" in the contact's time zone. |
Settings the ADK doesn't know yet are kept as they were pulled, but the ADK can't send them. A settings change replaces every setting, so change the settings of a campaign that has any in Agent Studio, or update the ADK.
Nodes¶
Each node has a name, unique in the campaign, and a type with that type's fields. Nodes refer to each other by name. A node's function code lives in functions/{node_name}.py, with the name lowercased and punctuation replaced by _. Names are compared ignoring case and punctuation, so when Agent Studio has nodes named Call and call, a pull numbers the second one, as in call 2. A node Agent Studio has with no name, or with a name another node has, is named on pull and shows as changed until your next push sends that name.
| Type | Fields |
|---|---|
trigger |
function, routes (each a next and an optional outcome), source_type (csv, api or webhook; default csv), ingest_interval (hourly, daily or manual; default daily) |
call |
flow_name, amd_flow_name (optional), function, greeting, voicemail_enabled, voicemail_script and voicemail_when (detection or final_retry), max_attempts (1 to 5), backoff, backoff_unit (minutes, hours or days), default_route |
sms |
function, message_template, reply_flow_name, reply_timeout_value and reply_timeout_unit (all optional), default_route |
conditional |
function, branches (each a variable and next), default_next |
wait |
amount, unit, next |
writeback |
target (api or csv), function, next |
end |
exit_reason, writeback_enabled, function (optional) |
next, default_next and default_route name the node a contact moves to next. Branches have no id in the file: a branch keeps its id in Agent Studio while its variable stays the same, and a new branch gets a new one. A call or text always moves to its default_route; put a conditional after it to branch on how it went. Flow fields hold a flow's name.
Every node except wait and end has a function, and an end node may have one. A function has a name (a valid Python name) and a description. Its code goes in the node's .py file, whose def line takes exactly the parameters the node is called with:
| Node | Parameters |
|---|---|
trigger with source_type: csv |
contacts, outbound_campaign |
trigger with source_type: api |
outbound_campaign, sync |
writeback with target: csv |
outbound_contacts, outbound_campaign |
Any other call, sms, conditional, writeback or end |
outbound_contact, outbound_campaign |
A webhook trigger runs no function.
Node positions on the Agent Studio canvas are not in the file. A node keeps its position, and a new node is placed next to the node that routes to it.
Renaming a node
A node's name is its identity in your files. A campaign has one trigger, so renaming or replacing the trigger keeps its id and history. Renaming any other node, or changing its type, deletes the node and creates a new one with a new id, which starts its history again. Rename its .py file to match.
Example¶
name: Appointment reminders
description: Reminds patients of their appointment.
settings:
from_number: '+15550100'
country: US
use_case: transactional
contact_window:
days_of_week: [monday, tuesday, wednesday, thursday, friday]
start_time: '09:00'
end_time: '17:00'
nodes:
- name: Import contacts
type: trigger
function: {name: map_contacts, description: Maps CSV rows to contacts.}
routes:
- next: Reminder call
- name: Reminder call
type: call
flow_name: Reminder
function: {name: call_args, description: Passes the appointment to the call.}
greeting: Hi, this is a reminder about your appointment.
voicemail_enabled: false
max_attempts: 2
backoff: 1
backoff_unit: hours
default_route: Done
- name: Done
type: end
exit_reason: completed
writeback_enabled: false
functions/import_contacts.py:
def map_contacts(contacts: list[dict], outbound_campaign: OutboundCampaign):
return {"contacts": [...]}
Validation¶
poly validate and poly push check:
nameis present and under 256 characters, anddescriptionunder 1024.- The folder name matches the campaign's name.
- A campaign deleted in the push has never been published.
- Settings have the right types and allowed values:
use_caseistransactionalormarketing, and limits are positive whole numbers.countryis a real ISO 3166-1 alpha-2 code, in capitals.default_timezoneis a valid IANA time zone.end_dateis not beforestart_date.contact_windowhas at least one day, its times areHH:mm, and it ends after it starts.- A campaign with settings the ADK doesn't know has no settings changed, and a new campaign has none.
nodesis a list, every node has a name, and names are unique in the campaign, ignoring case and punctuation.- There is at most one
triggernode, and a campaign that has a trigger in Agent Studio keeps one: rename or replace its trigger rather than delete it. - The trigger changes
typeonly when another node becomes the trigger in the same push, and a published campaign's trigger keeps itssource_type. - Each node has a known
type, its required fields, allowed values, and no fields its type doesn't have. - A
conditionalnode uses each branchvariableonce. voicemail_scriptandvoicemail_whenare set whenvoicemail_enabledis true.- On a node that is new, changed type or had its routes changed, every route names a node in the campaign. Agent Studio keeps a route to a deleted node until you change it.
- Function names are valid Python names, and
codeis not in the YAML. - On a node that is new, changed type, or had its code, function name or parameters changed, the function's
defline is whole on one line and takes exactly the node's parameters. - Every file in
functions/belongs to a node with a function, and a node's file is named after it. After renaming a node, rename its file too.
Best practices¶
- Name nodes after what they do, like
Reminder call, so routes read clearly. - Keep node names stable: renaming a node other than the trigger gives it a new identity and history.
- Make a campaign on a branch, merge it, then publish it from
main.
Related pages¶
-
Flows
Call and SMS nodes enter a flow by its name. Open flows