Create a Web Agent

curl --request POST \
  --url https://app.luly.ai/api/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "prompt": "<string>",
  "voice": "<string>",
  "analysis_schema": {},
  "metadata": {},
  "pathway_id": "<string>",
  "language": "<string>",
  "model": "<string>",
  "first_sentence": "<string>",
  "tools": [
    {}
  ],
  "dynamic_data": {},
  "interruption_threshold": 123,
  "keywords": [
    "<string>"
  ],
  "max_duration": {}
}
'

import requests

url = "https://app.luly.ai/api/v1/agents"

payload = {
    "prompt": "<string>",
    "voice": "<string>",
    "analysis_schema": {},
    "metadata": {},
    "pathway_id": "<string>",
    "language": "<string>",
    "model": "<string>",
    "first_sentence": "<string>",
    "tools": [{}],
    "dynamic_data": {},
    "interruption_threshold": 123,
    "keywords": ["<string>"],
    "max_duration": {}
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    voice: '<string>',
    analysis_schema: {},
    metadata: {},
    pathway_id: '<string>',
    language: '<string>',
    model: '<string>',
    first_sentence: '<string>',
    tools: [{}],
    dynamic_data: {},
    interruption_threshold: 123,
    keywords: ['<string>'],
    max_duration: {}
  })
};

fetch('https://app.luly.ai/api/v1/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://app.luly.ai/api/v1/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([
    'prompt' => '<string>',
    'voice' => '<string>',
    'analysis_schema' => [
        
    ],
    'metadata' => [
        
    ],
    'pathway_id' => '<string>',
    'language' => '<string>',
    'model' => '<string>',
    'first_sentence' => '<string>',
    'tools' => [
        [
                
        ]
    ],
    'dynamic_data' => [
        
    ],
    'interruption_threshold' => 123,
    'keywords' => [
        '<string>'
    ],
    'max_duration' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$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://app.luly.ai/api/v1/agents"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"analysis_schema\": {},\n  \"metadata\": {},\n  \"pathway_id\": \"<string>\",\n  \"language\": \"<string>\",\n  \"model\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"tools\": [\n    {}\n  ],\n  \"dynamic_data\": {},\n  \"interruption_threshold\": 123,\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"max_duration\": {}\n}")

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

	req.Header.Add("authorization", "<authorization>")
	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://app.luly.ai/api/v1/agents")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"analysis_schema\": {},\n  \"metadata\": {},\n  \"pathway_id\": \"<string>\",\n  \"language\": \"<string>\",\n  \"model\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"tools\": [\n    {}\n  ],\n  \"dynamic_data\": {},\n  \"interruption_threshold\": 123,\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"max_duration\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.luly.ai/api/v1/agents")

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

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"analysis_schema\": {},\n  \"metadata\": {},\n  \"pathway_id\": \"<string>\",\n  \"language\": \"<string>\",\n  \"model\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"tools\": [\n    {}\n  ],\n  \"dynamic_data\": {},\n  \"interruption_threshold\": 123,\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"max_duration\": {}\n}"

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

{
  "agent": {
        "agent_id": "2c565dc7-f41f-43db-a99f-e4c8ba9d7d18",
        "dynamic_data": null,
        "interruption_threshold": null,
        "first_sentence": null,
        "model": "enhanced",
        "voice_settings": null,
        "voice": "maya",
        "prompt": "...",
        "temperature": null,
        "max_duration": 30,
        "language": "ENG",
        "tools": null
  }
}

POST

agents

Create a Web Agent

curl --request POST \
  --url https://app.luly.ai/api/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "prompt": "<string>",
  "voice": "<string>",
  "analysis_schema": {},
  "metadata": {},
  "pathway_id": "<string>",
  "language": "<string>",
  "model": "<string>",
  "first_sentence": "<string>",
  "tools": [
    {}
  ],
  "dynamic_data": {},
  "interruption_threshold": 123,
  "keywords": [
    "<string>"
  ],
  "max_duration": {}
}
'

