---
title: "How to Setup a Call Control Object"
slug: "how-to-setup-a-call-control-object"
updated: 2026-05-07T15:34:40Z
published: 2026-05-07T15:34:40Z
canonical: "docs.natterbox.com/how-to-setup-a-call-control-object"
---

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

# How to Setup a Call Control Object

> [!NOTE]
> This guide is intended for advanced Natterbox admins. Further customisations of this solution might not be supported.

**Requirement:** Contact Centre Licences

## Overview

The Call Control Object allows you to manage inbound call routing entirely from Salesforce records — no routing policy changes needed. Admins can:

- Set weekly opening and closing hours (in local time)
- One Record to handle Holiday/Open hour rules on multiple policies
- Handle multiple time zones with automatic daylight saving adjustment
- Pre-set holiday routing and TTS messages using reusable slots
- Force lines closed for emergencies
- Dynamically route calls based on all of the above

Once created, you'll use a [Query Object App](/v1/docs/query-object-app) in your routing policy to pull the record data, and a [Rule App (Evaluate)](/v1/docs/rule-app) to route calls based on the result.

## How It Works

1. A call arrives at the routing policy
2. The [Query Object App](/v1/docs/query-object-app) runs a query against your Call Control record
3. Salesforce evaluates all formula fields at query time (timezone conversion, holiday checks, open/closed status)
4. The [Rule App (Evaluate)](/v1/docs/rule-app) checks the returned values and routes the call:
  - Force Closed? → Play emergency message → Hang up/Voicemail
  - Holiday Active? → Play holiday message → Hang up/Voicemail
  - Out of Hours? → Play closed message → Hang up/Voicemail
  - None of the above? → Route to your normal call flow

### Step 1: Create the Custom Object

1. Navigate to Setup → Object Manager → Create → Custom Object
2. Configure the following settings:

| Setting | Value |
| --- | --- |
| Label | Call Control |
| Plural Label | Call Controls |
| API Name | Call_Control__c |
| Record Name | Routing Policy Name |
| Data Type | Text |
| Allow Reports | ☑ |
| Allow Activities | ☐ |
| Track Field History | ☑ |
| Allow Search | ☑ |
| Allow Bulk API Access | ☑ |
| Allow Streaming API Access | ☑ |

1. Click **Save.**

### Step 2: Set Permissions

The Natterbox integration user (the user your Natterbox AVS connector authenticates as) needs **Read** access to this object and all its fields.

1. Go to **Setup** → **Permission Sets** (or Profiles)
2. Find the permission set/profile assigned to your Natterbox integration user
3. Under **Object Settings**, find **Call Control**
4. Enable **Read** access on the object
5. Enable **Read** access on **all fields**

### Step 3: Create a Tab

1. Go to **Setup** → **Tabs** → **Custom Object Tabs** → **New**
2. Select **Call Control** as the object
3. Choose a Tab Style (the clock icon works well)
4. Add it to the relevant App (e.g., your Natterbox app or admin app)
5. Click **Save**

### Step 4: Create the Fields

Navigate to **Setup** → **Object Manager** → **Call Control** → **Fields & Relationships** → **New** for each field below.

#### 4.1 — UTC Offset

| **Setting** | Value |
| --- | --- |
| Field Type | Number |
| Field Label | UTC Offset |
| API Name | UTC_Offset |
| Length | 2 |
| Decimal Places | 1 |
| Required | ☑ |
| Description | Standard (winter) UTC offset for this policy's timezone. E.g. -5 for US Eastern, 0 for UK, +1 for CET, +5.5 for India. |
| Help Text | Enter the standard UTC offset (not DST). See timezone reference table. |

#### 4.2 — DST Rule

| Setting | Value |
| --- | --- |
| Field Type | Picklist |
| Field Label | DST Rule |
| API Name | DST_Rule |
| Values | US / EU / None (one per line) |
| Default Value | None |
| Required | ☑ |
| Description | Which daylight saving rule applies. US = Second Sunday March to First Sunday November. EU = Last Sunday March to Last Sunday October. None = No DST observed. |
| Help Text | Select the DST rule for this timezone. Choose None if the region does not observe daylight saving. |

#### 4.3 — Monday Open

| Setting | Value |
| --- | --- |
| Field Type | Time |
| Field Label | Monday Open |
| API Name | Monday_Open |
| Required | ☐ |
| Description | Opening time on Monday in local time |
| Help Text | Enter the time this line opens on Monday in local time (e.g. 09:00). Leave blank if closed on this day. |

