Campaigns overview

After this guide you will be able to set a campaign up end to end: choose its settings knowingly, take it live without being refused, pause and resume it from a script, and say why a call to one of its numbers never reached a buyer.

A campaign is one stream of calls with one set of rules: one offer, one vertical, one group of tracking numbers. It exists so that the questions that are about the *call* — is it inside hours, has this person called before, what happens if nobody answers — are asked once, in one place, before the questions that are about a *buyer*. Those belong to the campaign's routing plan.

Two ways a call reaches a campaign

• Somebody dials one of its numbers. The tracking number says which campaign the call belongs to, and — when the number is tied to a publisher or sits in a number pool — who sent it. This is the path the rest of this page describes.
• A publisher pings it, wins and sends the call. The publisher's platform asks for a bid first, and the call that follows is routed by the same plan, with the auction standing in for the gates. See How RTB works.

The gates a call passes first

Before a single target is looked at, a dialled call is tested against eight gates, always in this order. The first one it fails ends the call there, with that reason code on it. Every call gets a row in the call log, including the ones that went nowhere.

When the wallet gate fails, the workspace's owners are notified and a wallet.low event is sent — at most once an hour, however many callers are turned away in it.

The settings

A campaign also shows a routingKeyPrefix. It is minted by the platform, read-only, and is what to quote to support when a question is about this campaign.

Status

Status is changed by its own request, never as a side effect of editing a setting, so a settings change cannot switch a campaign on or off by accident. A change to the status a campaign already has answers changed: false and does nothing. These changes are refused, each with a 409 that says what to do instead:

• Going live while not ready. The answer carries details.blockers — the whole list, not just the first. There are exactly two: no active tracking number points at the campaign, and the routing plan has no active route to an active target.
• Archiving a live campaign. Pause it first.
• Archiving while numbers still point at it. They would go on ringing into a campaign nobody can see, and go on being rented. Move or release them; details.numbers says how many.
• Taking an archived campaign anywhere but draft. Restoring re-checks your plan's campaign allowance, so it can also answer 402.

An optional note of up to 500 characters is stored as the campaign's statusNote — "paused for the weekend" — and cleared when the campaign goes live. Every status change is written to the activity log.

The readiness checklist

A campaign's detail carries a checklist: the journey from nothing to a routed call, each step a fact the server checked rather than a box somebody ticked. Two steps are blocking — they are the two a launch is refused on — and one is optional.

An empty wallet does not block a launch on purpose: a campaign may go live on Friday for traffic that starts on Monday. It does stop calls routing, so the checklist says so.

Worked example: a campaign from nothing to live

1. 1

   Create the campaign

   In the console, open Campaigns and create one. These are the settings for a Medicare enquiry line that is open on weekdays and Saturday mornings, sends a returning caller back to the buyer they spoke to, and reads a message to anybody it cannot place:

   The campaign's settingsCopy

   {
     "name": "Medicare enquiries",
     "verticalId": "medicare",
     "description": "Inbound enquiries from search and partner sites",
     "routingMode": "priority",
     "recordCalls": true,
     "repeatCallerPolicy": "same_target",
     "anonymousPolicy": "block",
     "dedupeWindowSeconds": 2592000,
     "unroutedAction": "message",
     "unroutedMessage": "Thank you for calling. Our lines are closed right now. Please call again tomorrow.",
     "dialTimeoutSeconds": 18,
     "failoverBudgetSeconds": 45,
     "dailyCap": 400,
     "concurrencyCap": 0,
     "hoursSchedule": {
       "tz": "America/Chicago",
       "days": {
         "mon": [
           [
             "08:00",
             "20:00"
           ]
         ],
         "tue": [
           [
             "08:00",
             "20:00"
           ]
         ],
         "wed": [
           [
             "08:00",
             "20:00"
           ]
         ],
         "thu": [
           [
             "08:00",
             "20:00"
           ]
         ],
         "fri": [
           [
             "08:00",
             "20:00"
           ]
         ],
         "sat": [
           [
             "09:00",
             "13:00"
           ]
         ],
         "sun": []
       }
     }
   }

   The campaign is created as a draft. The response already tells you what stands between it and a routed call: canGoLive is false, and blockers lists both blocking steps.

2. 2

   Give it somewhere to send calls

   Add a buyer and a target, then put the target on the campaign's Routing plan tab. See Routing plans.

3. 3

   Give it a number

   Buy a tracking number under Numbers and assign it to the campaign. See Assigning numbers.

4. 4

   Check it, then go live

   Simulate a call from a caller you choose. When the simulation ends at the target you expect, set the campaign live. canGoLive is now true and the request succeeds.

Pause and resume from a script

Creating a campaign, editing its settings, launching a draft and archiving are acts for a person in the console. An API key can do the things an integration needs day to day: read campaigns (campaigns:read), replace a routing plan, and pause and resume a campaign that is already live or paused (campaigns:write).

curl -X POST "https://api.buy3.io/api/v1/campaigns/6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d/status" \
  -H "Authorization: Bearer $BUY3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused", "note": "Buyers closed for the public holiday" }'

A resume passes the same readiness check as a launch. If somebody released the campaign's last number while it was paused, the answer is:

{
  "error": "That campaign is not ready to take calls yet",
  "code": "conflict",
  "details": {
    "blockers": [
      "No tracking number points at this campaign — buy or assign one first",
      "The routing plan has no active target — add one, or every caller goes unrouted"
    ]
  },
  "requestId": "5d1c0d2e-8a4f-4c0b-9e1d-2f3a4b5c6d7e"
}

Asking a key to set any other status, or to change a campaign that is a draft or archived, answers 409 with details.allowed listing live and paused. The full request and response shapes are in the Campaigns API reference.

Next steps