import requests

url = "https://app.luly.ai/api/v1/agents"

payload = {
    "prompt": "<string>",
    "voice": "<string>",
    "analysis_schema": {},
    "metadata": {},
    "pathway_id": "<string>",
    "language": "<string>",
    "model": "<string>",
    "first_sentence": "<string>",
    "tools": [{}],
    "dynamic_data": {},
    "interruption_threshold": 123,
    "keywords": ["<string>"],
    "max_duration": {}
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    voice: '<string>',
    analysis_schema: {},
    metadata: {},
    pathway_id: '<string>',
    language: '<string>',
    model: '<string>',
    first_sentence: '<string>',
    tools: [{}],
    dynamic_data: {},
    interruption_threshold: 123,
    keywords: ['<string>'],
    max_duration: {}
  })
};

fetch('https://app.luly.ai/api/v1/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://app.luly.ai/api/v1/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([
    'prompt' => '<string>',
    'voice' => '<string>',
    'analysis_schema' => [
        
    ],
    'metadata' => [
        
    ],
    'pathway_id' => '<string>',
    'language' => '<string>',
    'model' => '<string>',
    'first_sentence' => '<string>',
    'tools' => [
        [
                
        ]
    ],
    'dynamic_data' => [
        
    ],
    'interruption_threshold' => 123,
    'keywords' => [
        '<string>'
    ],
    'max_duration' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$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://app.luly.ai/api/v1/agents"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"analysis_schema\": {},\n  \"metadata\": {},\n  \"pathway_id\": \"<string>\",\n  \"language\": \"<string>\",\n  \"model\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"tools\": [\n    {}\n  ],\n  \"dynamic_data\": {},\n  \"interruption_threshold\": 123,\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"max_duration\": {}\n}")

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

	req.Header.Add("authorization", "<authorization>")
	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://app.luly.ai/api/v1/agents")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"analysis_schema\": {},\n  \"metadata\": {},\n  \"pathway_id\": \"<string>\",\n  \"language\": \"<string>\",\n  \"model\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"tools\": [\n    {}\n  ],\n  \"dynamic_data\": {},\n  \"interruption_threshold\": 123,\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"max_duration\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.luly.ai/api/v1/agents")

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

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"analysis_schema\": {},\n  \"metadata\": {},\n  \"pathway_id\": \"<string>\",\n  \"language\": \"<string>\",\n  \"model\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"tools\": [\n    {}\n  ],\n  \"dynamic_data\": {},\n  \"interruption_threshold\": 123,\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"max_duration\": {}\n}"

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

{
  "agent": {
        "agent_id": "2c565dc7-f41f-43db-a99f-e4c8ba9d7d18",
        "dynamic_data": null,
        "interruption_threshold": null,
        "first_sentence": null,
        "model": "enhanced",
        "voice_settings": null,
        "voice": "maya",
        "prompt": "...",
        "temperature": null,
        "max_duration": 30,
        "language": "ENG",
        "tools": null
  }
}

Headers

string

required

Your API key for authentication.

Body

string

required

Provide instructions, relevant information, and examples of the ideal conversation flow.

Best Practices

Out-of-the-Box Behaviors (Summarized):

Speech pattern: Direct, concise, casual
Spells out symbols, acronyms, abbreviations, percentages, etc. ($4,000,000 -> “four million dollars”)
Asks clarifying questions
Ends call when objective is complete or voicemail is detected

Prompting Tips:

Want to easily test out exactly how your agent will behave?
- Try out Agent Testing!
Aim for less than >2,000 characters where possible.
Simple, direct prompts are the most predictable and reliable.
Frame instructions positively:
- "Do this" rather than "Don't do this".
- Ex. “Keep the conversation casual” rather than “Don’t be too formal”.
- This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation.

string

Set your agent’s voice - all available voices can be found with the List Voices endpoint.

object

Define a JSON schema for how you want to get information about the call - information like email addresses, names, appointment times or any other type of custom data.In the webhook response or whenever you retrieve call data later, you’ll get the data you defined back under analysis.For example, if you wanted to retrieve this information from the call:

"analysis_schema": {
"email_address": "email",
"first_name": "string",
"last_name": "string",
"wants_to_book_appointment": "boolean",
"appointment_time": "YYYY-MM-DD HH:MM:SS"
}

You would get it filled out like this in your webhook once the call completes:

"analysis": {
"email_address": "johndoe@gmail.com",
"first_name": "John",
"last_name": "Doe",
"wants_to_book_appointment": true,
"appointment_time": "2024-01-01 12:00:00"
}

object

Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls.

string

Set the pathway that your agent will follow. This will override the prompt field, so there is no need to pass the ‘prompt’ field if you are setting a pathway.Warning: Setting a pathway will set the following fields to null / their default value - prompt, first_sentence, model, dynamic_data, tools, transfer_listSet to null or an empty string to clear the pathway.

string

default:"ENG"

Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings.Supported Languages and their codes:

English: ENG
Spanish: ESP
French: FRE
Polish: POL
German: GER
Italian: ITA
Brazilian Portuguese: PBR
Portuguese: POR

string

default:"enhanced"

Select a model to use for your call.Options: base, turbo and enhanced.In nearly all cases, enhanced is the best choice for now.

Model differences

There are three different ways to use luly:

model: base
- The original, follows scripts/procedures most effectively.
- Supports all features and capabilities.
- Best for Custom Tools
model: enhanced
- Much faster latency and very conversational, works best with objective-based prompts.
- Supports all features and capabilities.
model: turbo
- The absolute fastest latency possible, can be verbose at times
- Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools)
- Extremely realistic conversation capabilities

