Public API
Build public Talkturo calling experiences with AI employee demos, outbound calls, embedded forms, and browser-ready call tokens.
curl -X POST "https://app.talkturo.com/api/public/ai-employee/create" \
-H "Content-Type: application/json" \
-H "Origin: https://www.acme-demo-site.com" \
-d '{
"website_url": "https://www.acmeexample.com",
"business_description": "Acme Example provides managed IT support for growing professional services firms.",
"company_name": "Acme Example",
"language": "en",
"use_case": "lead_qualification",
"first_name": "Jordan",
"last_name": "Lee",
"turnstile_token": "turnstile_example_token_7f3a91",
"fbc": "fb.1.1712345678901.AbCdEfGh",
"fbp": "fb.1.1712345678901.123456789",
"fbclid": "IwAR_example_click_id"
}'
const response = await fetch("https://app.talkturo.com/api/public/ai-employee/create", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Origin": "https://www.acme-demo-site.com"
},
body: JSON.stringify({
website_url: "https://www.acmeexample.com",
business_description: "Acme Example provides managed IT support for growing professional services firms.",
company_name: "Acme Example",
language: "en",
use_case: "lead_qualification",
first_name: "Jordan",
last_name: "Lee",
turnstile_token: "turnstile_example_token_7f3a91",
fbc: "fb.1.1712345678901.AbCdEfGh",
fbp: "fb.1.1712345678901.123456789",
fbclid: "IwAR_example_click_id"
})
});
const data = await response.json();
console.log(data);
{
"draft_token": "draft_example_8f4c2a91b7d6",
"assistant_name": "Jordan",
"company_name": "Acme Example",
"business_summary": "Managed IT support for growing professional services firms.",
"first_message": "Hi, I am Jordan from Acme Example. How can I help?",
"source": "website",
"language": "en",
"voice_name": "alloy"
}
{
"error": "Turnstile verification failed"
}
curl -X POST "https://app.talkturo.com/api/public/ai-employee/upload" \
-H "Origin: https://www.acme-demo-site.com" \
-F "draft_token=draft_example_8f4c2a91b7d6" \
-F "file=@acme-services.txt"
const documentFile = new File(
[
"Acme Example provides managed IT support, cloud migration, and security monitoring for professional services firms."
],
"acme-services.txt",
{ type: "text/plain" }
);
const formData = new FormData();
formData.append("draft_token", "draft_example_8f4c2a91b7d6");
formData.append("file", documentFile);
const response = await fetch("https://app.talkturo.com/api/public/ai-employee/upload", {
method: "POST",
headers: {
"Origin": "https://www.acme-demo-site.com"
},
body: formData
});
const data = await response.json();
console.log(data);
{
"success": true,
"used_in_demo": true
}
{
"error": "Unsupported file type"
}
curl -X POST "https://app.talkturo.com/api/public/ai-employee/call-token" \
-H "Content-Type: application/json" \
-H "Origin: https://www.acme-demo-site.com" \
-d '{
"draft_token": "draft_example_8f4c2a91b7d6"
}'
const response = await fetch("https://app.talkturo.com/api/public/ai-employee/call-token", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Origin": "https://www.acme-demo-site.com"
},
body: JSON.stringify({
draft_token: "draft_example_8f4c2a91b7d6"
})
});
const data = await response.json();
console.log(data);
{
"token": "call_token_example_5c91",
"wsUrl": "wss://voice.talkturo.com",
"roomName": "public-demo-room-73e9",
"identity": "visitor-73e9",
"agentName": "Jordan",
"max_duration_seconds": 180,
"calls_remaining": 2
}
{
"error": "Invalid draft token"
}
curl "https://app.talkturo.com/api/public/ai-employee/use-cases" \
-H "Origin: https://www.acme-demo-site.com"
const response = await fetch("https://app.talkturo.com/api/public/ai-employee/use-cases", {
headers: {
"Origin": "https://www.acme-demo-site.com"
}
});
const data = await response.json();
console.log(data);
{
"use_cases": [
{
"key": "lead_qualification",
"label_en": "Lead qualification",
"label_de": "Lead-Qualifizierung",
"language": "en"
}
]
}
curl "https://app.talkturo.com/api/public/demo-assistants" \
-H "Origin: https://www.acme-demo-site.com"
const response = await fetch("https://app.talkturo.com/api/public/demo-assistants", {
headers: {
"Origin": "https://www.acme-demo-site.com"
}
});
const data = await response.json();
console.log(data);
{
"assistants": [
{
"id": "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
"name": "Maya",
"description": "Answers questions about customer onboarding.",
"display_order": 1,
"icon": "headset",
"max_call_duration_seconds": 120,
"outbound_enabled": true
}
]
}
curl -X POST "https://app.talkturo.com/api/public/test-call/token" \
-H "Content-Type: application/json" \
-H "Origin: https://www.acme-demo-site.com" \
-d '{
"assistant_id": "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
"turnstile_token": "turnstile_example_token_9b21d4",
"visitor_name": "Jordan Lee"
}'
const response = await fetch("https://app.talkturo.com/api/public/test-call/token", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Origin": "https://www.acme-demo-site.com"
},
body: JSON.stringify({
assistant_id: "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
turnstile_token: "turnstile_example_token_9b21d4",
visitor_name: "Jordan Lee"
})
});
const data = await response.json();
console.log(data);
{
"token": "call_token_example_7a31",
"wsUrl": "wss://voice.talkturo.com",
"roomName": "public-test-room-91bd",
"identity": "visitor-91bd",
"agentName": "Maya",
"max_duration_seconds": 120
}
{
"error": "Turnstile verification failed"
}
curl -X POST "https://app.talkturo.com/api/public/test-call/outbound" \
-H "Content-Type: application/json" \
-H "Origin: https://www.acme-demo-site.com" \
-d '{
"assistant_id": "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
"to_number": "+14155550184",
"turnstile_token": "turnstile_example_token_2c84f1",
"consent_given": true,
"visitor_name": "Jordan Lee",
"visitor_email": "jordan.lee@acmeexample.com"
}'
const response = await fetch("https://app.talkturo.com/api/public/test-call/outbound", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Origin": "https://www.acme-demo-site.com"
},
body: JSON.stringify({
assistant_id: "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
to_number: "+14155550184",
turnstile_token: "turnstile_example_token_2c84f1",
consent_given: true,
visitor_name: "Jordan Lee",
visitor_email: "jordan.lee@acmeexample.com"
})
});
const data = await response.json();
console.log(data);
{
"success": true,
"roomName": "outbound-demo-room-4e82",
"sipCallId": "CA8f2d9c1e4b7a6f3d0e",
"max_duration_seconds": 120,
"to_number": "+14155550184"
}
{
"error": "Destination country is not allowed"
}
curl -X POST "https://app.talkturo.com/api/public/form-call/outbound" \
-H "Content-Type: application/json" \
-H "Origin: https://www.acme-demo-site.com" \
-d '{
"assistant_id": "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
"account_id": "b8e3d9c2-56a7-4f02-ab34-7d8e9c3f2a15",
"account_slug": "acme-example",
"company_id": "c9f4e0d3-67b8-4a13-bc45-8e9f0d4b3a26",
"to_number": "+14155550184",
"visitor_name": "Jordan Lee",
"consent_given": true
}'
const response = await fetch("https://app.talkturo.com/api/public/form-call/outbound", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Origin": "https://www.acme-demo-site.com"
},
body: JSON.stringify({
assistant_id: "a7d2c8b1-45f6-4e91-9a23-6c7d8b2e1f04",
account_id: "b8e3d9c2-56a7-4f02-ab34-7d8e9c3f2a15",
account_slug: "acme-example",
company_id: "c9f4e0d3-67b8-4a13-bc45-8e9f0d4b3a26",
to_number: "+14155550184",
visitor_name: "Jordan Lee",
consent_given: true
})
});
const data = await response.json();
console.log(data);
{
"success": true,
"roomName": "form-call-room-6f24",
"sipCallId": "CA9e3f0a2b5c8d7e4f1a",
"to_number": "+14155550184"
}
{
"error": "consent_given must be true"
}
Build public calling experiences
Use Talkturo's public endpoints to create AI employee drafts, upload business documents, start browser-based demo calls, and place consented outbound calls from websites and embedded forms.
All endpoints use https://app.talkturo.com and do not require a session, JWT, or API key. Talkturo validates the request Origin header with CORS rules. Some endpoints also require a Turnstile CAPTCHA token.
Every public endpoint requires a valid CORS origin. Requests from unapproved origins fail even when the request body and CAPTCHA token are valid. Endpoints that require CAPTCHA must receive a valid turnstile_token.
Endpoint summary
| Method | Path | Purpose | Authentication |
|---|---|---|---|
POST | /api/public/ai-employee/create | Create an AI employee draft from business details | Turnstile CAPTCHA |
POST | /api/public/ai-employee/upload | Add a reference document to an AI employee draft | draft_token |
POST | /api/public/ai-employee/call-token | Create a browser call token for an AI employee draft | draft_token |
GET | /api/public/ai-employee/use-cases | List available AI employee use cases | None |
GET | /api/public/demo-assistants | List assistants available for public demos | None |
POST | /api/public/test-call/token | Create a browser call token for a demo assistant | Turnstile CAPTCHA |
POST | /api/public/test-call/outbound | Start a consented outbound demo call | Turnstile CAPTCHA |
POST | /api/public/form-call/outbound | Start an outbound call from an embedded form | None |
The draft_token returned by the AI employee creation endpoint authorizes the upload and call-token endpoints for that draft. Treat it as a short-lived public demo credential and do not expose it in server logs.
AI employee creation
Create an AI employee draft
Create a draft AI employee from a website URL, business description, or both. The endpoint generates the draft identity and returns a draft_token for subsequent upload and browser-call requests.
The endpoint accepts unauthenticated requests, but requires a valid Turnstile token and applies per-IP and global rate limits:
- 10 requests per hour per IP
- 30 requests per day per IP
- 200 requests per day globally
Body parameters
Website URL used to derive business context. The field is conditionally required when business_description is not provided.
Description of the business and the information the AI employee should use. The field is conditionally required when website_url is not provided.
Company name shown in the generated draft.
Use case selected for the AI employee.
First name used for the generated AI employee.
Last name associated with the draft request.
Cloudflare Turnstile token for CAPTCHA verification.
Optional Facebook click identifier.
Optional Facebook browser identifier.
Optional Facebook click identifier from the landing-page URL.
Response fields
Token used to authorize uploads and call-token requests for this draft.
Name generated for the AI employee.
Company name used by the generated draft.
Generated summary of the business.
Opening message the AI employee uses when the call starts.
Source used to create the draft, such as website content or a supplied description.
Language selected for the draft.
Voice assigned to the AI employee.
Upload a reference document
Attach a business document to an existing AI employee draft. Use multipart/form-data with the draft_token and a supported file.
The endpoint accepts PDF, DOC, DOCX, TXT, and MD files up to 10 MB. It allows 20 requests per hour per IP.
Form fields
Token returned by the create endpoint.
Reference document in PDF, DOC, DOCX, TXT, or MD format. The maximum file size is 10 MB.
Response fields
Indicates whether the upload completed successfully.
Indicates whether the uploaded content is available in the demo. The value is true for TXT and MD files and false for PDF and Word files.
Create an AI employee call token
Create the browser call credentials for an AI employee draft. Use the returned token and room details with your browser calling client.
The endpoint allows 30 requests per hour and 100 requests per day per IP, with a global limit of 500 requests per day.
Body parameters
Token returned by the create endpoint.
Response fields
Short-lived token used to join the browser call.
WebSocket URL for the calling provider.
Room assigned to the call.
Visitor identity assigned to the call.
Name of the AI employee in the draft.
Maximum call duration. The AI employee demo limit is 180 seconds.
Number of calls remaining for the draft.
AI employee metadata
List AI employee use cases
Return the use cases available when creating an AI employee. This endpoint requires no authentication and is not rate limited.
Response fields
Available AI employee use cases.
Stable identifier to send as the use_case value when creating a draft.
English display label.
German display label.
Language associated with the use case.
Demo assistants
List demo assistants
Return the assistants available for public demo calls. This endpoint requires no authentication and allows 60 requests per minute per IP.
Response fields
Assistants configured for public demos.
Assistant UUID used in demo call and outbound call requests.
Assistant display name.
Description shown to visitors.
Display order for the assistant list.
Icon identifier for the assistant.
Maximum duration configured for the assistant.
Whether the assistant can place outbound calls.
Create a demo call token
Create browser call credentials for a public demo assistant. This endpoint requires a valid Turnstile token and allows 30 requests per hour and 100 requests per day per IP.
Body parameters
UUID of the demo assistant.
Cloudflare Turnstile token for CAPTCHA verification.
Name associated with the visitor's demo call.
Response fields
Short-lived token used to join the browser call.
WebSocket URL for the calling provider.
Room assigned to the call.
Visitor identity assigned to the call.
Demo assistant name.
Maximum demo call duration, which is 120 seconds.
Start a demo outbound call
Start a consented outbound call to a visitor's phone number. The number must use E.164 format. A country allowlist may restrict which destinations are permitted.
This endpoint requires Turnstile CAPTCHA and applies these limits:
- 10 requests per hour per IP
- 30 requests per day per IP
- 3 requests per phone number every 6 hours
Body parameters
UUID of the demo assistant.
Destination phone number in E.164 format.
Cloudflare Turnstile token for CAPTCHA verification.
Must be true before Talkturo places the outbound call.
Name associated with the visitor.
Email address associated with the visitor.
Response fields
Indicates whether the outbound call was started.
Room assigned to the outbound call.
Telephony provider call identifier.
Maximum outbound demo call duration, which is 120 seconds.
Normalized destination phone number.
Embedded form calls
Start an outbound form call
Start an outbound call from an embedded form without CAPTCHA. The form must provide the assistant, workspace context, destination number, and explicit consent.
The endpoint accepts E.164 phone numbers and applies these limits:
- 50 requests per hour per IP
- 200 requests per day per IP
- 50 requests per hour per phone number
Body parameters
UUID of the assistant that handles the call.
Workspace UUID associated with the assistant.
Workspace slug used to identify the account.
Company UUID included for compatibility. The endpoint ignores this field.
Destination phone number in E.164 format.
Name provided by the visitor.
Must be true before Talkturo places the outbound call.
Response fields
Indicates whether the outbound call was started.
Room assigned to the outbound call.
Telephony provider call identifier.
Normalized destination phone number.