Update AI agent

PATCH

https://{your_space_name}.signalwire.com/api/fabric/resources/ai_agents/:id

PATCH

/api/fabric/resources/ai_agents/:id

$ curl -X PATCH https://{your_space_name}.signalwire.com/api/fabric/resources/ai_agents/id \
>      -H "Content-Type: application/json" \
>      -u "<project_id>:<api_token>" \
>      -d '{}'

1 {
2   "id": "a87db7ed-8ebe-42e4-829f-8ba5a4152f54",
3   "project_id": "99151cf8-9548-4860-ba70-a8de824f3312",
4   "display_name": "Booking Assistant",
5   "type": "ai_agent",
6   "created_at": "2024-05-06T12:20:00Z",
7   "updated_at": "2024-05-06T12:20:00Z",
8   "ai_agent": {
9     "prompt": {
10       "max_tokens": 256,
11       "temperature": 0.7,
12       "top_p": 0.9,
13       "confidence": 0.6,
14       "presence_penalty": 0,
15       "frequency_penalty": 0,
16       "text": "Your name is Franklin and you are taking orders for Franklin's Pizza. Begin by greeting the caller, and ask if they'd like to place an order for pickup or delivery.",
17       "contexts": {
18         "default": {
19           "steps": [
20             {
21               "name": "Take Pizza order",
22               "step_criteria": "Customer wants to order Pizza",
23               "functions": [
24                 "Take Order",
25                 "Confirm Order",
26                 "Confirm Address"
27               ],
28               "valid_contexts": [
29                 "Place Order",
30                 "Confirm Order"
31               ],
32               "skip_user_turn": true,
33               "end": true,
34               "valid_steps": [
35                 "get order",
36                 "confirm order"
37               ],
38               "pom": {}
39             }
40           ],
41           "isolated": true,
42           "enter_fillers": [
43             {
44               "default": [
45                 "one moment please",
46                 "let me check"
47               ]
48             }
49           ],
50           "exit_fillers": [
51             {
52               "default": [
53                 "one moment please",
54                 "let me check"
55               ]
56             }
57           ],
58           "pom": [
59             {
60               "title": "Customer Service Guidelines",
61               "subsections": {},
62               "numbered": true,
63               "numberedBullets": false,
64               "body": "Welcome customers warmly and assist them with their inquiries.",
65               "bullets": [
66                 "Be polite and professional",
67                 "Listen actively to customer concerns",
68                 "Provide accurate information"
69               ]
70             }
71           ]
72         }
73       }
74     },
75     "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
76     "name": "My AI Agent",
77     "global_data": {
78       "company_name": "Acme Corp",
79       "support_hours": "9am-5pm EST"
80     },
81     "hints": [
82       "pizza",
83       "pepperoni"
84     ],
85     "languages": [
86       {
87         "name": "French",
88         "code": "fr-FR",
89         "voice": "gcloud.fr-FR-Neural2-B",
90         "model": "arcana",
91         "emotion": "auto",
92         "speed": "auto",
93         "engine": "elevenlabs",
94         "params": {
95           "stability": 1.1,
96           "similarity": 1.1
97         },
98         "fillers": [
99           "umm",
100           "let me check"
101         ]
102       }
103     ],
104     "params": {
105       "acknowledge_interruptions": true,
106       "ai_model": "gpt-4o-mini",
107       "ai_name": "assistant",
108       "ai_volume": 0,
109       "app_name": "customer-support-bot",
110       "asr_smart_format": true,
111       "attention_timeout": 30000,
112       "attention_timeout_prompt": "Ask if the user would like you to repeat yourself, or if they need more time to respond.",
113       "asr_diarize": true,
114       "asr_speaker_affinity": true,
115       "audible_debug": false,
116       "audible_latency": false,
117       "background_file": "https://cdn.signalwire.com/default-music/welcome.mp3",
118       "background_file_loops": 5,
119       "background_file_volume": -10,
120       "enable_barge": "complete,partial",
121       "enable_inner_dialog": true,
122       "enable_pause": true,
123       "enable_turn_detection": true,
124       "barge_match_string": "Cancel order",
125       "barge_min_words": 3,
126       "barge_functions": true,
127       "cache_mode": true,
128       "conscience": "Place an order",
129       "convo": [
130         {
131           "role": "user",
132           "content": "Hello, how can I assist you today?",
133           "lang": "en"
134         }
135       ],
136       "conversation_id": "Conversation ID",
137       "conversation_sliding_window": 20,
138       "debug_webhook_level": 1,
139       "debug_webhook_url": "https://example.com",
140       "debug": true,
141       "direction": "inbound",
142       "digit_terminators": "#",
143       "digit_timeout": 3000,
144       "end_of_speech_timeout": 700,
145       "enable_accounting": true,
146       "enable_thinking": true,
147       "enable_vision": true,
148       "energy_level": 52,
149       "first_word_timeout": 1000,
150       "function_wait_for_talking": true,
151       "functions_on_no_response": true,
152       "hard_stop_prompt": "Thank you for calling. The maximum call time has been reached. Goodbye!",
153       "hard_stop_time": "30m",
154       "hold_music": "https://cdn.signalwire.com/default-music/welcome.mp3",
155       "hold_on_process": true,
156       "inactivity_timeout": 600000,
157       "inner_dialog_model": "gpt-4.1-nano",
158       "inner_dialog_prompt": "Analyze the conversation and provide insights to help the agent respond better.",
159       "inner_dialog_synced": true,
160       "initial_sleep_ms": 1000,
161       "input_poll_freq": 2000,
162       "interrupt_on_noise": true,
163       "interrupt_prompt": "Inform user that you can't hear anything",
164       "languages_enabled": true,
165       "local_tz": "America/Ensenada",
166       "llm_diarize_aware": true,
167       "max_emotion": 15,
168       "max_response_tokens": 1024,
169       "openai_asr_engine": "nova-3",
170       "outbound_attention_timeout": 120000,
171       "persist_global_data": true,
172       "pom_format": "markdown",
173       "save_conversation": true,
174       "speech_event_timeout": 1400,
175       "speech_gen_quick_stops": 3,
176       "speech_timeout": 60000,
177       "speak_when_spoken_to": true,
178       "start_paused": true,
179       "static_greeting": "Hello! Welcome to our customer service. How can I help you today?",
180       "static_greeting_no_barge": true,
181       "summary_mode": "string",
182       "swaig_allow_settings": true,
183       "swaig_allow_swml": true,
184       "swaig_post_conversation": true,
185       "swaig_set_global_data": true,
186       "swaig_post_swml_vars": true,
187       "thinking_model": "gpt-4.1-mini",
188       "transparent_barge": true,
189       "transparent_barge_max_time": 3000,
190       "transfer_summary": true,
191       "turn_detection_timeout": 250,
192       "tts_number_format": "international",
193       "verbose_logs": true,
194       "video_listening_file": "https://example.com/listening.mp4",
195       "video_idle_file": "https://example.com/idle.mp4",
196       "video_talking_file": "https://example.com/talking.mp4",
197       "vision_model": "gpt-4o-mini",
198       "vad_config": "50:20",
199       "wait_for_user": true,
200       "wake_prefix": "hey",
201       "eleven_labs_stability": 0.5,
202       "eleven_labs_similarity": 0.75
203     },
204     "post_prompt": {
205       "max_tokens": 256,
206       "temperature": 0.7,
207       "top_p": 0.9,
208       "confidence": 0.6,
209       "presence_penalty": 0,
210       "frequency_penalty": 0,
211       "text": "Summarize the conversation and provide any follow-up action items."
212     },
213     "post_prompt_url": "username:password@https://example.com",
214     "pronounce": [
215       {
216         "replace": "pizza",
217         "with": "pissa",
218         "ignore_case": true
219       }
220     ],
221     "SWAIG": {
222       "defaults": {
223         "web_hook_url": "username:password@https://example.com"
224       },
225       "native_functions": [
226         "check_time"
227       ],
228       "includes": [
229         {
230           "functions": [
231             "transfer call",
232             "notify kitchen"
233           ],
234           "url": "username:password@https://example.com",
235           "meta_data": {
236             "customer_id": "cust_123",
237             "session_type": "support"
238           }
239         }
240       ],
241       "functions": [
242         {
243           "description": "Get the weather information",
244           "purpose": "Get the weather information",
245           "parameters": {
246             "type": "object",
247             "properties": {},
248             "required": [
249               "name1",
250               "name2"
251             ]
252           },
253           "fillers": {
254             "default": [
255               "one moment please",
256               "let me check"
257             ]
258           },
259           "argument": {
260             "type": "object",
261             "properties": {},
262             "required": [
263               "name1",
264               "name2"
265             ]
266           },
267           "active": true,
268           "meta_data": {
269             "api_key": "key_123",
270             "endpoint": "https://api.example.com"
271           },
272           "meta_data_token": "my-function-scope",
273           "data_map": {
274             "output": {
275               "response": "Order placed",
276               "action": [
277                 {
278                   "SWML": {}
279                 }
280               ]
281             },
282             "expressions": [
283               {
284                 "string": "I want a refund",
285                 "pattern": "refund|return|money back",
286                 "output": {
287                   "response": "Order placed",
288                   "action": [
289                     {}
290                   ]
291                 }
292               }
293             ],
294             "webhooks": [
295               {
296                 "expressions": [
297                   {
298                     "string": "I want a refund",
299                     "pattern": "refund|return|money back",
300                     "output": {
301                       "response": "Order placed",
302                       "action": {}
303                     }
304                   }
305                 ],
306                 "error_keys": "failed",
307                 "url": "https://example.com",
308                 "foreach": {
309                   "input_key": "success",
310                   "output_key": "deliverer",
311                   "max": 5,
312                   "append": "title: ${this.title}, contact: ${this.phone}"
313                 },
314                 "headers": {
315                   "Content-Type": "application/json",
316                   "X-API-Key": "your-api-key"
317                 },
318                 "method": "POST",
319                 "input_args_as_params": true,
320                 "params": {
321                   "account_id": "acc_123",
322                   "include_details": true
323                 },
324                 "require_args": [
325                   "order_id",
326                   "customer_email"
327                 ],
328                 "output": {
329                   "response": "Order placed",
330                   "action": [
331                     {}
332                   ]
333                 }
334               }
335             ]
336           },
337           "skip_fillers": true,
338           "web_hook_url": "username:password:https://statuscallback.com",
339           "wait_file": "https://cdn.signalwire.com/default-music/welcome.mp3",
340           "wait_file_loops": 5,
341           "wait_for_fillers": true,
342           "function": "get_weather"
343         }
344       ],
345       "internal_fillers": {
346         "hangup": {
347           "default": [
348             "one moment please",
349             "let me check"
350           ]
351         },
352         "check_time": {
353           "default": [
354             "one moment please",
355             "let me check"
356           ]
357         },
358         "wait_for_user": {
359           "default": [
360             "one moment please",
361             "let me check"
362           ]
363         },
364         "wait_seconds": {
365           "default": [
366             "one moment please",
367             "let me check"
368           ]
369         },
370         "adjust_response_latency": {
371           "default": [
372             "one moment please",
373             "let me check"
374           ]
375         },
376         "next_step": {
377           "default": [
378             "one moment please",
379             "let me check"
380           ]
381         },
382         "change_context": {
383           "default": [
384             "one moment please",
385             "let me check"
386           ]
387         },
388         "get_visual_input": {
389           "default": [
390             "one moment please",
391             "let me check"
392           ]
393         },
394         "get_ideal_strategy": {
395           "default": [
396             "one moment please",
397             "let me check"
398           ]
399         }
400       }
401     }
402   }
403 }

