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

# Triggering a VoiceAgent Call from Attio

> Start a CloudTalk VoiceAgent call from an Attio workflow when something changes in your CRM

> [!NOTE]
>
> You can start a CloudTalk VoiceAgent call straight from an Attio workflow, so a VoiceAgent calls a person the moment something changes in your CRM. If the CloudTalk integration for Attio is connected, the call and its outcome are logged on the same person in Attio.

**User level:** Admin

***

## Before you start

You will need:

* VoiceAgents enabled on your CloudTalk account, and an **outbound** VoiceAgent (note its VoiceAgent ID). See [VoiceAgents for Outbound Calls](https://help.cloudtalk.io/en/articles/11401649-voiceagents-for-outbound-calls.md).
* [CloudTalk API credentials](https://help.cloudtalk.io/en/articles/15272380-how-to-access-and-generate-your-cloudtalk-api-keys.md) (API Key ID and API Secret)
* An Attio workspace where you can create workflows
* People in Attio with a phone number in international format, for example `+14155550123`

## Create the Authorization header

The CloudTalk API uses Basic authentication. Attio sends your credentials in an `Authorization` header, with a value in this format:

```text theme={"system"}
Basic <your API Key ID and API Secret, encoded in Base64>
```

To create it:

1. Join your API Key ID and API Secret with a colon: `API_KEY_ID:API_SECRET`.

2. Encode that text in Base64. For example, on a Mac or Linux computer, run this in the Terminal:

   ```bash theme={"system"}
   echo -n 'API_KEY_ID:API_SECRET' | base64
   ```

3. Put `Basic ` (with a space) in front of the result, for example `Basic QVBJX0tFWV9JRDpBUElfU0VDUkVU`.

> [!WARNING]
>
> Treat your API Secret like a password. Don't paste it into websites you don't trust, and don't share screenshots that show the Authorization value. For more details, see [Authentication](https://help.cloudtalk.io/guides/authentication.md).

## What you can trigger on

Any Attio workflow trigger works. These suit a VoiceAgent well:

| Trigger | What it's good for |
| - | - |
| **Record added to list** | A verification call. People land in a list (new sign-ups, imported leads, event registrations), and the VoiceAgent calls each one to confirm their name, role, email or anything else you need before a rep spends time on them. |
| **Attribute value changed** | A reaction. For example, a status moves to "Needs follow-up", a renewal date is within 30 days, or a phone number is finally filled in. |
| **Record created** | A fast first touch. The phone number may still be empty when the record is created, so keep the filter from Step 2. |
| **Manual run** | A call a rep starts from the person's record. It's also the easiest way to test the workflow. |
| **Recurring schedule** | A regular sweep, for example everyone who hasn't been contacted for 60 days. |

The steps below use **Record added to list**. You can swap the trigger in Step 1 for any of the others, and the rest of the steps stay the same.

## Option A: Build the workflow manually

### Step 1: Create the workflow and choose a trigger

1. In Attio, go to **Workflows > New workflow**.
2. Choose the **People** object and give the workflow a name.
3. Add the trigger **Record added to list** and pick your list.

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=4033ea3cd778801caae7deaac0b174da)

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image-1.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=6324c357c81ae630e30b4adfbb600ebf)

### Step 2: Filter out people you shouldn't call

Add a **Filter** block. At a minimum, continue only when **Phone numbers** is not empty.

To avoid calling the same person again and again, add a second condition. For example, use a date attribute called **Last VoiceAgent call** that must be empty, or older than a week. Create this attribute on People first. Step 4 fills it in.

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image-2.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=d7f4ed36fda5491c860ece058028b167)

### Step 3: Send the request to CloudTalk

Add a **Send HTTP request** block and set it up as follows:

| Field | Value |
| - | - |
| Method | `POST` |
| URL | `https://api.cloudtalk.io/v1/voice-agent/calls` |
| Header | `Content-Type`: `application/json` |
| Header | `Authorization`: the value you created in [Create the Authorization header](#h_authorization_header) |

![Screenshot 2026 10 27 At 08 47 41](https://mintcdn.com/cloudtalk/TvYlkdmIE4deeGSh/images/Screenshot-2026-10-27-at-08.47.41.png?fit=max\&auto=format\&n=TvYlkdmIE4deeGSh\&q=85\&s=0a6c47955fe3b78c2b99131be8f12df1)

In the body, enter:

```json theme={"system"}
{
  "call_number": "{{person phone number}}",
  "voice_agent_id": "YOUR_VOICE_AGENT_ID",
  "call_properties": {
    "system_prompt": {
      "variables": {
        "contact_name": "{{person name}}",
        "company_name": "{{person company name}}"
      }
    }
  }
}
```

![Screenshot 2026 10 27 At 08 48 29](https://mintcdn.com/cloudtalk/TvYlkdmIE4deeGSh/images/Screenshot-2026-10-27-at-08.48.29.png?fit=max\&auto=format\&n=TvYlkdmIE4deeGSh\&q=85\&s=8089815ef951e6ef0c6db436446d19bb)

Replace `YOUR_VOICE_AGENT_ID` with your VoiceAgent ID, and insert the values in double curly brackets with Attio's variable picker rather than typing them. Then check the body preview for two things:

* **`call_number` must be a single phone number, as text.** Phone numbers is a multi-value attribute in Attio, so select the first value. If the preview shows brackets or a list, CloudTalk rejects the request.
* **`company_name` must show the company's name,** not the company record itself.

> [!WARNING]
>
> `call_number` and `voice_agent_id` are the only required fields. Add `call_properties` only if your VoiceAgent's prompt uses variables, as described below. [Learn what else you can include](https://help.cloudtalk.io/en/articles/11401649-voiceagents-for-outbound-calls.md).

#### Pass details to the VoiceAgent

Anything you want the VoiceAgent to know about the person goes in `system_prompt.variables`. The VoiceAgent picks it up through matching placeholders in its own prompt, written as `#{{contact_name}}`. To insert one, type `#{{` in the VoiceAgent's **Goal** field.

The names must match exactly: `contact_name` in the body and `#{{contact_name}}` in the prompt. If they don't match, nothing tells you. The VoiceAgent just doesn't get the value.

If you want the VoiceAgent to **capture** what it hears, such as a corrected name, a role, an email or a callback time, set up extraction in the VoiceAgent's **Skills**. Without it, the call still happens and is logged, but the only result recorded is the outcome, and nothing is written to your Attio fields.

### Step 4: Handle the result

Add an **If** block on the HTTP block's **success** output:

* **Success:** update **Last VoiceAgent call** to the current date and time.
* **Not success:** create a note on the person with the status code and the response body, so failures show up in Attio and not only in the workflow's run log.

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image-3.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=2ca02d34604a7ce9a125839d32875035)

### Step 5: Publish and test

1. Publish the workflow.
2. Add **one** test person, with your own phone number, to the list. The call should arrive within a minute.
3. In the workflow's run history, check that the request returned a status between 200 and 299.
4. In CloudTalk, find the call under **Statistics > Calls**.

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image-4.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=af9cf87bac1bd94c1570e8a8b2dd6518)

If **Log VoiceAgent Calls** is turned on in your CloudTalk integration settings for Attio, the call is also logged on the person in Attio.

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image-5.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=1c8c186128c5311ebc441dddbe1a9bcd)

**You're all set!** 🚀 Your Attio workflow now starts a CloudTalk VoiceAgent call whenever a person meets your conditions.

## Option B: Build the workflow with Attio AI

Attio can generate the whole workflow from a description:

1. Create a new workflow on **People** and choose to build it with AI.
2. Paste the prompt below.
3. After the workflow is generated, replace the two placeholders with your real values. Don't paste your real credentials into the AI builder.

