Skip to main content

Update AI Agent

PATCH 
/resources/ai_agents/:id

Updates an AI Agent by ID

Request​

Path Parameters

    id uuidrequired

    Unique ID of an AI Agent.

Body

required

    name string

    Name of the AI Agent.

    Example: My AI Agent

    prompt

    object

    text string

    The instructions to send to the agent.

    Example: Prompt text
    temperature number

    Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random.

    Possible values: <= 1.5

    top_p number

    Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random.

    Possible values: <= 1

    confidence number

    Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives.

    Possible values: <= 1

    presence_penalty number

    Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics.

    Possible values: >= -2 and <= 2

    frequency_penalty number

    Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim.

    Possible values: >= -2 and <= 2

    contexts

    object

    An object that defines the context steps for the AI. The context steps are used to define the flow of the conversation. Every context object requires a default key, which is the default context to use at the beginning of the conversation. Additionally, more context steps can be defined as any other key in the object.

    default

    object

    The default context to use at the beginning of the conversation. Additional context steps can be defined as any other key in the object.

    steps

    object[]

    An array of objects that define the steps in the context. These steps are used to define the flow of the conversation.

  • Array [

    • anyOf

    name stringrequired

    The name of the step. The name must be unique within the context. The name is used for referencing the step in the context.

    Example: Take Pizza order
    text stringrequired

    The prompt or instructions given to the AI at this step.

    Example: Your name is Franklin and you are taking orders for Franklin's Pizza.
    step_criteria string

    The conditions that must be met for the conversation to proceed to the next step. If a condition is not met, the conversation will not proceed to the next step. It's highly recommended you create a custom criteria for the step to get the intended behavior.

    Example: Customer wants to order Pizza
    functions string[]

    An array of SWAIG.functions that can be executed from this step.

    Example: ["Take Order","Confirm Order","Confirm Address"]
    valid_contexts string[]

    An array of valid contexts that the conversation can transition to from this step.

    Example: ["Place Order","Confirm Order"]
    skip_user_turn boolean

    A boolean value that, when true, will skip the user's turn to respond in the conversation and proceed to the next step.

    end boolean

    A boolean value that, when true, will end the contexts conversation and transition to a normal interaction.

  • ]

    • property name*

    ContextSteps object

    steps

    object[]

    An array of objects that define the steps in the context. These steps are used to define the flow of the conversation.

  • Array [

    • anyOf

    name stringrequired

    The name of the step. The name must be unique within the context. The name is used for referencing the step in the context.

    Example: Take Pizza order
    text stringrequired

    The prompt or instructions given to the AI at this step.

    Example: Your name is Franklin and you are taking orders for Franklin's Pizza.
    step_criteria string

    The conditions that must be met for the conversation to proceed to the next step. If a condition is not met, the conversation will not proceed to the next step. It's highly recommended you create a custom criteria for the step to get the intended behavior.

    Example: Customer wants to order Pizza
    functions string[]

    An array of SWAIG.functions that can be executed from this step.

    Example: ["Take Order","Confirm Order","Confirm Address"]
    valid_contexts string[]

    An array of valid contexts that the conversation can transition to from this step.

    Example: ["Place Order","Confirm Order"]
    skip_user_turn boolean

    A boolean value that, when true, will skip the user's turn to respond in the conversation and proceed to the next step.

    end boolean

    A boolean value that, when true, will end the contexts conversation and transition to a normal interaction.

  • ]

    • post_prompt

    object

    text string

    The instructions to send to the agent.

    Example: Prompt text
    temperature number

    Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random.

    Possible values: <= 1.5

    top_p number

    Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random.

    Possible values: <= 1

    confidence number

    Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives.

    Possible values: <= 1

    presence_penalty number

    Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics.

    Possible values: >= -2 and <= 2

    frequency_penalty number

    Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim.

    Possible values: >= -2 and <= 2

    params

    object

    acknowledge_interruptions boolean

    Instructs the agent to acknowledge crosstalk and confirm user input when the user speaks over the agent.

    ai_volume integer

    Adjust the volume of the AI. Allowed values from -50 - 50.

    Possible values: >= -50 and <= 50

    attention_timeout

    object

    Possible values: >= 10000 and <= 600000

    Amount of time, in ms, to wait before prompting the user to respond. Allowed values from 10,000 - 600,000. Set to 0 to disable.

    anyOf

    integer

    attention_timeout_prompt string

    A custom prompt that is fed into the AI when the attention_timeout is reached.

    Example: Ask if the user can listen to you or they need more time to respond
    background_file uri

    URL of audio file to play in the background while AI plays in foreground.

    Example: https://audiourl.com
    background_file_loops integernullable

    Maximum number of times to loop playing the background file. undefined means loop indefinitely.

    Example: 5
    background_file_volume integer

    Defines background_file volume within a range of -50 to 50.

    Possible values: >= -50 and <= 50

    barge_match_string string

    Takes a string, including a regular expression, defining barge behavior. For example, this param can direct the AI to stop when the word 'hippopotomus' is input.

    Example: Cancel order
    barge_min_words integer

    Defines the number of words that must be input before triggering barge behavior, in a range of 1-99.

    Possible values: >= 1 and <= 99

    conscience string

    Sets the prompt which binds the agent to its purpose.

    Example: Place an order
    conversation_id string

    Used by check_for_input and save_conversation to identify an individual conversation.

    Example: Converation ID
    debug_webhook_level integer

    Enables debugging to the set URL. Allowed values from 0 - 1.

    Possible values: <= 1

    debug_webhook_url uri

    Each interaction between the AI and end user is posted in real time to the established URL.

    Example: https://example.com
    direction Direction enum (string)[]

    Forces the direction of the call to the assistant. Valid values are inbound and outbound.

    Possible values: [inbound, outbound]

    digit_termiantors string

    DTMF digit, as a string, to signal the end of input (ex: '#')

    Example: #
    digit_timeout integer

    Time, in ms, at the end of digit input to detect end of input. Allowed values from 250 - 10,000.

    Possible values: >= 250 and <= 10000

    end_of_speech_timeout integer

    Amount of silence, in ms, at the end of an utterance to detect end of speech. Allowed values from 250 - 10,000.

    Possible values: >= 250 and <= 10000

    eleven_labs_stability number

    The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice.

    eleven_labs_similarity number

    The similarity slider dictates how closely the AI should adhere to the original voice when attempting to replicate it. The higher the similarity, the closer the AI will sound to the original voice.

    energy_level number

    Amount of energy necessary for bot to hear you (in dB). Allowed values from 0.0 - 100.0.

    Possible values: <= 100

    hold_music uri

    A URL for the hold music to play, accepting WAV, mp3, and FreeSWITCH tone_stream.

    Example: https://holdmusic.com
    hold_on_process boolean

    Enables hold music during SWAIG processing.

    inactivity_timeout integer

    Amount of time, in ms, to wait before exiting the app due to inactivity. Allowed values from 10,000 - 3,600,000.

    Possible values: >= 10000 and <= 3600000

    input_poll_freq string

    Check for input function with check_for_input. Example use case: Feeding an inbound SMS to AI on a voice call, eg., for collecting an email address or other complex information.

    interrupt_on_noise boolean

    When enabled, barges agent upon any sound interruption longer than 1 second.

    interrupt_prompt string

    Provide a prompt for the agent to handle crosstalk.

    Example: Inform user that you can't hear anything
    languages_enabled boolean

    Allows multilingualism when true.

    local_tz string

    The local timezone setting for the AI. Value should use IANA TZ ID

    Example: America/Ensenada
    outbound_attention_timeout integer

    Sets a time duration for the outbound call recipient to respond to the AI agent before timeout, in a range from 10000 to 600000.

    Possible values: >= 10000 and <= 600000

    save_conversation boolean

    Send a summary of the conversation after the call ends. This requires a post_url to be set in the ai parameters and the conversation_id defined below. This eliminates the need for a post_prompt in the ai parameters.

    swaig_allow_settings boolean

    Allows tweaking any of the indicated settings, such as barge_match_string, using the returned SWML from the SWAIG function.

    swaig_allow_swml boolean

    Allows your SWAIG to return SWML to be executed.

    swaig_post_conversation boolean

    Post entire conversation to any SWAIG call.

    transfer_summary boolean

    Pass a summary of a conversation from one AI agent to another. For example, transfer a call summary between support agents in two departments.

    verbose_logs boolean

    Enable verbose logging.

    wait_for_user boolean

    When false, AI agent will initialize dialogue after call is setup. When true, agent will wait for the user to speak first.

    pronounce

    object[]

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

  • Array [

    • replace stringrequired

    The expression to replace.

    Example: pizza
    with stringrequired

    The phonetic spelling of the expression.

    Example: pissa
    ignore_case boolean

    Whether the pronunciation replacement should ignore case.

  • ]

    • hints string[]

    An array of hints (as strings) to provide context to the dialogue.

    Example: ["One Hint","Two Hint"]
    languages object[]

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

    SWAIG

    object[]

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

  • Array [

    • defaults

    object

    web_hook_url string

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

    Example: username:password@https://example.com
    native_functions native_functions (string)[]

    Prebuilt functions the AI agent is able to call from this list of available native functions

    Possible values: [check_time, wait_seconds]

    includes

    object[]

    An array of objects to include remote function signatures. The object fields are url to specify where the remote functions are defined and functions which is an array of the function names as strings.

  • Array [

    • functions string[]required

    Remote functions to fetch and include in your AI application.

    Example: ["transfer call","notify kitchen"]
    url stringrequired

    URL to fetch remote functions and include in your AI application. Authentication can also be set in the url in the format of username:password@url.

    Example: username:password@https://example.com

    meta_data

    object

    property name* any

  • ]

    • functions

    object[]

    An array of JSON objects to define functions that can be executed during the interaction with the AI. Default is not set. The fields of this object are the six following.

  • Array [

    • function stringrequired

    A unique name for the function. For example, 'get_weather'.

    Example: get_weather
    description stringrequired

    A description of the context and purpose of the function, to explain to the agent when to use it.

    Example: Get the weather information

    parameters

    object

    type stringrequired

    The type of argument the AI is passing to the function. Possible values are 'string' and 'object'.

    Possible values: [object]

    properties

    object

    required

    An object containing the property definitions that are passed to the function.

    A property definition is a valid JSON schema type with dynamic property names, where:

    • Keys: User-defined strings, that set the property names.

    • Values: A valid property type, which can be one of the following: string, integer, number, boolean, array, object, or null.

    property name*

    Function Parameters Type Union

    oneOf

    Base interface for all property types

    description string

    A description of the property.

    Example: Property description
    nullable boolean

    Whether the property can be null.

    type stringrequired

    The type of parameter(s) the AI is passing to the function.

    Possible values: [string]

    enum string[]

    An array of strings that are the possible values

    Example: ["value1","value2","value3"]
    default string

    The default string value

    Example: default value
    pattern string

    Regular expression pattern

    Example: ^[a-zA-Z0-9_.-]*$
    format StringFormat (string)

    String format (email, date-time, etc.)

    Possible values: [date_time, time, date, duration, email, hostname, ipv4, ipv6, uri, uuid]

    required string[]

    An array of required property names from the properties object.

    Example: ["name1","name2"]
    active boolean

    Whether the function is active. Default is true.

    meta_data

    object

    A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML set_meta_data action. This data can be referenced locally to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string. Default is not set.

    property name* any

    A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML set_meta_data action. This data can be referenced locally to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string. Default is not set.

    meta_data_token string

    Scoping token for meta_data. If not supplied, metadata will be scoped to function's web_hook_url. Default is set by SignalWire.

    data_map

    object

    oneOf

    output

    object

    required

    An object that defines the response or action to be taken when the webhook is successfully triggered.

    response stringrequired

    A static response text or message returned to the AI agents context.

    Example: Order placed

    action

    object[]

    A list of actions to be performed upon matching.

  • Array [

    • anyOf

    context_switch

    object

    required

    A JSON object containing the context to switch to. Default is not set.

    system_prompt stringrequired

    The instructions to send to the agent. Default is not set.

    consolidate boolean

    Whether to consolidate the context. Default is false.

    user_prompt string

    A string serving as simulated user input for the AI Agent. During a context_switch in the AI's prompt, the user_prompt offers the AI pre-established context or guidance. Default is not set

  • ]

    • web_hook_url string

    Function-specific URL to send status callbacks and reports to. Takes precedence over a default setting. Authentication can also be set in the url in the format of username:password@url.

    Example: username:password:https://music.com
    wait_file uri

    A file to play while the function is running. wait_file_loops can specify the amount of times that files should continously play. Default is not set.

    Example: https://music.com

    wait_file_loops

    object

    The number of times to loop playing the file. Default is not set.

    anyOf

    integer

  • ]

  • ]