#### 4.4 — Monday Closed

| Setting | Value |
| --- | --- |
| Field Type | Time |
| Field Label | Monday Closed |
| API Name | Monday_Closed |
| Required | ☐ |
| Description | Closing time on Monday in local time |
| Help Text | Enter the time this line closes on Monday in local time (e.g. 17:30). Leave blank if closed on this day. |

#### 4.5–4.16 — Tuesday through Sunday - Repeat the same steps as 4.3 and 4.4 for each remaining day. All are **Time** fields, with the required field UNCHECKED

| Label | API Name |
| --- | --- |
| Tuesday Open | Tuesday_Open |
| Tuesday Closed | Tuesday_Closed |
| Wednesday Open | Wednesday_Open |
| Wednesday Closed | Wednesday_Closed |
| Thursday Open | Thursday_Open |
| Thursday Closed | Thursday_Closed |
| Friday Open | Friday_Open |
| Friday Closed | Friday_Closed |
| Saturday Open | Saturday_Open |
| Saturday Closed | Saturday_Closed |
| Sunday Open | Sunday_Open |
| Sunday Closed | Sunday_Closed |

#### 4.17 — DST Active

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Checkbox |
| Field Label | DST Active |
| API Name | DST_Active |
| Description | Returns true if daylight saving time is currently active based on the DST Rule for this record. |

Formula:

```sql
IF(TEXT(DST_Rule__c) = "US",
  AND(
    TODAY() >= DATE(YEAR(TODAY()), 3, 8) + MOD(1 - WEEKDAY(DATE(YEAR(TODAY()), 3, 8)) + 7, 7),
    TODAY() < DATE(YEAR(TODAY()), 11, 1) + MOD(1 - WEEKDAY(DATE(YEAR(TODAY()), 11, 1)) + 7, 7)
  ),
  IF(TEXT(DST_Rule__c) = "EU",
    AND(
      TODAY() >= DATE(YEAR(TODAY()), 3, 31) - MOD(WEEKDAY(DATE(YEAR(TODAY()), 3, 31)) - 1, 7),
      TODAY() < DATE(YEAR(TODAY()), 10, 31) - MOD(WEEKDAY(DATE(YEAR(TODAY()), 10, 31)) - 1, 7)
    ),
    false
  )
)
```

Click **Check Syntax** to validate before saving.

#### 4.18 — Current Time

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Time |
| Field Label | Current Time |
| API Name | Current_Time |
| Description | The current time converted to the local timezone for this record. Uses UTC Offset + DST Active to calculate. |

Formula:

```plaintext
TIMEVALUE(NOW() + ((UTC_Offset__c + IF(DST_Active__c, 1, 0)) / 24))
```

#### 4.19 — Open Today

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Time |
| Field Label | Open Today |
| API Name | Open_Today |
| Description | Returns the opening time for the current day of the week. |

Formula:

```plaintext
CASE(
  WEEKDAY(TODAY()),
  2, Monday_Open__c,
  3, Tuesday_Open__c,
  4, Wednesday_Open__c,
  5, Thursday_Open__c,
  6, Friday_Open__c,
  7, Saturday_Open__c,
  Sunday_Open__c
)
```

#### 4.20 — Closed Today

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Time |
| Field Label | Closed Today |
| API Name | Closed_Today |
| Description | Returns the closing time for the current day of the week. |

Formula:

```plaintext
CASE(
  WEEKDAY(TODAY()),
  2, Monday_Closed__c,
  3, Tuesday_Closed__c,
  4, Wednesday_Closed__c,
  5, Thursday_Closed__c,
  6, Friday_Closed__c,
  7, Saturday_Closed__c,
  Sunday_Closed__c
)
```

#### 4.21 — Currently Open

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Checkbox |
| Field Label | Currently Open |
| API Name | Currently_Open |
| Description | Returns true if the current local time is between today's opening and closing hours. This is the primary field used by the routing policy. |

Formula:

```plaintext
AND(
  NOT(ISBLANK(Open_Today__c)),
  Current_Time__c >= Open_Today__c,
  Current_Time__c <= Closed_Today__c
)
```

#### 4.22–4.41 — Holiday Slots

Rather than creating named holiday fields (Christmas, Easter, etc.), create **generic numbered slots**. Admins can use any slot for any holiday without needing new fields. For the purpose of this example we have created 5 Holiday slots (**20 Fields)**. You may need to create more depending on how many holidays you observe.