string

A phrase that your call will start with instead of a generating one on the fly. This works both with and without wait_for_greeting. Can be more than one sentence, but must be less than 200 characters.To remove, set to null or an empty string.

array

Interact with the real world through API calls.Detailed tutorial here: Custom Tools

object

Integrate data from external APIs into your agent’s knowledge.Set to null or an empty string to clear dynamic data settings.Detailed usage in the Send Call endpoint.

number

default:"100"

Adjusts how patient the AI is when waiting for the user to finish speaking.Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.Recommended range: 50-200

50: Extremely quick, back and forth conversation
100: Balanced to respond at a natural pace
200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.

Try to start with 100 and make small adjustments in increments of ~10 as needed for your use case.

string[]

default:"[]"

These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed.For example, if the word “Reece” is frequently transcribed as a homonym like “Reese” you could do this:

    {
        "keywords": ["Reece"]
    }

For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2.

    {
        "keywords": ["Reece:3"]
    }

integer (minutes)

default:"30"

The maximum duration that calls to your agent can last before being automatically terminated.Set to null to reset to default.

Response

string

Can be success or error.

string

A unique identifier for the call (present only if status is success).

{
  "agent": {
        "agent_id": "2c565dc7-f41f-43db-a99f-e4c8ba9d7d18",
        "dynamic_data": null,
        "interruption_threshold": null,
        "first_sentence": null,
        "model": "enhanced",
        "voice_settings": null,
        "voice": "maya",
        "prompt": "...",
        "temperature": null,
        "max_duration": 30,
        "language": "ENG",
        "tools": null
  }
}

Basic

Calls

Vector Stores

Conversational Pathways

Inbound Numbers

Outbound Numbers

Voices

Custom Tools

Web Agents

Custom Twilio Accounts

Campaigns

Prompts

Batches

SMS

Create a Web Agent

Headers

Body

Out-of-the-Box Behaviors (Summarized):

Prompting Tips:

Response

​Headers

​Body

​Out-of-the-Box Behaviors (Summarized):

​Prompting Tips:

​Response

Headers

Body

Out-of-the-Box Behaviors (Summarized):

Prompting Tips:

Response