Variables

Heedify Variables is a per-Entity JSON key/value store for customer context via the DB Object record, integrated with Microsoft Teams call flows to personalize routing — up to 100 root-level keys plus 100 customData primitive keys per record. Values are populated by workflows and consumed by call flow routing — for example, to route a VIP customer to a dedicated queue.

Two different things are called “variables” in Heedify — don’t confuse them:

  • Variables (this page) — a stored, per-Entity customer record (the DB Object). It is looked up by customer key on each call and read by Check Variable routing nodes. It persists between calls.
  • Workflow runtime variables — $VARIABLE$ tokens used inside a Workflow Action (URL, headers, body) plus any values a workflow’s Mapping captures from an API response. They live only for the duration of one call. See Workflows → Mapping.

Scoping

Every variable record belongs to one Entity and is identified by the combination of:

  • Entity — the Entity the record belongs to (selected when you create the record)
  • Customer key — a unique identifier you store at the root of the DB Object (typically a phone number, account ID or external CRM ID)

When a call comes in, the routing engine looks up the variable record for the current Entity + the caller’s identifier. Records from other Entities are never visible to a flow running under a different Entity, so the same identifier can map to different values across Entities without collision.

Creating a variable set

  1. Open Variables from the sidebar
  2. Click +Add
  3. Fill in the fields and save

Fields

Field Description
Display name Name shown in the list (required). The system prefixes the name with DB_ if you omit the prefix
Entity Entity the variables belong to (required)
DB Object JSON structure with the keys and values

DB Object rules

The DB object must respect these constraints:

  • Maximum 100 keys at the root of the DB object
  • Must contain a customData object
  • Maximum 100 keys inside customData
  • Values inside customData must be primitives only (string, number, boolean, null) — no nested objects or arrays
  • No duplicate keys

The 100-key limit is per level, not a global total. You can have up to 100 keys at the DB root AND up to 100 keys inside customData.

Example:

{
  "customerId": "+33612345678",
  "customData": {
    "loyalty_tier": "gold",
    "is_vip": true,
    "case_id": null
  }
}

In this example, customerId is the customer key that the routing engine matches against the incoming call. The customData block carries every primitive field a flow may want to read.

Using variables in flows

In a Call Flow, use Check Variable nodes to branch:

  • “If customData.is_vip is true, route to the VIP queue”
  • “If customData.loyalty_tier is gold, skip the IVR”

The flow reads the record matched by entity + customer key and evaluates the path you specify against the values found there.

Populating variables

Use a workflow triggered on Agent Connected or an early call event. The workflow’s Action calls your API and its Mapping captures fields from the response; those values are written to the variable record for the Entity + customer key, ready for the next call’s routing.

FAQ

Q: What can I store in Heedify Variables? A: Customer keys at the root of the DB Object (typically a phone number, account ID or external CRM ID) and primitives (string, number, boolean, null) inside the required customData object. No nested objects or arrays — Heedify enforces a single level under customData.

Q: How does a Heedify call flow look up the right record? A: The routing engine matches on the current Entity plus the caller’s identifier (the customer key at the root of the DB Object). Records from other Entities are never visible to a flow running under a different Entity.

Q: Can I store nested objects in Heedify Variables? A: Only one level. The DB root holds the customer key plus up to 100 keys, and the customData object holds up to 100 primitive keys. Heedify rejects nested objects or arrays inside customData.

Q: How are Heedify Variables populated? A: Use a workflow triggered on an early call event (typically Agent Connected). The webhook returns a JSON payload that Heedify merges into the variable record matched by Entity + customer key.

Works with: Microsoft Teams, Teams Phone, Workflows, Call Flows, webhook-based CRMs.