**Full list of API names to create:**

| Slot | Name | Start | End | Message |
| --- | --- | --- | --- | --- |
| 1 | Holiday_1_Name | Holiday_1_Start | Holiday_1_End | Holiday_1_Message |
| 2 | Holiday_2_Name | Holiday_2_Start | Holiday_2_End | Holiday_2_Message |
| 3 | Holiday_3_Name | Holiday_3_Start | Holiday_3_End | Holiday_3_Message |
| 4 | Holiday_4_Name | Holiday_4_Start | Holiday_4_End | Holiday_4_Message |
| 5 | Holiday_5_Name | Holiday_5_Start | Holiday_5_End | Holiday_5_Message |

**For each slot (1–5), create these 4 fields:**

**Holiday X Name** (Replace X with the Slot Number)

| Setting | Value |
| --- | --- |
| Field Type | Text |
| Field Label | Holiday X Name |
| API Name | Holiday_X_Name |
| Length | 80 |
| Required | ☐ |
| Description | Name/label for this holiday slot. For admin reference only — not used in routing. |
| Help Text | Enter a name so you know what this holiday is. E.g. "Christmas 2026" |

**Holiday X Start**

| Setting | Value |
| --- | --- |
| Field Type | Date/Time |
| Field Label | Holiday X Start |
| API Name | Holiday_X_Start |
| Required | ☐ |
| Description | The date and time that this holiday closure begins. |
| Help Text | Enter when this line should close for this holiday. E.g. 24/12/2025 17:30 |

**Holiday X End**

| Setting | Value |
| --- | --- |
| Field Type | Date/Time |
| Field Label | Holiday X End |
| API Name | Holiday_X_End |
| Required | ☐ |
| Description | The date and time that this holiday closure ends. |
| Help Text | Enter when this line should reopen after this holiday. E.g. 02/01/2026 09:00 |

**Holiday X Message**

| Setting | Value |
| --- | --- |
| Field Type | Text |
| Field Label | Holiday X Message |
| API Name | Holiday_X_Message |
| Length | 255 |
| Required | ☐ |
| Description | The TTS message callers hear when calling during this holiday closure. |
| Help Text | Enter the message callers will hear during this holiday. |

#### 4.42 — Holiday Active

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Checkbox |
| Field Label | Holiday Active |
| API Name | Holiday_Active |
| Description | Returns true if the current date/time falls within ANY of the holiday closure windows. |

Formula:

```plaintext
OR(
  AND(NOT(ISBLANK(Holiday_1_Start__c)), NOW() >= Holiday_1_Start__c, NOW() <= Holiday_1_End__c),
  AND(NOT(ISBLANK(Holiday_2_Start__c)), NOW() >= Holiday_2_Start__c, NOW() <= Holiday_2_End__c),
  AND(NOT(ISBLANK(Holiday_3_Start__c)), NOW() >= Holiday_3_Start__c, NOW() <= Holiday_3_End__c),
  AND(NOT(ISBLANK(Holiday_4_Start__c)), NOW() >= Holiday_4_Start__c, NOW() <= Holiday_4_End__c),
  AND(NOT(ISBLANK(Holiday_5_Start__c)), NOW() >= Holiday_5_Start__c, NOW() <= Holiday_5_End__c)
)
```

#### 4.43 — Holiday Message

| Setting | Value |
| --- | --- |
| Field Type | Formula |
| Return Type | Text |
| Field Label | Holiday Message |
| API Name | Holiday_Message |
| Description | Returns the TTS message for whichever holiday is currently active. Checks slots in order (1 first). Returns blank if no holiday is active. |

Formula:

```plaintext
IF(AND(NOT(ISBLANK(Holiday_1_Start__c)), NOW() >= Holiday_1_Start__c, NOW() <= Holiday_1_End__c), Holiday_1_Message__c,
IF(AND(NOT(ISBLANK(Holiday_2_Start__c)), NOW() >= Holiday_2_Start__c, NOW() <= Holiday_2_End__c), Holiday_2_Message__c,
IF(AND(NOT(ISBLANK(Holiday_3_Start__c)), NOW() >= Holiday_3_Start__c, NOW() <= Holiday_3_End__c), Holiday_3_Message__c,
IF(AND(NOT(ISBLANK(Holiday_4_Start__c)), NOW() >= Holiday_4_Start__c, NOW() <= Holiday_4_End__c), Holiday_4_Message__c,
IF(AND(NOT(ISBLANK(Holiday_5_Start__c)), NOW() >= Holiday_5_Start__c, NOW() <= Holiday_5_End__c), Holiday_5_Message__c,
"")))))
```

