> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 23. Outbound campaign

> From a contact file to the first dial: import, retries, calling windows, attestation.

# Outbound campaign: from a file to the first dial

> [!NOTE]
>
> **Module goal:** launch calling over a contact list with the right calling windows, retries and a signed attestation.

![Campaign list with filters and progress](https://mintcdn.com/hubtalk/UuNkjJ26eB-xpPwv/images/tutorial/tut-46-campaigns-list_en.webp?fit=max\&auto=format\&n=UuNkjJ26eB-xpPwv\&q=85\&s=7f4b8abc2d195ff72c4238e5778897fe)

Campaigns — the campaign list: status, dates, speed, number of contacts and progress.

A campaign is assembled by a wizard on a page of its own — **five steps**, and all of them can be revisited while the campaign is a **Draft**. **Next** does not let you move on with incomplete data and names the missing fields.

**1. Campaign**

Name, agent and **classification** — the purpose of the calls: Marketing, Servicing or Debt collection. It determines the required consent tier and the attestation text you sign on the fifth step.

**2. Schedule**

The date range, time zone, working hours and — on the `kz` profile — the Call in the contact's local time checkbox.

**3. Dialing**

Trunk, subgroup and caller ID (the collapsible Telephony group), dialing speed or auto-speed mode, what to do with duplicates, retries and the dialing logic.

**4. Contacts**

CSV or XLSX. The phone column is recognized by its header, and **every other column becomes a call variable**. This is also where you read the import report: how many rows were accepted, what was rejected and why.

**5. Review and launch**

Blockers, warnings and the attestation signature.

> [!NOTE]
>
> The campaign record is created when you move on to the **Contacts** step — before that there is nowhere to upload a file. **A campaign that already exists is not edited in the wizard** but in the dialog box opened from its card; the fields are the same.

> [!NOTE]
>
> **The agent picker on the first step is a searchable list.** Type a few letters of the name instead of scrolling; the other agent pickers work the same way — the inbound subgroup card, the test call dialog, the phrase correction rule.
>
> The list offers only published agents, and to a member — only those [marked as visible to members](https://docs.hubtalk.ai/v4/platform/agents/list.md): unfinished and retired agents are not shown to them at all. An administrator and a developer see all agents, and a hidden one has "· hidden from members" added to its name. If an agent is hidden after the campaign has been assembled, the campaign keeps working and can be edited, but a member will not be able to **launch** it — a blocker appears on the review step.

![Campaign creation wizard: the Campaign step — name, agent and classification](https://mintcdn.com/hubtalk/UuNkjJ26eB-xpPwv/images/tutorial/tut-47-campaign-create_en.webp?fit=max\&auto=format\&n=UuNkjJ26eB-xpPwv\&q=85\&s=e09c921482b1e66c61c18f35dc317fd1)

The first wizard step, Campaign: name, agent and classification. Dialing speed and retries come later, on the Dialing step: the speed is picked from fixed tiers or set as a custom number, and Dialing logic is Standard (retries and an interval) or Expert logic (rules by reason).

> [!WARNING]
>
> **Dialing speed means exactly what it says.** It is any whole number from 1 to **200** calls per minute. The list has nine ready-made values; for any other, tick **Set a custom speed** and enter the number in the **Calls per minute** field. There is no platform ceiling that would cut the value you chose. The trunk subgroup may have its own calls-per-minute limit — see [module 22](https://docs.hubtalk.ai/v4/tutorial/telephony.md).

> [!TIP]
>
> **Not sure what speed to set? Tick Auto-speed mode.** Then the platform picks the speed: it works out how many dials are still needed, callbacks included, picks a pace at which every attempt fits before the campaign end and recomputes every 10 minutes, staying within the subgroup limit and the concurrent call limit. It needs an end date, and a campaign over several days also needs working hours. On the **Review and launch** step the **Speed** group shows how much is needed, how much is achievable and what limits it: if the limits won't let you finish in time, you learn it before the launch rather than in the evening from an undialed base. Details — [Auto speed](https://docs.hubtalk.ai/v4/platform/campaign-launch.md#auto-speed).

![Campaign card: metrics, outcome breakdown, dialing configuration and frequency settings](https://mintcdn.com/hubtalk/UuNkjJ26eB-xpPwv/images/tutorial/tut-48-campaign-card_en.webp?fit=max\&auto=format\&n=UuNkjJ26eB-xpPwv\&q=85\&s=850da326453d3ab3a3f0c49e36393a31)

The campaign card: metrics, the outcome breakdown, the dialing configuration (after launch only the dialing speed and auto-speed mode can be changed) and the frequency settings.

## Contact file: limits and columns

CSV or XLSX; the old **XLS is not supported**. Up to **50,000 rows** and **10 MB** — a file over the limit is rejected in full, not truncated. One column is required — the phone: the platform finds it by its header (`phone`, `mobile`, `tel` and similar), and if there is no recognizable header — by its content. The name is taken from `name` / `full_name` or built from `first_name` and `last_name`. Every other column becomes a call variable.

> [!NOTE]
>
> **Columns that depend on the market.** On the `us_tcpa` profile the file also needs a `contact_zip` or `contact_state` column: the platform uses it to determine the contact's local time and the legal calling window. A file with neither column is rejected in full. On the `kz` profile no location columns are needed; if Call in the contact's local time is ticked, the time zone is taken from the `timezone` column. Details — [Campaign contacts](https://docs.hubtalk.ai/v4/platform/campaigns/contacts.md).

> [!TIP]
>
> **The most useful trick in the whole module: download a sample file right from the campaign creation form.** The sample is built **for the specific agent** — it already has the columns the agent uses in its prompts. This is exactly the check people otherwise do by hand, comparing the `{{variables}}` in the nodes with the headers in Excel.

**Duplicate numbers** — three options: Reject duplicates (the default; repeats go to the report as errors), Keep first occurrence or Keep last occurrence. In any case **a number enters the campaign at most once**; repeat dials happen only as retries after a failed attempt.

## The import report — a must-read

In the screenshot: 6 accepted, 1 with warnings, 1 rejected, 1 duplicate found. The report names the **row numbers** and the reason (rows without a readable phone — row 8), can be exported to CSV/XLSX and is stored with the upload version.

A separate note on geography on the `us_tcpa` profile: if even one row is rejected as having no usable location, **the launch is blocked entirely** — with the number of rows and the file name. There is no workaround and no partial launch: fix the file and upload it again. Below are the variables table and a red line saying that the agent uses variables the file has no columns for: they will be empty. This is the most common reason for "the agent says strange things": the prompt has `{{doctor}}`, and the file has no such column.

## Retries: standard and expert logic

Standard logic is "call back up to N times with interval M". What is counted is **retries** (0–29); the first dial is not included in that number, and the screen always shows both figures: "9 retries · 10 dials".

The interval is set in two modes:

* **Same interval** — one identical pause between all dials of the same number.
* **Per-retry intervals** — an interval for each retry separately, on the **Retry 1**, **Retry 2**, … pills. This is how "often first, rarely later" is built: 2 min → 5 min → 1 d → 3 d. Values come from a fixed list, **from 1 minute to 7 days**.

If the retry ladder does not fit into the campaign dates, the launch warns you ("N retries will not happen") but does not block.

Expert logic is rules of the form "if *reason* → *action*": for example `No answer → Redial on the next pass (up to 2 times)`, `Busy → Redial after a delay (in 10 min)`, `Voicemail reached → Stop calling this number`, `Goal not achieved → redial`. For permanent reasons (wrong number, spam block) a retry is forbidden by the schema — as it should be.

You don't have to assemble the rules by hand every time: above the rule editor is the **Strategy preset** selector with three built-in sets — **Default** (busy up to 3 redials, no answer up to 2), **Aggressive** (busy ×5, no answer ×4, voicemail ×2, a hang-up within the first 15 seconds is redialed) and **Conservative** (busy ×2, no answer ×1, voicemail and a hang-up within the first 10 seconds stop the number). Your own set is saved with **Save as preset** and reused in other campaigns; up to 20 presets per organization.

> [!WARNING]
>
> **Two pitfalls with presets.** First: any edit to a rule switches the selector to Own rules — that is normal, but Save as preset is available only in this state. Second: a preset carries **only the rules**; the number of retries and the intervals stay campaign fields — picking a preset does not change them. And editing your preset does not update campaigns that were already set up.

> [!NOTE]
>
> **What counts as a permanent reason depends on the market.** Declined by callee and Declined by a call screener close the number for good on the `us_tcpa` profile; on the `kz` profile these are transient reasons — the number returns to dialing and spends an attempt.
>
> **Voicemail without a rule is redialed.** Expert logic is standard logic plus rules: an outcome with no rule (or whose rule has used up its **Times**) is handled by standard logic, and that redials voicemail after the campaign interval. If you don't want to redial voicemail, add the rule Voicemail reached → Stop calling this number.

## Frequency: how many times a person may be called at all

Retries answer the question "when to dial again". Frequency limits answer a different one — "how many times may this number be called at all", and they are counted per number across all of the organization's campaigns at once. Two campaigns calling the same person share one budget, so a retry ladder may stop short not because of an error but because of frequency.

In the campaign wizard and on the card, each limit shows four things: the **Applied limit** (what is actually in force), **Set by** — Organization, Platform default or Campaign, the **recommendation**, and a **Not applicable to this campaign type** note when the limit does not apply to this kind of campaign. Legal caps are not in this block: which restriction exactly applied to a contact is visible in its stored frequency decision.

> [!WARNING]
>
> **A campaign setting can only tighten.** The block is called Setting for this campaign and accepts values stricter than the organization's: a lower limit or a longer pause. Anything looser the server will refuse to save — better to learn that here than at the Save button before launch.

The campaign progress has a **Frequency** block: it separates contacts **held** by a restriction (we will call later) from contacts **closed** by it (this campaign will not call them). In the contact listing, each contact shows the reason and the stored frequency decision — which restriction fired, with which counters and until when.

> [!NOTE]
>
> **The default limits depend on the market.** The recommended values are the same for both profiles — 2 calls per day, 7 per week, a 24-hour pause after a conversation.
>
> * **`us_tcpa`** — the limits are on from the start, and on top of them the state's legal caps apply by the contact's location, and for Debt collection campaigns — Reg F: at most 7 calls in 7 days per debt and a 7-day pause after a conversation.
> * **`kz`** — the limits are off: the market norm is the calling window and the do-not-call registry. If you need limits, turn them on yourself — it will be the company's voluntary self-restriction.
>
> Details — in [Call frequency](https://docs.hubtalk.ai/v4/platform/campaigns/frequency.md).

![The Review and launch step: summary, warnings and the consent attestation](https://mintcdn.com/hubtalk/UuNkjJ26eB-xpPwv/images/tutorial/tut-49-campaign-launch_en.webp?fit=max\&auto=format\&n=UuNkjJ26eB-xpPwv\&q=85\&s=d3f96cfc6f77bfa51c435b9855f0d8ef)

Launch. Before the first dial — the review (the agent is published, the trunk is alive, there are contacts, the windows are set) and the consent attestation: a signature confirming that consent to the call was obtained. The wording comes from the server and depends on the campaign classification; the signature is stored with your name and time and is reset when the contact file is replaced.

> [!NOTE]
>
> **Working hours and time zones**
>
> The schedule is set by weekdays and intervals (the Restrict to a schedule (optional) toggle). **An empty schedule does not mean "around the clock"**, and what limits dialing depends on the market profile.
>
> **`us_tcpa`.** Time is always computed in the contact's local time, so there is no checkbox: the time zone comes from `contact_zip` or `contact_state`. The window is the intersection of the federal one (8:00–21:00), the state's rules (in many states the evening ends earlier, and there are forbidden days and holidays) and the campaign working hours; the strictest wins. An empty schedule = the whole legal window of the contact's state. Details — [US campaigns](https://docs.hubtalk.ai/v4/platform/campaigns/us-market.md).
>
> **`kz`.** If no schedule is set, the **organization's calling window** applies — 08:00–21:00 by default, and the form says so directly. The campaign schedule can only narrow the window: a schedule wider than the window is not saved, a contact outside the window is deferred until it next opens, and if the window and the schedule no longer intersect, the contact is refused with the reason "empty intersection". The window is set by the platform — in the organization settings it is read-only; a change applies at once to all of the organization's campaigns, including running ones. The **Call in the contact's local time** checkbox takes the time zone from the file's `timezone` column: Almaty and Aktobe are an hour apart, and "09:00 campaign time" may turn out to be 08:00 for the customer.

> [!WARNING]
>
> **Pausing and stopping**
>
> A campaign can be paused and resumed; a cancelled one cannot. Pausing and cancelling stop dialing at once, within the current cycle: calls in progress finish, new ones don't start — at most a few dials that had already begun may go out. After launch the dialing configuration is frozen: to change the rules or the retries you need a new campaign. Only the dialing speed and auto-speed mode can be changed — the **Settings** button on the campaign card, while the campaign is neither completed nor cancelled. That is why the first launch is done on 20–30 contacts, not on the whole base.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.