> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/campaigns/campaign-smart-functions.md).

# Campaign smart functions

Reading contact metadata and storing the call result from the conversation flow.

Two smart functions connect the conversation flow with the campaign. Add them in a **Function node** (or the Start node) via **Smart functions** > **Add smart function**, and store their output in a variable.

| Smart function                                                  | Use it to                                                                   |
| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Get campaign call metadata** (`get_campaign_call_metadata`)   | Load the contact's data (metadata) at the beginning of the call.            |
| **Update campaign call result** (`update_campaign_call_result`) | Save the result of the call and decide whether the contact is called again. |

Both functions work only in conversations started by a campaign (or in a call-back from a campaign contact, see below).

## get\_campaign\_call\_metadata

Returns the campaign record of the contact, including all columns from the uploaded file.

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FLStMsIkpA4cJyRw3wqUu%2Fimage.png?alt=media&amp;token=16d8ae16-f274-4098-bc7b-25eaf313f75a" alt=""><figcaption></figcaption></figure>

| Argument                                      | Required | Description                                                                                    |
| --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| **Phone number** (`phone_number`)             | yes      | The contact's phone number. On an outbound call it is available in the `PhoneNumber` variable. |
| **Number of days for user callback** (`days`) | no       | Default `2`. See *Call-backs* below.                                                           |

**Output** - stored e.g. in the variable `campaign_call`:

{% code title="campaign\_call" %}

```json
{
  "metadata": {
    "phone_number": "+420601234567",
    "status": "Locked",
    "attempt": 1,
    "campaign_status": "RUNNING",
    "next_call_time": null,
    "metadata": {
      "first_name": "Jana",
      "contract_id": "C-1001",
      "amount_due": "1200"
    }
  },
  "status_callback_url": "https://..."
}
```

{% endcode %}

The uploaded columns are under `metadata` > `metadata`. Read them into separate variables, e.g.:

* New variable name: **`first_name`**\
  New variable value: `campaign_call["metadata"]["metadata"]["first_name"]`

and use them in messages: *"Good morning {first\_name}, I am calling about contract {contract\_id}."*

Other useful fields: `attempt` (which attempt this is - e.g. a different greeting on a repeated call) and `status` (result of the previous attempt).

{% hint style="info" %}
If the data cannot be loaded, the function returns an empty object `{}`. Make sure the flow continues sensibly in that case (e.g. a generic greeting without the name).
{% endhint %}

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FvDDF6uUODBcOropFEI3h%2Fimage.png?alt=media&amp;token=61075590-45eb-4b55-a3da-881194267304" alt=""><figcaption></figcaption></figure>

### Call-backs

When a contact misses the call and **calls back** to the voicebot number, the inbound conversation has no campaign link. The function then searches the caller's conversations from the last **`days`** days (within the same organisation) and, if it finds the campaign call, returns its data. The flow can then finish the original task and save the result with `update_campaign_call_result` - a successful result also marks the contact as *Processed*.

## update\_campaign\_call\_result

Saves the result of the call to the campaign.

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2F3SrT0jAB02qgK42vq36k%2Fimage.png?alt=media&amp;token=6b70b2c1-8ec9-4c6d-962b-7eb904815cb4" alt=""><figcaption></figcaption></figure>

| Argument                                            | Required | Description                                                                                                                                                  |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Status** (`status`)                               | yes      | Final status of the call, e.g. `interested`, `not-interested`, `callback-requested`, `busy`.                                                                 |
| **Call metadata** (`metaData`)                      | no       | Dictionary with data to store with the call, e.g. `{"agreed": "yes", "preferred_date": "2026-10-20"}`. The values also become variables in the conversation. |
| **Custom retry delay (min)** (`custom_retry_delay`) | no       | Minutes until the next attempt for this contact - overrides the campaign setting for this one retry. Used only when the status is unsuccessful.              |

**What the status does**

* Status listed in the campaign's *Statuses*, or `busy` / `no-answer` / `disconnected` → **unsuccessful**: the contact is called again (or moved to *Failed* if no attempts are left).
* Any other status → **success**: the contact is moved to *Processed*.

**Output** - a text message:

| Output                                                                | Meaning                                                                    |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `200 - Successfully updated`                                          | The result was saved.                                                      |
| `501 - Metadata was updated but status_callback_url was not provided` | The conversation is not a campaign call - only the variables were updated. |
| `500 - Error while updating call ...`                                 | The result could not be saved.                                             |

{% hint style="warning" %}
**Metadata is replaced, not merged.** When you send `metaData`, it replaces the contact's original metadata in the campaign results. If you want to keep the uploaded columns in the export, include them in `metaData` as well. If you send no `metaData`, the original metadata is kept.
{% endhint %}

{% hint style="info" %}
Call `update_campaign_call_result` on **every** path where a connected call ends (success, refusal, transfer to an operator...). If no result arrives, the platform checks the conversation's `call_result` variable after 10 minutes and otherwise marks the contact as failed after 60 minutes.
{% endhint %}

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FTiDg3Oy9OIJRlF5xK07y%2Fimage.png?alt=media&amp;token=aeb2f796-4b6b-4d64-8261-f0c94b3721f9" alt=""><figcaption></figcaption></figure>