#### 4.44 — Force Closed

| Setting | Value |
| --- | --- |
| Field Type | Checkbox |
| Field Label | Force Closed |
| API Name | Force_Closed |
| Default Value | Unchecked |
| Description | When checked, forces this line closed regardless of business hours. Use for emergencies or unplanned closures. |
| Help Text | Tick this box to immediately close this line. Callers will hear the Force Closed Message. |

#### 4.45 — Force Closed Message

| Setting | Value |
| --- | --- |
| Field Type | Text |
| Field Label | Force Closed Message |
| API Name | Force_Closed_Message |
| Length | 255 |
| Required | ☐ |
| Description | The TTS message callers hear when the line has been manually force-closed. |
| Help Text | E.g. "We are currently experiencing unexpected issues. Please try again later." |

### **Step 5: Configure the Page Layout**

1. Navigate to **Setup → Object Manager → Call Control → Page Layouts**
2. Click on the default layout
3. Organise fields into sections:

**Section 1 — Settings** *(single column)*

- Routing Policy Name
- UTC Offset
- DST Rule

**Section 2 — Opening Hours** *(2-column)*

| Left Column | Right Column |
| --- | --- |
| Monday Open | Monday Closed |
| Tuesday Open | Tuesday Closed |
| Wednesday Open | Wednesday Closed |
| Thursday Open | Thursday Closed |
| Friday Open | Friday Closed |
| Saturday Open | Saturday Closed |
| Sunday Open | Sunday Closed |

**Section 3 — Status** *(single column, all read-only)*

- DST Active
- Current Time
- Open Today
- Closed Today
- Currently Open

**Section 4 — Holidays** *(2-column)*

| Left Column | Right Column |
| --- | --- |
| Holiday 1 Name | Holiday 1 Message |
| Holiday 1 Start | Holiday 1 End |
| Holiday 2 Name | Holiday 2 Message |
| Holiday 2 Start | Holiday 2 End |
| Holiday 3 Name | Holiday 3 Message |
| Holiday 3 Start | Holiday 3 End |
| Holiday 4 Name | Holiday 4 Message |
| Holiday 4 Start | Holiday 4 End |
| Holiday 5 Name | Holiday 5 Message |
| Holiday 5 Start | Holiday 5 End |
| Holiday Active (read-only) | Holiday Message (read-only) |

**Section 5 — Overrides** *(single column)*

- Force Closed
- Force Closed Message

1. Click **Save**

### **Step 6: Create Your Records**

Create a record for each **unique schedule** you need. If multiple routing policies share the same opening hours, timezone, and holidays, they can all point to the same record — no need to duplicate.

**Example:** If your UK Sales, UK Support, and UK Billing policies all follow the same hours and holidays, create one record called **UK Standard Hours** and point all three routing policies at the record using the same query. Update hours or holidays once, and it applies everywhere.

For policies with different schedules (different timezone, different hours, different holidays), create a separate record.

#### Filling in Opening Hours

- Enter all times in local time — the formulas handle timezone conversion automatically
- If the line is closed on a particular day (e.g., weekends), leave both the Open and Closed fields blank for that day. A blank day will always evaluate as closed.
- If the line has different hours on different days (e.g., closes early on Fridays), just enter the different times for that day
- Times use 24-hour format: 09:00, 17:30, 22:00, etc.

#### Filling in Holiday Slots

- Use any available slot for any holiday — the slot number doesn't matter, they're checked in order
- Once a holiday has passed, you can clear the slot and reuse it for the next one, or leave old holidays in place (they won't trigger once the end date has passed)
- Leave all 4 fields blank for unused slots — they'll be ignored by the formula

#### Writing Messages (TTS)

The text you enter in Holiday Message and Force Closed Message fields is read aloud to callers by the Text-to-Speech (TTS) engine. Keep the following in mind:

- **Language**: The message must be written in the language that matches the TTS voice configured in your routing policy. If your policy uses an English voice, write in English. If it uses a French voice, write in French.

**Example record:**

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(409).png)

  

## Part 2: Building the Routing Policy

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(410).png)

