Create TFU Live agent

Creates a TFU Live agent that calls and answers leads. TFU Live is Team Follow Up AI’s realtime voice agent. It is run by a Brain of instructions and workflows, and is separate from Agent Builder agents, which follow a script. AI can write it from business information, or it can start from a free starter draft or a ready-made Brain template. AI generation costs USD 0.50, paid from the agency’s existing wallet balance, only when the agent and campaign are created. It is charged once per agent. An agency on the new billing ledger, or exempt from payment, pays nothing. Clarification replies and starter drafts are free. Each new agent gets its own paused campaign and its own call schedule. To change the prompt after creation, use `PATCH /api/tfu-live-agents/{id}`. For a Brain template ({ id, brainTemplateId, values?, name? }), values are optional, and missing settings stay as setup items. Retry with the same request id after an uncertain response. Creation never switches a campaign on. Required scope: `agents:write`. Use mode=generate with business information as text for AI creation (USD 0.50 on successful creation, free clarification). Generation needs three facts, for inbound and outbound agents alike: who the business serves, the result it offers, and how it delivers that result. Take agentType from the main use the user states. If it is missing, ask whether the agent mainly takes inbound or outbound calls. Do not guess it from their website. Take voiceId from `GET /api/tfu-live-agents/voices`. Without name, the agent is called Tars. Without voiceId, it uses the River voice (voice id `cedar`). Use mode=template for a free starter draft, then edit it with `PATCH /api/tfu-live-agents/{id}`. mode=template is not a Brain template. Both modes return a creation request. Follow it with `GET /api/tfu-live-agents/creation/{requestId}`. When the build asks questions, send the request again with the same id and settings, and add the answers to information. Required API key scope: `agents:write`.

POST

api

tfu-live-agents

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/tfu-live-agents \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "front_desk",
  "brainTemplateId": "booking_one_calendar",
  "name": "Front desk",
  "values": {
    "calendar": "cal_consult01"
  }
}'

import requests

url = "https://api.teamfollowup.ai/api/tfu-live-agents"

payload = {
    "id": "front_desk",
    "brainTemplateId": "booking_one_calendar"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({id: 'front_desk', brainTemplateId: 'booking_one_calendar'})
};

fetch('https://api.teamfollowup.ai/api/tfu-live-agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/tfu-live-agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => 'front_desk',
    'brainTemplateId' => 'booking_one_calendar'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/tfu-live-agents"

	payload := strings.NewReader("{\n  \"id\": \"front_desk\",\n  \"brainTemplateId\": \"booking_one_calendar\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.teamfollowup.ai/api/tfu-live-agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"front_desk\",\n  \"brainTemplateId\": \"booking_one_calendar\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/tfu-live-agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"front_desk\",\n  \"brainTemplateId\": \"booking_one_calendar\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "campaign": {
      "id": "cmp_123",
      "profileId": "example_agent",
      "name": "Consultation desk",
      "isActive": false,
      "sms": true,
      "fromNumbers": []
    },
    "agent": {
      "id": "tfu_live:example_agent",
      "runtime": "tfu_live",
      "name": "Consultation desk",
      "brain": {
        "prompt": "Help people arrange a consultation. Confirm that their postal code is covered before offering an appointment.",
        "capabilities": [
          "outreach"
        ],
        "capabilityConfig": {
          "workflows": {
            "wf_area2k9x": {
              "id": "wf_area2k9x",
              "name": "Check service area",
              "description": "Use when the caller wants to know whether we serve their area.",
              "steps": [
                {
                  "id": "zip",
                  "type": "collect_information",
                  "config": {
                    "items": [
                      {
                        "id": "zip_code",
                        "label": "Zip code",
                        "question": "What is the zip code of the address?",
                        "type": "text",
                        "field": "contact.postalCode"
                      }
                    ]
                  }
                },
                {
                  "id": "coverage",
                  "type": "check_zip_code",
                  "config": {
                    "field": "contact.postalCode",
                    "codes": [
                      "10001"
                    ]
                  },
                  "outputs": {
                    "in_area": [
                      {
                        "id": "covered",
                        "type": "steer_agent",
                        "config": {
                          "guidance": "Offer a consultation."
                        }
                      }
                    ],
                    "out_of_area": [
                      {
                        "id": "outside",
                        "type": "steer_agent",
                        "config": {
                          "guidance": "Explain that this area is not covered."
                        }
                      }
                    ]
                  }
                }
              ]
            }
          }
        }
      },
      "voice": {
        "voiceId": "marin",
        "prompt": "Speak at a calm pace and pronounce addresses clearly."
      },
      "authoring": {
        "editable": true,
        "reasons": []
      },
      "orb": {
        "style": "default"
      },
      "ifVersion": "3f2b9c0d1e",
      "setup": {
        "status": "draft",
        "revision": 1
      }
    },
    "setupStarted": false
  }
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Query Parameters

locationId

string

required

The sub-account. It must belong to the agency, and be the credential’s own sub-account when the credential is limited to one.

Body

application/json