Responses​

The request has succeeded.

Schema

    name stringrequired

    Name of the AI Agent.

    Example: My AI Agent

    prompt

    object

    text stringrequired

    The instructions to send to the agent.

    Example: Prompt text
    temperature number

    Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random.

    Possible values: <= 1.5

    top_p number

    Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random.

    Possible values: <= 1

    confidence number

    Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives.

    Possible values: <= 1

    presence_penalty number

    Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics.

    Possible values: >= -2 and <= 2

    frequency_penalty number

    Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim.

    Possible values: >= -2 and <= 2

    contexts

    object

    An object that defines the context steps for the AI. The context steps are used to define the flow of the conversation. Every context object requires a default key, which is the default context to use at the beginning of the conversation. Additionally, more context steps can be defined as any other key in the object.

    default

    object

    required

    The default context to use at the beginning of the conversation. Additional context steps can be defined as any other key in the object.

    steps

    object[]

    required

    An array of objects that define the steps in the context. These steps are used to define the flow of the conversation.

  • Array [

    • anyOf

    name stringrequired

    The name of the step. The name must be unique within the context. The name is used for referencing the step in the context.

    Example: Take Pizza order
    text stringrequired

    The prompt or instructions given to the AI at this step.

    Example: Your name is Franklin and you are taking orders for Franklin's Pizza.
    step_criteria string

    The conditions that must be met for the conversation to proceed to the next step. If a condition is not met, the conversation will not proceed to the next step. It's highly recommended you create a custom criteria for the step to get the intended behavior.

    Example: Customer wants to order Pizza
    functions string[]

    An array of SWAIG.functions that can be executed from this step.

    Example: ["Take Order","Confirm Order","Confirm Address"]
    valid_contexts string[]

    An array of valid contexts that the conversation can transition to from this step.

    Example: ["Place Order","Confirm Order"]
    skip_user_turn boolean

    A boolean value that, when true, will skip the user's turn to respond in the conversation and proceed to the next step.

    end boolean

    A boolean value that, when true, will end the contexts conversation and transition to a normal interaction.

  • ]

    • property name*

    ContextSteps object

    steps

    object[]

    required

    An array of objects that define the steps in the context. These steps are used to define the flow of the conversation.

  • Array [

    • anyOf

    name stringrequired

    The name of the step. The name must be unique within the context. The name is used for referencing the step in the context.

    Example: Take Pizza order
    text stringrequired

    The prompt or instructions given to the AI at this step.

    Example: Your name is Franklin and you are taking orders for Franklin's Pizza.
    step_criteria string

    The conditions that must be met for the conversation to proceed to the next step. If a condition is not met, the conversation will not proceed to the next step. It's highly recommended you create a custom criteria for the step to get the intended behavior.

    Example: Customer wants to order Pizza
    functions string[]

    An array of SWAIG.functions that can be executed from this step.

    Example: ["Take Order","Confirm Order","Confirm Address"]
    valid_contexts string[]

    An array of valid contexts that the conversation can transition to from this step.

    Example: ["Place Order","Confirm Order"]
    skip_user_turn boolean

    A boolean value that, when true, will skip the user's turn to respond in the conversation and proceed to the next step.

    end boolean

    A boolean value that, when true, will end the contexts conversation and transition to a normal interaction.

  • ]

    • post_prompt

    object

    text stringrequired

    The instructions to send to the agent.

    Example: Prompt text
    temperature number

    Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random.

    Possible values: <= 1.5

    top_p number

    Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random.

    Possible values: <= 1

    confidence number

    Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives.

    Possible values: <= 1

    presence_penalty number

    Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics.

    Possible values: >= -2 and <= 2

    frequency_penalty number

    Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim.

    Possible values: >= -2 and <= 2

    params

    object

    acknowledge_interruptions boolean

    Instructs the agent to acknowledge crosstalk and confirm user input when the user speaks over the agent.

    ai_volume integer

    Adjust the volume of the AI. Allowed values from -50 - 50.

    Possible values: >= -50 and <= 50

    attention_timeout

    object

    Possible values: >= 10000 and <= 600000

    Amount of time, in ms, to wait before prompting the user to respond. Allowed values from 10,000 - 600,000. Set to 0 to disable.

    anyOf

    integer

    attention_timeout_prompt string

    A custom prompt that is fed into the AI when the attention_timeout is reached.

    Example: Ask if the user can listen to you or they need more time to respond
    background_file uri

    URL of audio file to play in the background while AI plays in foreground.

    Example: https://audiourl.com
    background_file_loops integernullable

    Maximum number of times to loop playing the background file. undefined means loop indefinitely.

    Example: 5
    background_file_volume integer

    Defines background_file volume within a range of -50 to 50.

    Possible values: >= -50 and <= 50

    barge_match_string string

    Takes a string, including a regular expression, defining barge behavior. For example, this param can direct the AI to stop when the word 'hippopotomus' is input.

    Example: Cancel order
    barge_min_words integer

    Defines the number of words that must be input before triggering barge behavior, in a range of 1-99.

    Possible values: >= 1 and <= 99

    conscience string

    Sets the prompt which binds the agent to its purpose.

    Example: Place an order
    conversation_id string

    Used by check_for_input and save_conversation to identify an individual conversation.

    Example: Converation ID
    debug_webhook_level integer

    Enables debugging to the set URL. Allowed values from 0 - 1.

    Possible values: <= 1

    debug_webhook_url uri

    Each interaction between the AI and end user is posted in real time to the established URL.

    Example: https://example.com
    direction Direction enum (string)[]

    Forces the direction of the call to the assistant. Valid values are inbound and outbound.

    Possible values: [inbound, outbound]

    digit_termiantors string

    DTMF digit, as a string, to signal the end of input (ex: '#')

    Example: #
    digit_timeout integer

    Time, in ms, at the end of digit input to detect end of input. Allowed values from 250 - 10,000.

    Possible values: >= 250 and <= 10000

    end_of_speech_timeout integer

    Amount of silence, in ms, at the end of an utterance to detect end of speech. Allowed values from 250 - 10,000.

    Possible values: >= 250 and <= 10000

    eleven_labs_stability number

    The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice.

    eleven_labs_similarity number

    The similarity slider dictates how closely the AI should adhere to the original voice when attempting to replicate it. The higher the similarity, the closer the AI will sound to the original voice.

    energy_level number

    Amount of energy necessary for bot to hear you (in dB). Allowed values from 0.0 - 100.0.

    Possible values: <= 100

    hold_music uri

    A URL for the hold music to play, accepting WAV, mp3, and FreeSWITCH tone_stream.

    Example: https://holdmusic.com
    hold_on_process boolean

    Enables hold music during SWAIG processing.

    inactivity_timeout integer

    Amount of time, in ms, to wait before exiting the app due to inactivity. Allowed values from 10,000 - 3,600,000.

    Possible values: >= 10000 and <= 3600000

    input_poll_freq string

    Check for input function with check_for_input. Example use case: Feeding an inbound SMS to AI on a voice call, eg., for collecting an email address or other complex information.

    interrupt_on_noise boolean

    When enabled, barges agent upon any sound interruption longer than 1 second.

    interrupt_prompt string

    Provide a prompt for the agent to handle crosstalk.

    Example: Inform user that you can't hear anything
    languages_enabled boolean

    Allows multilingualism when true.

    local_tz string

    The local timezone setting for the AI. Value should use IANA TZ ID

    Example: America/Ensenada
    outbound_attention_timeout integer

    Sets a time duration for the outbound call recipient to respond to the AI agent before timeout, in a range from 10000 to 600000.

    Possible values: >= 10000 and <= 600000

    save_conversation boolean

    Send a summary of the conversation after the call ends. This requires a post_url to be set in the ai parameters and the conversation_id defined below. This eliminates the need for a post_prompt in the ai parameters.

    swaig_allow_settings boolean

    Allows tweaking any of the indicated settings, such as barge_match_string, using the returned SWML from the SWAIG function.

    swaig_allow_swml boolean

    Allows your SWAIG to return SWML to be executed.

    swaig_post_conversation boolean

    Post entire conversation to any SWAIG call.

    transfer_summary boolean

    Pass a summary of a conversation from one AI agent to another. For example, transfer a call summary between support agents in two departments.

    verbose_logs boolean

    Enable verbose logging.

    wait_for_user boolean

    When false, AI agent will initialize dialogue after call is setup. When true, agent will wait for the user to speak first.

    pronounce

    object[]

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

  • Array [

    • replace stringrequired

    The expression to replace.

    Example: pizza
    with stringrequired

    The phonetic spelling of the expression.

    Example: pissa
    ignore_case boolean

    Whether the pronunciation replacement should ignore case.

  • ]

    • hints string[]

    An array of hints (as strings) to provide context to the dialogue.

    Example: ["One Hint","Two Hint"]
    languages object[]

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

    SWAIG

    object[]

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

  • Array [

    • defaults

    object

    web_hook_url string

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

    Example: username:password@https://example.com
    native_functions native_functions (string)[]

    Prebuilt functions the AI agent is able to call from this list of available native functions

    Possible values: [check_time, wait_seconds]

    includes

    object[]

    An array of objects to include remote function signatures. The object fields are url to specify where the remote functions are defined and functions which is an array of the function names as strings.

  • Array [

    • functions string[]required

    Remote functions to fetch and include in your AI application.

    Example: ["transfer call","notify kitchen"]
    url stringrequired

    URL to fetch remote functions and include in your AI application. Authentication can also be set in the url in the format of username:password@url.

    Example: username:password@https://example.com

    meta_data

    object

    property name* any

  • ]

    • functions

    object[]

    An array of JSON objects to define functions that can be executed during the interaction with the AI. Default is not set. The fields of this object are the six following.

  • Array [

    • function stringrequired

    A unique name for the function. For example, 'get_weather'.

    Example: get_weather
    description stringrequired

    A description of the context and purpose of the function, to explain to the agent when to use it.

    Example: Get the weather information

    parameters

    object

    type stringrequired

    The type of argument the AI is passing to the function. Possible values are 'string' and 'object'.

    Possible values: [object]

    properties

    object

    required

    An object containing the property definitions that are passed to the function.

    A property definition is a valid JSON schema type with dynamic property names, where:

    • Keys: User-defined strings, that set the property names.

    • Values: A valid property type, which can be one of the following: string, integer, number, boolean, array, object, or null.

    property name*

    Function Parameters Type Union

    oneOf

    Base interface for all property types

    description string

    A description of the property.

    Example: Property description
    nullable boolean

    Whether the property can be null.

    type stringrequired

    The type of parameter(s) the AI is passing to the function.

    Possible values: [string]

    enum string[]

    An array of strings that are the possible values

    Example: ["value1","value2","value3"]
    default string

    The default string value

    Example: default value
    pattern string

    Regular expression pattern

    Example: ^[a-zA-Z0-9_.-]*$
    format StringFormat (string)

    String format (email, date-time, etc.)

    Possible values: [date_time, time, date, duration, email, hostname, ipv4, ipv6, uri, uuid]

    required string[]

    An array of required property names from the properties object.

    Example: ["name1","name2"]
    active boolean

    Whether the function is active. Default is true.

    meta_data

    object

    A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML set_meta_data action. This data can be referenced locally to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string. Default is not set.

    property name* any

    A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML set_meta_data action. This data can be referenced locally to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string. Default is not set.

    meta_data_token string

    Scoping token for meta_data. If not supplied, metadata will be scoped to function's web_hook_url. Default is set by SignalWire.

    data_map

    object

    oneOf

    output

    object

    required

    An object that defines the response or action to be taken when the webhook is successfully triggered.

    response stringrequired

    A static response text or message returned to the AI agents context.

    Example: Order placed

    action

    object[]

    A list of actions to be performed upon matching.

  • Array [

    • anyOf

    context_switch

    object

    required

    A JSON object containing the context to switch to. Default is not set.

    system_prompt stringrequired

    The instructions to send to the agent. Default is not set.

    consolidate boolean

    Whether to consolidate the context. Default is false.

    user_prompt string

    A string serving as simulated user input for the AI Agent. During a context_switch in the AI's prompt, the user_prompt offers the AI pre-established context or guidance. Default is not set

  • ]

    • web_hook_url string

    Function-specific URL to send status callbacks and reports to. Takes precedence over a default setting. Authentication can also be set in the url in the format of username:password@url.

    Example: username:password:https://music.com
    wait_file uri

    A file to play while the function is running. wait_file_loops can specify the amount of times that files should continously play. Default is not set.

    Example: https://music.com

    wait_file_loops

    object

    The number of times to loop playing the file. Default is not set.

    anyOf

    integer

  • ]

  • ]