### Step 7: Add the Query Object App

In your routing policy, inside an [Action Container](/v1/docs/action-container) (placed after Inbound Numbers):

1. Add a [Query Object app](/v1/docs/query-object-app)
2. Configure:

- Record Type = Call Control

- Filter Results (Routing Policy Name) = (Testing Policy) (Replace “Testing Policy” with the name of your Call Control record you created)

- Return Fields (Currently Open), (Holiday Active), (Holiday Message), (Force Closed), (Force Closed Message)

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(411).png)

### Macro Reference

When the Query Object App retrieves a record, all returned fields are stored as macros using this format:

$(SForce_ResultSetName.FieldAPIName)

With the Result Set (Query Component Name) named CallControl:

| Macro | Returns |
| --- | --- |
| $(SForce_CallControl.Currently_Open__c) | true or false |
| $(SForce_CallControl.Holiday_Active__c) | true or false |
| $(SForce_CallControl.Holiday_Message__c) | The active holiday's TTS message text |
| $(SForce_CallControl.Force_Closed__c) | true or false |
| $(SForce_CallControl.Force_Closed_Message__c) | The force-closed TTS message text |

### 

### Step 8: Add Rules

Add a new Action Container, after the Query Object and connect all nodes:

1. Add 3 Rule apps
2. Order matters — Force Closed → Holiday → Out of Hours → Open. Most restrictive first.
3. Configure:

| Rule | Force Closed |
| --- | --- |
| Rule Type | Evaluate |
| Property | $(SForce_CallControl.Force_Closed__c) |
| Operator | Equals |
| Value | true |

| Rule | Holiday Closure |
| --- | --- |
| Rule Type | Evaluate |
| Property | $(SForce_CallControl.Holiday_Active__c) |
| Operator | Equals |
| Value | true |

| Rule | Out of Hours |
| --- | --- |
| Rule Type | Evaluate |
| Property | $(SForce_CallControl.Currently_Open__c) |
| Operator | Equals |
| Value | false |

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(412).png)

### Step 9: Setting up closure messages in the TTS Speak App

After each rule rule:

1. Add a speak app
2. Configure:

Each speak component can have its respective Macro added and voice set.

Force Close Message - $(SForce_CallControl.Force_Closed_Message__c)

Holiday Message - $(SForce_CallControl.Holiday_Message__c)

Out of Hours - This will be a static TTS message as it does not need to change frequently. Optionally you could add another field under the call control object to capture this input if desired.

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(415).png)

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(413).png)

### Step 10: Open Hours Flow

If none of the above rules trigger, the call falls through to the next app below — this is your open/in-hours flow. Connect to your normal routing (Hunt Group, Call Queue, Connect a Call, etc.).

![](https://cdn.document360.io/c81c490c-daaa-4ebd-a3c3-1a2dee8b7617/Images/Documentation/image(416).png)

## Key Points

- **Rules trigger on match** — if the condition is met, the call routes via the middle connector. If not, it passes to the next app below.
- **Order matters** — Force Closed → Holiday → Out of Hours → Open. Most restrictive first.
- **One record per schedule** — each has its own timezone, hours, and holidays.
- **Admins enter local times** — formulas handle UTC conversion automatically.
- **One rule for all holidays** — generic slots mean you never touch the policy to add a new holiday.
- **No policy changes needed** — admins manage everything from the Salesforce record.

---

## Testing

1. Set a test record's hours to a window you can test within
2. Call the number assigned to that policy
3. Verify the call routes correctly for open/closed
4. Toggle Force Closed and call again — confirm the override message plays
5. Set a holiday slot window that includes now — confirm the holiday message plays
6. Check the formula fields on the record to verify Currently Open, Current Time, DST Active, and Holiday Active are calculating correctly

## Timezone Reference

| Timezone | UTC Offset | DST Rule |
| --- | --- | --- |
| US Eastern | -5 | US |
| US Central | -6 | US |
| US Mountain | -7 | US |
| US Pacific | -8 | US |
| UK | 0 | EU |
| Central Europe | +1 | EU |
| Eastern Europe | +2 | EU |
| India | +5.5 | None |
| Singapore / HK | +8 | None |
| Japan | +9 | None |
| Australia (Sydney) | +10 | AU* |
| New Zealand | +12 | NZ* |

**For AU/NZ timezones, add additional IF branches to the DST_Active__c formula with the appropriate transition dates for those regions.*