Agents API
An agent answers the calls and messages of the channels it is connected to. What it says comes from its instructions, stored in versions: every change of instructions, language, identity or call opening creates a new draft, and deploying makes one version the one that answers. Its other settings change at once on the version that answers, with no deploy: automations, follow-up emails, human handoff, PBX extensions, knowledge and memory, how it books and the REST actions it calls.
POST /v1/agents → PATCH /v1/agents/:id → POST /v1/agents/:id/deployScopes agents:readagents:write29 endpointsShow
/v1/agentsList agents
Lists the workspace's agents, newest first, with their status: draft until a version is first deployed, then active. Archived (deleted) agents are listed only with status=archived, and POST /v1/agents/{id}/restore brings one back. deployed_version is null until a version is deployed.
agents:readQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
statusdraft | active | paused | archivedOnly agents in this status. Without it, every agent but the archived ones.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/agents?limit=10" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Agent",
"description": "Handles customer support inquiries",
"created_at": "2026-10-02T02:20:32.316004+00:00",
"status": "active",
"updated_at": "2026-10-02T03:56:00.896+00:00",
"deployed_version": {
"id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"version_label": "v1.1.0"
}
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}/v1/agentsCreate an agent
Creates an agent and its first version (v1.0.0, a draft) holding these instructions, and the language, identity, purpose and call opening sent. A draft takes no calls or messages: deploy it with POST /v1/agents/{id}/deploy.
agents:writeA version holds the name it introduces itself with, its instructions, language, purpose and call opening. The agent's automations, follow-up emails, transfers, knowledge and memory settings and Cal.com booking have endpoints of their own (/v1/agents/{id}/automations and the rest) and apply to its live version at once. Its voice is set on its channels. How it books (/v1/agents/{id}/booking-method, clinic-booking, business-booking) and the REST actions it calls (/v1/agents/{id}/rest-connector) have their own endpoints; its data connectors are set in the dashboard.
A new agent is not on any channel: put it on one with PUT /v1/channels/{id}/agent. Once it answers a channel, deploying a new version moves that channel to it.
Request body
namestring · 1–100 charactersrequiredDisplay name.
instructionsstring · 1–50,000 charactersrequiredThe system prompt: what the agent does and how it speaks.
descriptionstring · up to 500What the agent is for (shown in the dashboard).
languagees-MX | en-US | es-ES | en-GBThe language the agent speaks: its calls' speech recognition and the platform's own rules follow it. Without one the agent runs in English (en-US), so set it for every agent that speaks another language.
identity_namestring · up to 100The name the agent introduces itself with, e.g. Sofía. Default: the agent's name up to its first separator (|, —, –, ·, /, (, :, a comma or a spaced hyphen), so Sofía | Club Cañada — Reactivación calls itself Sofía.
purposestring · up to 500What the agent calls about, as it would finish "I'm calling about…", e.g. your appointment tomorrow.
greetingstring · up to 500The call opening: what the agent says first on a call. It may use the person's details, e.g. {{contact.first_name|there}} (a fallback after |).
say_greeting_exactlybooleantrue: calls start with the platform saying the opening word for word, the person's details filled in (an opening with a [slot] or a variable nothing fills is said by the AI, as written). false, where every agent starts: the opening is a brief the AI adapts.
Show 4 more fields
The agent's voice is set on its channels. Restaurant booking, data connectors, the REST connector's token or password and the workspace's Cal.com account are set in the dashboard. Add what it answers from with the Knowledge API.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/agents \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Agent",
"description": "Handles customer support inquiries",
"instructions": "You are the support agent for Acme. Answer in one or two sentences and offer a callback when you cannot solve the issue.",
"language": "en-US",
"identity_name": "Ava"
}'{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Agent",
"description": "Handles customer support inquiries",
"created_at": "2026-10-02T02:20:32.316004+00:00",
"version": {
"id": "c5c0810c-4614-4f0d-927d-62e587dad45e",
"version_label": "v1.0.0",
"deployment_status": "draft"
}
}
}/v1/agents/:idGet an agent
Returns an agent with its deployed version's instructions, language, identity, purpose and call opening, and every version's label and status.
agents:readPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Agent",
"description": "Handles customer support inquiries",
"created_at": "2026-10-02T02:20:32.316004+00:00",
"updated_at": "2026-10-02T03:56:00.896+00:00",
"deployed_version": {
"id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"version_label": "v1.1.0",
"instructions": "You are the support agent for Acme. Answer in one or two sentences.",
"language": "en-US",
"identity_name": "Ava",
"purpose": null,
"greeting": "Hi {{contact.first_name|there}}, this is Ava from Acme.",
"say_greeting_exactly": true
},
"versions": [
{
"id": "c5c0810c-4614-4f0d-927d-62e587dad45e",
"version_label": "v1.0.0",
"deployment_status": "draft",
"created_at": "2026-10-02T02:20:32.324764+00:00"
},
{
"id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"version_label": "v1.1.0",
"deployment_status": "deployed",
"created_at": "2026-10-02T02:21:20.112042+00:00"
}
]
}
}/v1/agents/:idUpdate an agent
Changes the name or description at once. New instructions, language, identity, purpose or call opening are saved together as one new draft version that copies the rest of the latest version's configuration; the deployed version keeps answering until you deploy the new one. The draft's label is the agent's highest version one minor step up, whichever way its versions were made: v3.11.1 → v3.12.0 (a label from before every version was vX.Y.Z counts as vX.Y.0: v3.10 → v3.11.0). The answer names that draft (version_id, version_label): deploy it with POST /v1/agents/{id}/deploy and that version_id.
agents:writeCan wait for approvalPath parameters
iduuidrequiredThe agent id.
Request body
namestring · 1–100 charactersNew display name.
descriptionstring · up to 500New description; an empty string clears it.
instructionsstring · 1–50,000 charactersNew system prompt, saved as a new draft version.
languagees-MX | en-US | es-ES | en-GBThe language the agent speaks: its calls' speech recognition and the platform's own rules follow it.
identity_namestring · up to 100The name the agent introduces itself with. An empty string goes back to its name up to the first separator.
purposestring · up to 500What the agent calls about, as it would finish "I'm calling about…", e.g. your appointment tomorrow. An empty string clears it.
greetingstring · up to 500The call opening: what the agent says first on a call. It may use the person's details, e.g. {{contact.first_name|there}} (a fallback after |). An empty string removes it.
say_greeting_exactlybooleantrue: calls start with the platform saying the opening word for word, the person's details filled in (an opening with a [slot] or a variable nothing fills is said by the AI, as written). false, where every agent starts: the opening is a brief the AI adapts.
Show 4 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).409conflictThe agent books in more than one way and nobody chose its booking method (details.reason booking_method_conflict): choose it in the agent's Actions tab first.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Handles support and sales",
"instructions": "You are the front desk for Acme. Answer in one or two sentences."
}'version_id, version_label) when it made one.{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Agent",
"description": "Handles support and sales",
"created_at": "2026-10-02T02:20:32.316004+00:00",
"updated_at": "2026-10-02T03:56:00.896+00:00",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"version_label": "v1.2.0"
}
}/v1/agents/:idDelete an agent
Archives the agent and takes it off every channel it was on. Those channels stop answering with it right away, so connect another agent first. An archived agent can't be fetched or changed; GET /v1/agents?status=archived lists it and POST /v1/agents/{id}/restore brings it back.
agents:writeWaits for approvalPath parameters
iduuidrequiredThe agent id.
Unless its key was set not to wait, nothing is removed yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X DELETE https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"deleted": true
}
}/v1/agents/:id/deployDeploy an agent version
Makes a version the one that answers. Without version_id the most recently created version is deployed; after PATCH /v1/agents/{id}, pass the version_id it answered, because on an agent whose live version a campaign A/B test calls with, a setting saved afterwards is saved as a new version, which is then the newest. The previously deployed version becomes a draft, and the channels this agent is the only agent of switch to the new version (deployed_channels counts the agent's channels on it afterwards). Deploying a version that is already deployed changes nothing and answers already_deployed: true. The version goes live with its own instructions, language, identity and call opening, and with the agent's current automations, actions (follow-up emails, transfers, Cal.com) and knowledge and memory settings, which are saved in place on the live version: deploying never undoes them, as the dashboard's deploy never does.
agents:writeCan wait for approvalChanged in October 2026: a deploy through the API used to put a version live with the automations, actions and knowledge settings it was saved with, so it could undo the ones saved since. It now keeps the agent's current ones, as the dashboard's deploy does.
Path parameters
iduuidrequiredThe agent id.
Request body
version_iduuidThe version to deploy: the version_id PATCH /v1/agents/{id} answered (default: the newest version).
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).404not_foundversion_id is not a version of this agent, or the agent has no version.409conflictThe version is in a campaign A/B test (details.reason version_in_ab_test), so it keeps its own settings, and deploying it would undo the ones saved since. Promote a variant to end the test first (in the dashboard: the campaign's Settings → A/B test), or deploy a newer version. Nothing changed.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/deploy \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82"
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"version_label": "v1.1.0",
"deployment_status": "deployed",
"deployed_channels": 1,
"published_at": "2026-10-02T02:21:38.917Z"
}
}/v1/agents/:id/automationsGet an agent's automations
Returns what the agent does on its own: WhatsApp follow-ups after a customer goes quiet, appointment reminders (WhatsApp messages, a confirmation, a reminder call) and closing inactive conversations, each with the agent's channels it runs on, and what keeps going in a chat your team took over. agent_id, agent_name and version_id name the agent and the version the settings are on (null when it has none). follow_ups.enabled_at is when follow-ups were switched on (set by NuTalk): conversations quiet since before then are never followed up.
agents:readPath parameters
iduuidrequiredThe agent id.
Automations, follow-up emails, human handoff, PBX extensions, knowledge and memory, the booking method, clinic and business booking, Cal.com booking and the REST connector each have a GET and a PUT. A PUT changes only what you send, runs the dashboard's own rules as the member who created the key, and applies to the version that answers right away. Deploying another version keeps them.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/automations \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"follow_ups": {
"enabled": true,
"channel_ids": [
"9f19ef32-eaef-452c-bebc-14d9759cdb64"
],
"delays_minutes": [
240,
1440
],
"instructions": "Ask whether they still want the appointment.",
"quiet_hours_enabled": true,
"quiet_start_hour": 21,
"quiet_end_hour": 9,
"enabled_at": "2026-10-23T18:04:11.000Z",
"follow_up_held_chats": false
},
"appointment_reminders": {
"enabled": true,
"whatsapp_channel_ids": [
"9f19ef32-eaef-452c-bebc-14d9759cdb64"
],
"voice_channel_ids": [],
"offsets_minutes": [
1440,
120
],
"whatsapp_enabled": true,
"confirmation_enabled": true,
"voice_enabled": false,
"voice_offset_minutes": 240,
"quiet_hours_enabled": true,
"quiet_start_hour": 21,
"quiet_end_hour": 9,
"day_reminders_at_hour": false,
"day_reminder_hour": 9,
"late_booking_reminders": false,
"remind_held_chats": false
},
"auto_close": {
"enabled": false,
"channel_ids": [],
"after_minutes": 4320,
"archive_enabled": true,
"skip_human_takeover": true,
"skip_customer_waiting": false
},
"campaign_messages": {
"send_to_held_chats": false
}
}
}/v1/agents/:id/automationsChange an agent's automations
Changes the settings sent, section by section, over what is saved at that moment; the rest stay as they are. Every channel must be one of the agent's active channels (WhatsApp for follow-ups, auto-close and WhatsApp reminders; voice for reminder calls), and a section switched on needs at least one. Follow-ups, reminders and reminder calls then go out to customers on their own.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy, and deploying another version later keeps it. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
follow_upsobjectWhatsApp follow-ups after the customer goes quiet: only the settings to change.
follow_ups.enabledbooleanFollow up on its own.
follow_ups.channel_idsuuid[] · 0–50 itemsThe agent's active WhatsApp channels where it follows up (at least one while on).
follow_ups.delays_minutesinteger[] · 1–5 itemsMinutes of silence before each follow-up, one per follow-up (at most 5), measured from the conversation's last message.
follow_ups.instructionsstring · up to 1,000Guidance for the AI writing the follow-ups.
follow_ups.quiet_hours_enabledbooleanSend nothing during quiet hours.
follow_ups.quiet_start_hourinteger · 0–23Local hour quiet hours start.
follow_ups.quiet_end_hourinteger · 0–23Local hour quiet hours end.
follow_ups.follow_up_held_chatsbooleanFollow-ups still go out in a chat your team took over: the team, not the AI, answers there. Off by default: a take-over stops them. A person's own exception, set in the dashboard, wins.
appointment_remindersobjectAppointment reminders: only the settings to change.
appointment_reminders.enabledbooleanRemind people of their appointments.
appointment_reminders.whatsapp_enabledbooleanSend WhatsApp reminders.
appointment_reminders.whatsapp_channel_idsuuid[] · 0–50 itemsThe agent's active WhatsApp channels that send reminders.
appointment_reminders.offsets_minutesinteger[] · 1–3 itemsMinutes before the appointment for each WhatsApp reminder (at most 3).
appointment_reminders.confirmation_enabledbooleanAsk the person to confirm, and record when they do.
appointment_reminders.day_reminders_at_hourbooleanSend a reminder set in whole days (1 day, 2 days…) at day_reminder_hour of that day instead of at the appointment's hour.
appointment_reminders.day_reminder_hourinteger · 0–23Local hour day reminders go out at.
appointment_reminders.late_booking_remindersbooleanAn appointment booked after its day reminder's moment, for a later day, gets that reminder right away.
appointment_reminders.remind_held_chatsbooleanA WhatsApp reminder still goes out in a chat your team took over: the team, not the AI, answers there. Off by default: a take-over stops the reminder. A person's own exception, set in the dashboard, wins.
appointment_reminders.voice_enabledbooleanAlso place a reminder call.
appointment_reminders.voice_channel_idsuuid[] · 0–50 itemsThe agent's active voice channels that place reminder calls.
appointment_reminders.voice_offset_minutesinteger · 15–10,080Minutes before the appointment for the reminder call.
appointment_reminders.quiet_hours_enabledbooleanHold reminders during quiet hours; due ones go out after.
appointment_reminders.quiet_start_hourinteger · 0–23Local hour quiet hours start.
appointment_reminders.quiet_end_hourinteger · 0–23Local hour quiet hours end.
auto_closeobjectClosing inactive conversations: only the settings to change.
auto_close.enabledbooleanClose inactive conversations.
auto_close.channel_idsuuid[] · 0–50 itemsThe agent's active WhatsApp channels where it closes them (at least one while on).
auto_close.after_minutesinteger · 60–43,200Minutes without a message before a conversation is closed.
auto_close.archive_enabledbooleanAlso archive it when closing.
auto_close.skip_human_takeoverbooleanNever close a conversation a person took over.
auto_close.skip_customer_waitingbooleanNever close a conversation whose last message is the customer's.
campaign_messagesobjectCampaign messages on the agent's lines in a chat your team took over: only the settings to change.
campaign_messages.send_to_held_chatsbooleanA campaign's WhatsApp template step still goes out in a chat your team took over; otherwise it waits until the chat is handed back. Off by default (until it is saved, it follows appointment_reminders.remind_held_chats). A person's own exception, set in the dashboard, wins.
Show 30 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictThe agent has no version yet, or its automations changed while saving (try again).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/automations \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"follow_ups": {
"enabled": true,
"channel_ids": [
"9f19ef32-eaef-452c-bebc-14d9759cdb64"
],
"delays_minutes": [
240,
1440
]
}
}'saved_as_new_version is true when a campaign A/B test kept the version and the change became a new one.{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"follow_ups": {
"enabled": true,
"channel_ids": [
"9f19ef32-eaef-452c-bebc-14d9759cdb64"
],
"delays_minutes": [
240,
1440
],
"instructions": "Ask whether they still want the appointment.",
"quiet_hours_enabled": true,
"quiet_start_hour": 21,
"quiet_end_hour": 9,
"enabled_at": "2026-10-23T18:04:11.000Z",
"follow_up_held_chats": false
},
"appointment_reminders": {
"enabled": true,
"whatsapp_channel_ids": [
"9f19ef32-eaef-452c-bebc-14d9759cdb64"
],
"voice_channel_ids": [],
"offsets_minutes": [
1440,
120
],
"whatsapp_enabled": true,
"confirmation_enabled": true,
"voice_enabled": false,
"voice_offset_minutes": 240,
"quiet_hours_enabled": true,
"quiet_start_hour": 21,
"quiet_end_hour": 9,
"day_reminders_at_hour": false,
"day_reminder_hour": 9,
"late_booking_reminders": false,
"remind_held_chats": false
},
"auto_close": {
"enabled": false,
"channel_ids": [],
"after_minutes": 4320,
"archive_enabled": true,
"skip_human_takeover": true,
"skip_customer_waiting": false
},
"campaign_messages": {
"send_to_held_chats": false
},
"saved_as_new_version": false
}
}/v1/agents/:id/follow-up-emailsGet an agent's follow-up emails
Returns the emails the agent may send the person it talks to when they ask for one (an invitation to an event, a link), and what sending them needs: workspace_enabled (follow-up emails are off until NuTalk switches them on for the workspace) and sending_ready (the workspace's Resend can send; null when it couldn't be read). readable is false when the saved follow-ups can't be read; the next change replaces them. agent_id, agent_name and version_id name the agent and the version the settings are on (null when it has none).
agents:readPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/follow-up-emails \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"enabled": true,
"items": [
{
"key": "taller_gratuito",
"enabled": true,
"name": "Invitación al taller gratuito",
"when": "When the person asks about the free workshop.",
"subject": "{{contact.first_name|Hola}}, tu lugar en el taller",
"body": "Te esperamos el martes. Aquí está el enlace para unirte.",
"link": null,
"event": {
"title": "Taller gratuito",
"weekday": 2,
"time": "19:00",
"timezone": "America/Mexico_City",
"duration_minutes": 60,
"join_url": "https://meet.example.com/taller"
},
"tag": "taller",
"reply_to": null
}
],
"readable": true,
"workspace_enabled": true,
"sending_ready": true
}
}/v1/agents/:id/follow-up-emailsChange an agent's follow-up emails
Saves the agent's follow-up emails. items replaces the whole list, enabled switches them all; what isn't sent stays as saved. Each enabled follow-up becomes an action the agent may take when the person asks for it, emailing the address they confirm. Switching emails on needs the workspace switch NuTalk turns on and the workspace's Resend ready to send; switching them off always saves.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy, and deploying another version later keeps it. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanSwitch every follow-up email on or off.
itemsobject[] · 0–5 itemsEvery follow-up email (at most 5); replaces the list.
items[].keystringThe follow-up's key: the action the agent calls is followup_<key>, and it never changes once saved. Send an existing follow-up's key to keep it; a new one sent without a key gets one from its name.
items[].enabledbooleanThis email's own switch (default on).
items[].namestring · up to 80requiredWhat the AI sees it as.
items[].whenstring · up to 400requiredWhen the AI should send it.
items[].subjectstring · up to 150requiredThe subject. Contact variables such as {{contact.first_name|there}} are filled.
items[].bodystring · up to 2,000requiredPlain text. Contact variables are filled.
items[].linkobject | nullA link the email offers.
items[].eventobject | nullA weekly event the email invites to: its next session.
items[].tagstring | null · up to 60The tag the contact gets.
items[].reply_tostring | nullWhere replies go (default: the workspace owner's address).
Show 8 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.403forbiddenFollow-up emails are off for the workspace (details.reason followup_emails_off): NuTalk switches them on.409conflictThe workspace's Resend isn't ready (details.reason resend_not_connected), or the agent has no version yet.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/follow-up-emails \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"items": [
{
"key": "taller_gratuito",
"enabled": true,
"name": "Invitación al taller gratuito",
"when": "When the person asks about the free workshop.",
"subject": "{{contact.first_name|Hola}}, tu lugar en el taller",
"body": "Te esperamos el martes. Aquí está el enlace para unirte.",
"link": null,
"event": {
"title": "Taller gratuito",
"weekday": 2,
"time": "19:00",
"timezone": "America/Mexico_City",
"duration_minutes": 60,
"join_url": "https://meet.example.com/taller"
},
"tag": "taller",
"reply_to": null
}
]
}'changed is false when nothing differed.{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"enabled": true,
"items": [
{
"key": "taller_gratuito",
"enabled": true,
"name": "Invitación al taller gratuito",
"when": "When the person asks about the free workshop.",
"subject": "{{contact.first_name|Hola}}, tu lugar en el taller",
"body": "Te esperamos el martes. Aquí está el enlace para unirte.",
"link": null,
"event": {
"title": "Taller gratuito",
"weekday": 2,
"time": "19:00",
"timezone": "America/Mexico_City",
"duration_minutes": 60,
"join_url": "https://meet.example.com/taller"
},
"tag": "taller",
"reply_to": null
}
],
"readable": true,
"changed": true
}
}/v1/agents/:id/human-handoffGet an agent's human handoff
Returns the agent's transfer to a person on calls: whether it may put a caller through to the workspace's AiBox handset, how many seconds it rings, the whisper the person hears before the caller, and when the agent should transfer. handsets lists the workspace's handsets (none: a transfer has nowhere to ring). agent_id, agent_name and version_id name the agent and the version the settings are on (null when it has none).
agents:readPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/human-handoff \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"enabled": true,
"ring_seconds": 25,
"whisper_enabled": true,
"whisper_intro": "Llamada de un paciente que pide hablar con recepción.",
"trigger_hint": "When the caller asks for a person or has an emergency.",
"handsets": [
{
"id": "2b3c4d5e-6f7a-4b8c-9dae-1f2a3b4c5d6e",
"name": "Recepción",
"status": "active",
"registration_status": "registered"
}
]
}
}/v1/agents/:id/human-handoffChange an agent's human handoff
Changes the settings sent; the rest stay as saved. A text sent as null is cleared.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy, and deploying another version later keeps it. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanWhether the agent may transfer a caller.
ring_secondsinteger · 5–90How long the handset rings.
whisper_enabledbooleanWhether the person hears a short intro before the caller.
whisper_introstring | null · up to 300What the person hears first.
trigger_hintstring | null · up to 500When the agent should transfer.
Show 1 more field
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/human-handoff \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"ring_seconds": 30
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"enabled": true,
"ring_seconds": 30,
"whisper_enabled": true,
"whisper_intro": null,
"trigger_hint": null,
"handsets": []
}
}/v1/agents/:id/pbx-transferGet an agent's PBX transfers
Returns the extensions of the workspace's PBX the agent may put a caller through to, each with a note on when, and extensions: the AI extensions to choose from (is_own: one the agent itself answers). available is false when the workspace has no PBX module. agent_id, agent_name and version_id name the agent and the version the settings are on (null when it has none).
agents:readPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/pbx-transfer \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"available": true,
"enabled": true,
"targets": [
{
"extension_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"note": "Billing questions."
}
],
"extensions": [
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"system_name": "Oficina",
"number": "201",
"label": "Cobranza",
"description": null,
"is_own": false
}
]
}
}/v1/agents/:id/pbx-transferChange an agent's PBX transfers
Changes the switch and the extensions: targets replaces the list; what isn't sent stays as saved, except saved extensions that are no longer live, which are dropped. Only the workspace's live AI extensions can be targets.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy, and deploying another version later keeps it. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanWhether the agent may transfer to them.
targetsobject[] · 0–20 itemsThe extensions it may transfer to (at most 20); replaces the list.
targets[].extension_iduuidrequiredAn id from extensions.
targets[].notestring | null · up to 240When to transfer there.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.403forbiddenThe workspace has no PBX module (NuTalk enables it for corporate plans).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/pbx-transfer \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"targets": [
{
"extension_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"note": "Billing questions."
}
]
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"available": true,
"enabled": true,
"targets": [
{
"extension_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"note": "Billing questions."
}
],
"extensions": []
}
}/v1/agents/:id/context-settingsGet an agent's knowledge and memory settings
Returns whether the agent answers from its knowledge sources and what it remembers of each person it talks to. agent_id, agent_name and version_id name the agent and the version the settings are on (null when it has none).
agents:readPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/context-settings \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"knowledge_enabled": true,
"inject_profile": true,
"inject_episodes": true,
"recall_tool_enabled": true,
"restart_mode": "smart",
"memory_scope": "channels",
"memory_channel_ids": [
"6e1b3a5c-7d9f-4b2e-8a4c-6e8a0c2e4b17"
]
}
}/v1/agents/:id/context-settingsChange an agent's knowledge and memory settings
Changes the settings sent; the rest stay as saved. memory_channel_ids must be channels of the workspace.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy, and deploying another version later keeps it. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
The technical values (passages per answer, the quiet period that ends a conversation's summary, the search server) are set by NuTalk and can't be sent.
Path parameters
iduuidrequiredThe agent id.
Request body
knowledge_enabledbooleanAnswer from the agent's knowledge sources.
inject_profilebooleanRemember what each person told it before (their profile).
inject_episodesbooleanRemember summaries of each person's past conversations.
recall_tool_enabledbooleanLet the agent search a person's past conversations when it needs to.
restart_modesmart | resume | freshHow a returning person's conversation restarts: smart (the agent decides), resume (it carries on) or fresh.
memory_scopechannel | channels | agent | workspaceWho shares what the agent remembers of a person: channel (the conversation's channel), channels (it and memory_channel_ids), agent (every channel the agent runs on) or workspace.
memory_channel_idsuuid[] · 0–50 itemsThe workspace's channels pooled with memory_scope channels.
Show 3 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictThe agent has no version to save the settings on yet.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/context-settings \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"memory_scope": "channels",
"memory_channel_ids": [
"6e1b3a5c-7d9f-4b2e-8a4c-6e8a0c2e4b17"
]
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"knowledge_enabled": true,
"inject_profile": true,
"inject_episodes": true,
"recall_tool_enabled": true,
"restart_mode": "smart",
"memory_scope": "channels",
"memory_channel_ids": [
"6e1b3a5c-7d9f-4b2e-8a4c-6e8a0c2e4b17"
]
}
}/v1/agents/:id/calcomGet an agent's Cal.com booking
Returns how the agent books with Cal.com: whether it is on, the event type, its length and time zone, and connected: whether the workspace's Cal.com account is connected (its credentials are never returned). agent_id, agent_name and version_id name the agent and the version the settings are on (null when it has none).
agents:readPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/calcom \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"enabled": true,
"event_type_slug": "consulta-30",
"event_type_id": 1234567,
"duration_minutes": 30,
"timezone": "America/Monterrey",
"connected": true
}
}/v1/agents/:id/calcomChange an agent's Cal.com booking
Changes the settings sent; the rest stay as saved. While booking is on, the event type is checked with Cal.com. Connecting or disconnecting the workspace's Cal.com account is done in the dashboard.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy, and deploying another version later keeps it. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanBook with Cal.com. Switching it on checks the event type with Cal.com, and an agent books one way only: when another booking method is chosen for it, it is refused.
event_type_idinteger · at least 1The event type's id (GET /v1/agents/{id}/calcom/event-types), sent with its event_type_slug: the agent books by the id.
event_type_slugstring · up to 200The event type's slug, sent with its event_type_id.
duration_minutesinteger | null · 5–480The meeting's length, when the event type allows several; null clears it.
timezonestring · up to 64The time zone it books in, e.g. America/Monterrey.
Show 1 more field
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictThe workspace's Cal.com account isn't connected (details.reason calcom_not_connected): connect it in the dashboard first.409conflictAnother booking method is chosen for the agent (details.reason booking_method_conflict).422validation_errorCal.com refused the event type (details.reason calcom_check_failed).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/calcom \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"event_type_id": 1234567,
"event_type_slug": "consulta-30",
"timezone": "America/Monterrey"
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": "2ea87934-6e03-4db7-80f2-ac753b724c82",
"enabled": true,
"event_type_slug": "consulta-30",
"event_type_id": 1234567,
"duration_minutes": 30,
"timezone": "America/Monterrey",
"connected": true
}
}/v1/agents/:id/calcom/event-typesList the Cal.com event types
Lists the event types of the workspace's Cal.com account (asked of Cal.com with the workspace's connection), to choose the one the agent books.
agents:readWorkspace keys only · acts as the key's creatorRead as the member who created the key, with a role that edits agents (owner, admin or builder).
Path parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictThe workspace's Cal.com account isn't connected (details.reason calcom_not_connected): connect it in the dashboard first.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/calcom/event-types \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": 1234567,
"slug": "consulta-30",
"title": "Consulta (30 min)",
"length_minutes": 30
}
]
}/v1/agents/:id/restoreRestore an archived agent
Brings back an archived agent (GET /v1/agents?status=archived lists them). It is active again when one of its versions is still deployed, a draft otherwise, and it comes back on no channel: put it on one with PUT /v1/channels/{id}/agent. An agent that isn't archived is left as it is (restored: false).
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
Path parameters
iduuidrequiredThe agent id.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/restore \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"restored": true,
"status": "active"
}
}/v1/agents/:id/booking-methodGet an agent's booking method
How the agent books: one method per agent (none, clinic, business, calcom or api_action, one of its REST write actions). method is null when several are in use and none was chosen. available says which methods the workspace can use now and why not; lines are the agent's channels and the scheduling mode each runs.
agents:readWorkspace keys only · acts as the key's creatorPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/booking-method \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"method": "business",
"chosen": true,
"in_use": [
"business"
],
"proposed": "business",
"action": null,
"available": {
"clinic": {
"available": false,
"reason": "module_missing"
},
"business": {
"available": true,
"reason": null
},
"calcom": {
"available": false,
"reason": "calcom_not_connected"
},
"api_action": {
"available": false,
"reason": "no_write_actions"
}
},
"lines": [
{
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Sales line",
"type": "voice",
"scheduling_mode": "business"
}
],
"write_actions": [],
"business": {
"meeting_type_ids": [
"4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d"
],
"default_meeting_type_id": null
}
}
}/v1/agents/:id/booking-methodChange an agent's booking method
Sets how the agent books, as its Booking card does: it records the method, makes the agent's live versions follow it and points the agent's channels at it, in one transaction. business takes meeting_type_ids (the agent's meeting types; people for each are set with business-booking), api_action the REST write action that books.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
Restaurant reservations can't be an agent's booking method yet.
Path parameters
iduuidrequiredThe agent id.
Request body
methodnone | clinic | business | calcom | api_actionrequiredThe booking method.
actionstringFor api_action: the name of one of the agent's REST write actions.
meeting_type_idsuuid[] · 1–50 itemsFor business: the meeting types the agent offers.
default_meeting_type_iduuidFor business, instead of a list: the one meeting type an older agent books.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).400validation_errorThe method isn't available for the workspace (its module is off, Cal.com isn't connected, the REST actions are off), a meeting type isn't the workspace's (details.reason meeting_type_not_available), or the action isn't one of the agent's write actions.409conflictA campaign A/B test calls with the agent's live version (details.reason live_version_in_ab_test): promote a variant first.403forbiddenThe key lacks channels:write (the change points the agent's channels at the method), or the member who created it can't edit agents, or it is a reseller key; or the agent answers a Zoom Phone line and that member isn't an owner or admin (details.reason ZOOM_MANAGERS_ONLY), since the method is copied onto that line too.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/booking-method \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"method": "business",
"meeting_type_ids": [
"4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d",
"5a3c7b2d-9e4f-4b6c-8d8e-2f3a4b5c6d7e"
]
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"method": "business",
"chosen": true,
"in_use": [
"business"
],
"proposed": "business",
"action": null,
"available": {
"clinic": {
"available": false,
"reason": "module_missing"
},
"business": {
"available": true,
"reason": null
},
"calcom": {
"available": false,
"reason": "calcom_not_connected"
},
"api_action": {
"available": false,
"reason": "no_write_actions"
}
},
"lines": [
{
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Sales line",
"type": "voice",
"scheduling_mode": "business"
}
],
"write_actions": [],
"business": {
"meeting_type_ids": [
"4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d"
],
"default_meeting_type_id": null
}
}
}/v1/agents/:id/clinic-bookingGet an agent's clinic booking
How the agent books clinic appointments: which doctors, rooms and services it offers, its defaults, what it asks the patient, what it may do with an appointment and its emergency guidance. Empty lists mean all of them.
agents:readWorkspace keys only · acts as the key's creatorPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/clinic-booking \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"enabled": true,
"timezone": "America/Monterrey",
"scopes": {
"consult_services": true,
"consult_deals": true,
"check_availability": true,
"book_appointment": true,
"lookup_appointments": true,
"reschedule_appointment": true,
"cancel_appointment": false,
"confirm_appointment": true
},
"allowed_doctor_ids": [
"3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7"
],
"allowed_room_ids": [],
"allowed_service_ids": [
"c06c8eaf-4b5d-4e7a-9c9f-1b3d5f7a9cb4"
],
"default_doctor_id": null,
"default_room_id": null,
"default_service_id": "c06c8eaf-4b5d-4e7a-9c9f-1b3d5f7a9cb4",
"required_patient_fields": [
"name",
"phone"
],
"patient_record_ask": "after_booking",
"patient_arrival_offset_minutes": 10,
"confirmation_instructions": "Bring your ID and arrive 10 minutes early.",
"fallback_message": null,
"emergency_guidance_enabled": true,
"emergency_contact": "911",
"emergency_message_es": null,
"emergency_message_en": null
}
}/v1/agents/:id/clinic-bookingChange an agent's clinic booking
Changes the settings sent; the rest stay as saved. Doctors, rooms and services must be the workspace's active ones (GET /v1/clinic/doctors, rooms and services).
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanThe agent books clinic appointments.
timezonestring | nullIANA timezone; null uses the clinic's.
scopesobjectWhat the agent may do, each true or false; only the ones sent change. Booking or rescheduling turns availability on.
scopes.consult_servicesbooleanconsult services.
scopes.consult_dealsbooleanconsult deals.
scopes.check_availabilitybooleancheck availability.
scopes.book_appointmentbooleanbook appointment.
scopes.lookup_appointmentsbooleanlookup appointments.
scopes.reschedule_appointmentbooleanreschedule appointment.
scopes.cancel_appointmentbooleancancel appointment.
scopes.confirm_appointmentbooleanconfirm appointment.
allowed_doctor_idsuuid[]The doctors it offers ([]: all of them).
allowed_room_idsuuid[]The rooms it books ([]: all of them).
allowed_service_idsuuid[]The services it offers ([]: all of them).
default_doctor_iduuid | nullThe doctor booked when the patient has no preference.
default_room_iduuid | nullThe room booked by default.
default_service_iduuid | nullThe service booked when none is named.
required_patient_fieldsstring[]What it asks the patient before booking.
patient_record_askafter_booking | before_booking | neverWhen it asks the clinic's patient record: after_booking (the default), before_booking or never. On WhatsApp lines. It never blocks a booking.
patient_arrival_offset_minutesinteger · 0–240Minutes before the appointment the patient is asked to arrive.
confirmation_instructionsstring | null · up to 4,000What it tells the patient after booking.
fallback_messagestring | null · up to 4,000What it says when it can't book.
emergency_guidance_enabledbooleanIt tells a patient describing an emergency to get urgent help instead of booking.
emergency_contactstring | null · up to 4,000The number or place it gives in an emergency.
emergency_message_esstring | null · up to 4,000Its emergency message in Spanish.
emergency_message_enstring | null · up to 4,000Its emergency message in English.
Show 22 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictAnother booking method is chosen for the agent (details.reason booking_method_conflict): change the booking method first.409conflictA room named was removed meanwhile (details.reason room_not_found).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/clinic-booking \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"allowed_service_ids": [
"c06c8eaf-4b5d-4e7a-9c9f-1b3d5f7a9cb4"
],
"required_patient_fields": [
"name",
"phone",
"email"
],
"scopes": {
"cancel_appointment": false
}
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"enabled": true,
"timezone": "America/Monterrey",
"scopes": {
"consult_services": true,
"consult_deals": true,
"check_availability": true,
"book_appointment": true,
"lookup_appointments": true,
"reschedule_appointment": true,
"cancel_appointment": false,
"confirm_appointment": true
},
"allowed_doctor_ids": [
"3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7"
],
"allowed_room_ids": [],
"allowed_service_ids": [
"c06c8eaf-4b5d-4e7a-9c9f-1b3d5f7a9cb4"
],
"default_doctor_id": null,
"default_room_id": null,
"default_service_id": "c06c8eaf-4b5d-4e7a-9c9f-1b3d5f7a9cb4",
"required_patient_fields": [
"name",
"phone"
],
"patient_record_ask": "after_booking",
"patient_arrival_offset_minutes": 10,
"confirmation_instructions": "Bring your ID and arrive 10 minutes early.",
"fallback_message": null,
"emergency_guidance_enabled": true,
"emergency_contact": "911",
"emergency_message_es": null,
"emergency_message_en": null
}
}/v1/agents/:id/business-bookingGet an agent's business booking
How the agent books business meetings: the meeting types it offers, each with the people who take it for this agent (null: everyone who takes it), the one it books without asking, HubSpot owner routing and what it may do with a booked meeting. meeting_types is null for an agent that books its one default meeting type; can_book says whether its saved settings can book on its channels.
agents:readWorkspace keys only · acts as the key's creatorPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/business-booking \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"module_enabled": true,
"enabled": true,
"check_availability": true,
"book_appointment": true,
"lookup_appointments": true,
"reschedule_appointment": true,
"cancel_appointment": false,
"meeting_types": [
{
"id": "4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d",
"host_ids": null
},
{
"id": "5a3c7b2d-9e4f-4b6c-8d8e-2f3a4b5c6d7e",
"host_ids": [
"6b4d8c3e-0f5a-4c7d-9e9f-3a4b5c6d7e8f"
]
}
],
"default_meeting_type_id": "4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d",
"default_host_id": null,
"route_by_hubspot_owner": false,
"timezone": "America/Monterrey",
"can_book": true
}
}/v1/agents/:id/business-bookingChange an agent's business booking
Changes the settings sent; the rest stay as saved. meeting_types replaces the list (at least one; to stop booking, set the booking method to none). With meeting types, who takes each one is set per type, so default_host_id can't change.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The change applies at once on the agent's live version (its newest when none is live), with no deploy. A version a campaign A/B test calls with keeps its settings: the change is then saved as a new version, deployed in its place.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanThe agent books business meetings.
check_availabilitybooleanIt may look up free times.
book_appointmentbooleanIt may book a meeting.
lookup_appointmentsbooleanIt may find the person's meetings.
reschedule_appointmentbooleanIt may move a meeting.
cancel_appointmentbooleanIt may cancel a meeting.
meeting_typesobject[] · 1–50 itemsThe meeting types it offers, from GET /v1/business/meeting-types; replaces the list.
meeting_types[].iduuidrequiredThe meeting type.
meeting_types[].host_idsuuid[] | nullThe people who take it for this agent; null: everyone who takes it.
default_meeting_type_iduuid | nullThe meeting type it books without asking; one of its meeting types.
default_host_iduuid | nullFor an agent without meeting types (one default type): the host it books with.
route_by_hubspot_ownerbooleanA lead with a HubSpot owner meets that owner when they take the meeting type.
timezonestring | nullIANA timezone; null uses the workspace's.
Show 9 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictAnother booking method is chosen for the agent (details.reason booking_method_conflict): change the booking method first.400validation_errorThe Business module is off, a meeting type or person isn't available (details.reason says which rule), the default isn't one of the meeting types (default_not_listed), or the default host can't change (default_host_per_meeting_type).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/business-booking \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"meeting_types": [
{
"id": "4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d",
"host_ids": null
},
{
"id": "5a3c7b2d-9e4f-4b6c-8d8e-2f3a4b5c6d7e",
"host_ids": [
"6b4d8c3e-0f5a-4c7d-9e9f-3a4b5c6d7e8f"
]
}
],
"default_meeting_type_id": "4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d"
}'{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"module_enabled": true,
"enabled": true,
"check_availability": true,
"book_appointment": true,
"lookup_appointments": true,
"reschedule_appointment": true,
"cancel_appointment": false,
"meeting_types": [
{
"id": "4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d",
"host_ids": null
},
{
"id": "5a3c7b2d-9e4f-4b6c-8d8e-2f3a4b5c6d7e",
"host_ids": [
"6b4d8c3e-0f5a-4c7d-9e9f-3a4b5c6d7e8f"
]
}
],
"default_meeting_type_id": "4f2b6a1c-8d3e-4a5b-9c7d-1e2f3a4b5c6d",
"default_host_id": null,
"route_by_hubspot_owner": false,
"timezone": "America/Monterrey",
"can_book": true
}
}/v1/agents/:id/rest-connectorGet an agent's REST connector
The REST actions the agent may call on your API during a conversation: the base URL, how it signs in (has_token and has_password say whether one is saved, never its value), the actions and the instructions for using them. Each write action has its risk (who says yes before NuTalk makes the change) and channels lists the agent's channels with how the customer confirms on each: buttons on WhatsApp's Cloud API, code in the other chats, and conversation on a call (the agent asks in the conversation) until calls ask for a key (dtmf).
agents:readWorkspace keys only · acts as the key's creatorPath parameters
iduuidrequiredThe agent id.
Errors
404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/rest-connector \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"configured": true,
"enabled": true,
"base_url": "https://api.example.com/v2",
"auth_type": "bearer",
"auth_header": "Authorization",
"auth_username": null,
"has_token": true,
"has_password": false,
"actions": [
{
"name": "order_status",
"description": "Look up an order when the customer gives its number.",
"label": null,
"method": "GET",
"path": "/orders/{order_number}",
"mode": "read",
"required_params": [
"order_number"
],
"response_hint": "status and delivery_date",
"timeout_ms": 10000,
"risk": null,
"high_mode": null,
"confirm_off_channels": []
},
{
"name": "book_visit",
"description": "Book a visit once the customer picks a time.",
"label": "Book your visit",
"method": "POST",
"path": "/visits",
"mode": "write",
"required_params": [
"slot_start",
"email"
],
"response_hint": null,
"timeout_ms": 10000,
"risk": "medium",
"high_mode": null,
"confirm_off_channels": []
}
],
"instructions": "Ask for the order number before looking it up.",
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Sales",
"kind": "whatsapp",
"confirm_via": "buttons"
}
]
}
}/v1/agents/:id/rest-connectorChange an agent's REST connector
Changes the settings sent; the rest stay as saved. The base URL must be a public HTTPS address. Tokens and passwords are added in NuTalk only (the agent's Actions → REST API), never through the API: a change to the base URL (another path on the same host too, a trailing slash aside) or to how it signs in clears the saved ones (secrets_cleared: true), so they never follow it there. Such a change can't switch the connector on: send enabled: false with it, add the secret in NuTalk, then switch it on.
agents:writeCan wait for approvalWorkspace keys only · acts as the key's creatorA change runs the dashboard's own rules as the member who created the key: the key needs agents:write, and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
The agent calls your API with what customers tell it: confirm the URL and the actions with the user first.
Only an owner's or admin's key may add or change an action that can change data (mode write, or any method but GET), the base URL or how it signs in; each such change is told to the workspace's owners.
A key acts at most as an admin: risk low and a channel without the customer's confirmation are set by an owner in NuTalk, and a save that leaves an action's risk fields out keeps them.
Path parameters
iduuidrequiredThe agent id.
Request body
enabledbooleanThe agent may call the actions.
base_urlstring | null · up to 500A public HTTPS URL, with no credentials, query or fragment.
auth_typenone | bearer | api_key_header | basic | custom_headerHow the connector signs in. The token or password is added in NuTalk.
auth_headerstring · up to 80The header for api_key_header and custom_header.
auth_usernamestring | null · up to 200The username for basic.
actionsobject[] · 0–20 itemsThe actions the agent may call; replaces the list.
actions[].namestringrequired2-64 lowercase letters, digits or _, starting with a letter: how the agent calls it. Names starting with followup_ are the agent's follow-up emails.
actions[].descriptionstring · up to 500requiredWhen the agent should call it.
actions[].methodGET | POST | PUT | PATCHThe HTTP method. Default: POST.
actions[].pathstring · up to 300requiredThe path after the base URL, starting with /.
actions[].moderead | writeread looks something up; write changes something (and can be the booking method). Default: read.
actions[].required_paramsstring[] · 0–12 itemsThe parameters the agent must collect before calling it.
actions[].response_hintstring | null · up to 500How to read the answer.
actions[].timeout_msinteger · 1000–15,000How long the agent waits. Default: 10000.
actions[].labelstring | null · up to 60What the customer reads as the action's name when asked to confirm it. Left out, the saved one stays; null clears it.
actions[].risklow | medium | high | nullWrite actions only: medium (the default) the customer confirms each one; high the agent never does it on its own (high_mode); low never asks, and only an owner sets it, in NuTalk. Left out or null (with high_mode and confirm_off_channels), the saved risk stays.
actions[].high_modeteam | blocked | nullFor risk high: team (the default) an owner or admin approves each one in NuTalk; blocked the agent may not use it.
actions[].confirm_off_channelsuuid[] · 0–50 itemsFor risk medium: the agent's channels where the customer doesn't confirm it. Only an owner turns one off, in NuTalk; any key may turn one back on by leaving it out.
instructionsstring | null · up to 4,000How the agent should use the actions.
Show 15 more fields
The API never sends or shows the connector's token or password. Changing its base URL (another path on the same host too) or how it signs in clears them, so add the new one in NuTalk (the agent's Actions → REST API) before switching it on again.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).403forbiddenThe member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key.409conflictAnother booking method is chosen for the agent (details.reason booking_method_conflict): change the booking method first.400validation_errorThe base URL isn't public HTTPS, an action is invalid, a name is reserved (reserved_action_name), the connector needs a secret NuTalk doesn't have (secret_required), or switching it on lacks a URL or an action.403forbiddenThe change adds or changes an action that can change data (mode write, or any method but GET), moves the base URL or changes how it signs in, and the key's creator isn't an owner or admin (owner_or_admin_required), or it sets an action's risk to low or turns the customer's confirmation off on a channel, which only an owner does, in NuTalk (owner_required): nothing was saved.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/rest-connector \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"base_url": "https://api.example.com/v2",
"actions": [
{
"name": "order_status",
"description": "Look up an order when the customer gives its number.",
"method": "GET",
"path": "/orders/{order_number}",
"mode": "read",
"required_params": [
"order_number"
]
}
]
}'secrets_cleared{
"success": true,
"data": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "Sofía",
"version_id": null,
"configured": true,
"enabled": true,
"base_url": "https://api.example.com/v2",
"auth_type": "bearer",
"auth_header": "Authorization",
"auth_username": null,
"has_token": true,
"has_password": false,
"actions": [
{
"name": "order_status",
"description": "Look up an order when the customer gives its number.",
"label": null,
"method": "GET",
"path": "/orders/{order_number}",
"mode": "read",
"required_params": [
"order_number"
],
"response_hint": "status and delivery_date",
"timeout_ms": 10000,
"risk": null,
"high_mode": null,
"confirm_off_channels": []
},
{
"name": "book_visit",
"description": "Book a visit once the customer picks a time.",
"label": "Book your visit",
"method": "POST",
"path": "/visits",
"mode": "write",
"required_params": [
"slot_start",
"email"
],
"response_hint": null,
"timeout_ms": 10000,
"risk": "medium",
"high_mode": null,
"confirm_off_channels": []
}
],
"instructions": "Ask for the order number before looking it up.",
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Sales",
"kind": "whatsapp",
"confirm_via": "buttons"
}
],
"secrets_cleared": false
}
}/v1/agents/:id/versions/:version_idGet one version of an agent
One version of the agent, deployed or a draft, with its instructions and the settings PATCH /v1/agents/{id} writes (language, identity, purpose, call opening): what a draft says before it is deployed. GET /v1/agents/{id} lists the versions.
agents:readPath parameters
iduuidrequiredThe agent id.
version_iduuidrequiredThe version id.
Errors
404not_foundNo agent or version with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/versions/c5c0810c-4614-4f0d-927d-62e587dad45e \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "c5c0810c-4614-4f0d-927d-62e587dad45e",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"version_label": "v1.5",
"deployment_status": "draft",
"published_at": null,
"created_at": "2026-10-26T15:00:00.000Z",
"instructions": "You are Sofía, the clinic's receptionist...",
"language": "es-MX",
"identity_name": "Sofía",
"purpose": "Book first consultations",
"greeting": "¡Hola! Soy Sofía.",
"say_greeting_exactly": false
}
}