Updates an AI Agent by ID

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Voice, Messaging, Fax, or Video.

Learn more about API scopes.

Updates an AI Agent by ID #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_, _Messaging_, _Fax_, or _Video_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space).

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

SignalWire Basic Authentication using Project ID and API Token. The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password. Example: ``` Authorization: Basic base64(project_id:token) ```

Path parameters

idstringRequiredformat: "uuid"

Unique ID of an AI Agent.

Request

This endpoint expects an object.

global_dataobjectOptional

A key-value object for storing data that persists throughout the AI session. Can be set initially in the SWML script or modified during the conversation using the set_global_data action. The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g. ${global_data.property_name}).

hintslist of strings or objectsOptional

Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately.

languageslist of objectsOptional

An array of JSON objects defining supported languages in the conversation.

paramsobjectOptional

A JSON object containing parameters as key-value pairs.

post_promptobjectOptional

The final set of instructions and configuration settings to send to the agent.

post_prompt_urlstringOptionalformat: "uri"

The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of username:password@url.

pronouncelist of objectsOptional

An array of JSON objects to clarify the AI's pronunciation of words or expressions.

promptobjectOptional

Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios. It is recommended to write prompts using markdown formatting.

SWAIGobjectOptional

An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue.

agent_idstringOptionalformat: "uuid"

Unique ID of an AI Agent.

namestringOptional

Name of the AI Agent.

Response

The request has succeeded.

idstringformat: "uuid"

Unique ID of the AIAgent.

project_idstringformat: "uuid"

Unique ID of the Project.

display_namestring

Display name of the AIAgent Fabric Resource

typeenum

Type of the Fabric Resource

Allowed values:

created_atdatetime

Date and time when the resource was created.

updated_atdatetime

Date and time when the resource was updated.

ai_agentobject

AIAgent data.

Errors

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error