One of three shapes: { id, mode: generate, information, agentType?, name?, voiceId? } to have AI write the agent, { id, mode: template, agentType?, name?, voiceId? } for a free starter draft, or { id, brainTemplateId, values?, name? } for a Brain template.

Option 1
Option 2
Option 3

USD 0.50 per agent and campaign created, paid from the agency’s existing wallet balance. Clarification replies and failed builds are free.

string

required

A request id you choose and keep. Reuse it to read progress, to retry and to answer questions. The new agent’s own id comes back as agentId.

Pattern: ^[a-zA-Z0-9_-]{8,100}$

mode

any

required

generate: AI writes the agent from information. It costs USD 0.50, charged only once the agent and campaign are created.

information

string

required

The business information and the job the agent should do. Include website findings as text. This request never reads websites itself. On needs_information, send the extra facts with the same id. Facts already given are kept.

Required string length: 1 - 50000

name

string

The name the agent says on calls, not only a dashboard label. Use the name the user asked for exactly. Add a business name to it only when the user asked for that as part of the spoken name. Reuse a name already agreed for follow-up or batch builds with the same settings. Omit it only when no name was given. The agent is then called Tars.

Required string length: 1 - 100

voiceId

string

Optional. A voice id from GET /api/tfu-live-agents/voices. Defaults to cedar. Voice ids from GET /api/agent-builder/voices are for Agent Builder agents and are not accepted.

Required string length: 1 - 100

agentType

enum<string>

The main use, as the user states it or as an existing role they describe. Do not infer it from the business website or the type of business alone. If it is missing, generation returns needs_information before it builds or charges anything. Then ask the user which calls will make up most of the agent’s work.

Available options:

inbound_receptionist,

outbound_sales

Response

Successful TFU Live response. Setup acceptance is not verified readiness or campaign activation.

success

any

required

data

object

required

Show child attributes

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/tfu-live-agents \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "front_desk",
  "brainTemplateId": "booking_one_calendar",
  "name": "Front desk",
  "values": {
    "calendar": "cal_consult01"
  }
}'

import requests

url = "https://api.teamfollowup.ai/api/tfu-live-agents"

payload = {
    "id": "front_desk",
    "brainTemplateId": "booking_one_calendar"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({id: 'front_desk', brainTemplateId: 'booking_one_calendar'})
};

fetch('https://api.teamfollowup.ai/api/tfu-live-agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/tfu-live-agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => 'front_desk',
    'brainTemplateId' => 'booking_one_calendar'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/tfu-live-agents"

	payload := strings.NewReader("{\n  \"id\": \"front_desk\",\n  \"brainTemplateId\": \"booking_one_calendar\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.teamfollowup.ai/api/tfu-live-agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"front_desk\",\n  \"brainTemplateId\": \"booking_one_calendar\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/tfu-live-agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"front_desk\",\n  \"brainTemplateId\": \"booking_one_calendar\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "campaign": {
      "id": "cmp_123",
      "profileId": "example_agent",
      "name": "Consultation desk",
      "isActive": false,
      "sms": true,
      "fromNumbers": []
    },
    "agent": {
      "id": "tfu_live:example_agent",
      "runtime": "tfu_live",
      "name": "Consultation desk",
      "brain": {
        "prompt": "Help people arrange a consultation. Confirm that their postal code is covered before offering an appointment.",
        "capabilities": [
          "outreach"
        ],
        "capabilityConfig": {
          "workflows": {
            "wf_area2k9x": {
              "id": "wf_area2k9x",
              "name": "Check service area",
              "description": "Use when the caller wants to know whether we serve their area.",
              "steps": [
                {
                  "id": "zip",
                  "type": "collect_information",
                  "config": {
                    "items": [
                      {
                        "id": "zip_code",
                        "label": "Zip code",
                        "question": "What is the zip code of the address?",
                        "type": "text",
                        "field": "contact.postalCode"
                      }
                    ]
                  }
                },
                {
                  "id": "coverage",
                  "type": "check_zip_code",
                  "config": {
                    "field": "contact.postalCode",
                    "codes": [
                      "10001"
                    ]
                  },
                  "outputs": {
                    "in_area": [
                      {
                        "id": "covered",
                        "type": "steer_agent",
                        "config": {
                          "guidance": "Offer a consultation."
                        }
                      }
                    ],
                    "out_of_area": [
                      {
                        "id": "outside",
                        "type": "steer_agent",
                        "config": {
                          "guidance": "Explain that this area is not covered."
                        }
                      }
                    ]
                  }
                }
              ]
            }
          }
        }
      },
      "voice": {
        "voiceId": "marin",
        "prompt": "Speak at a calm pace and pronounce addresses clearly."
      },
      "authoring": {
        "editable": true,
        "reasons": []
      },
      "orb": {
        "style": "default"
      },
      "ifVersion": "3f2b9c0d1e",
      "setup": {
        "status": "draft",
        "revision": 1
      }
    },
    "setupStarted": false
  }
}

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Caller ID

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

Create TFU Live agent

Authorizations

Query Parameters

Body

Response