```text theme={"system"}
Create a workflow on the People object called "VoiceAgent verification call".

Trigger: when a person is added to the list "To verify".

Step 1, Filter: continue only if the person's Phone numbers attribute is not
empty AND the person's "Last VoiceAgent call" date attribute is empty.

Step 2, Send HTTP request:
  Method: POST
  URL: https://api.cloudtalk.io/v1/voice-agent/calls
  Headers:
    Content-Type: application/json
    Authorization: Basic REPLACE_WITH_ENCODED_CREDENTIALS
  Body (JSON). Use the trigger person's FIRST phone number as a plain string
  for call_number, not an array and not the whole multiselect list. Insert the
  person's name and their company's name as plain strings:
  {
    "call_number": "<person's first phone number>",
    "voice_agent_id": "REPLACE_WITH_VOICE_AGENT_ID",
    "call_properties": {
      "system_prompt": {
        "variables": {
          "contact_name": "<person's name>",
          "company_name": "<the person's company name>"
        }
      }
    }
  }

Step 3: if the request succeeded (status code 200-299), set the person's
"Last VoiceAgent call" attribute to the current date and time.

Step 4: if it did not succeed, create a note on the person titled
"CloudTalk VoiceAgent call failed" with the status code and response body.

Do not add any other steps.
```

![Image](https://mintcdn.com/cloudtalk/dOKBgsYK2Buf3-Vf/images/image-6.png?fit=max\&auto=format\&n=dOKBgsYK2Buf3-Vf\&q=85\&s=d565b0cb17732839a72d118a2fadf423)

Before you publish, open each generated block and check that:

1. **`call_number`** shows a single phone number in the body preview, not a list.
2. **`company_name`** shows the company's name, not the company record.
3. **The variable names** match the `#{{...}}` placeholders in your VoiceAgent's prompt.
4. **The `Authorization` header** holds your real encoded value, which you pasted in yourself.
5. **The trigger** is the one you asked for. Generated workflows sometimes use a broader one.

## Where the call appears in Attio

With the [CloudTalk integration for Attio](https://help.cloudtalk.io/en/articles/16815902-using-cloudtalk-with-attio.md) connected, the VoiceAgent call is logged on the person it called, just like a call made by one of your agents:

* **Notes mode:** a note on the person with the call details, plus a VoiceAgent section with the outcome and anything the VoiceAgent captured.
* **Your own call object:** a call record linked to the person. Map **Voice Agent Analysis** to a long text attribute to have the captured data written there. If you leave it unmapped, it goes into a note on the call record instead.

![Screenshot 2026 10 27 At 11 06 40](https://mintcdn.com/cloudtalk/TvYlkdmIE4deeGSh/images/Screenshot-2026-10-27-at-11.06.40.png?fit=max\&auto=format\&n=TvYlkdmIE4deeGSh\&q=85\&s=153c41cd727863966004e7ee45c4970b)

A call that ends without an analysis, for example when nobody answers or the call fails, is logged as an ordinary call.

Because the result is saved on the record, you can build a second workflow on top of it. For example, when a verification call comes back with a corrected email, you can move the person to another list, create a task for their owner, or notify the rep who owns the account.

## Troubleshooting

* **401 Unauthorized:** check that the `Authorization` header starts with `Basic ` and that the encoded value comes from your current API Key ID and API Secret.
* **400 Bad Request:** check that `call_number` is a single phone number in international format (for example, `+14155550123`), not a list.
* **The VoiceAgent doesn't use the person's name or company:** check that the variable names in the body match the `#{{...}}` placeholders in the VoiceAgent's prompt exactly.
* **No call at all:** check that the workflow is published and that the person meets all the filter conditions.

***

Need help or have a question? Reach out through our [Support portal](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884). We're here for you.


## Related topics

- [Triggering a VoiceAgent Call from Freshdesk](https://help.cloudtalk.io/en/articles/15457387-triggering-a-voiceagent-call-from-freshdesk.md)
- [Triggering a VoiceAgent Call from Zendesk](https://help.cloudtalk.io/en/articles/15934846-triggering-a-voiceagent-call-from-zendesk.md)
- [Triggering a VoiceAgent Call from Freshservice](https://help.cloudtalk.io/en/articles/15502021-triggering-a-voiceagent-call-from-freshservice.md)


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