Skip to main content

<AI> noun

<Connect> verb's <AI> noun allows the connection to a virtual AI agent. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <AI postPromptURL="https://webhook.site/10d74766-3782-414d-8d40-614dacdaf140">
      <Prompt confidence="0.6">
        You are a recipe bot. You can help me cook any recipe, step by step.
      </Prompt>
      <PostPrompt confidence="0.6">
        Summarize the conversation.
      </PostPrompt>
    </AI>
  </Connect>
</Response>

The agent has the ability to perform a number of actions when needed, for example it can hang up the call or send an SMS to the caller.

<AI> Noun Attributes​

Attribute
engine optionalThe Text-To-Speech engine to use. Default: "gcloud".
voice optionalDefault Text-To-Speech voice to use. Default: "en-US-Neural2-J".
postPromptURL optionalSignalWire will make a POST request to this URL when the conversation terminates. It can include an optional username and password. See below for specified request parameters.
postPromptAuthUser optionalHTTP user to use for the request to postPromptURL. Ignored if a user already appears in the URL.
postPromptAuthPassword optionalHTTP password to use for the request to postPromptURL. Ignored if a password already appears in the URL.
hints optionalA list of words and phrases that a caller is likely to say during a call. This is used to improve speech recognition accuracy.

<Prompt> and <PostPrompt>​

You can specify two prompts: <Prompt> and <PostPrompt>.

Any text inside <Prompt> will be used as the initial prompt for the AI agent (it will remain hidden from the user). You typically use <Prompt> to instruct the agent on who it is, what it should do, and what it knows.

Similarly, any text in <PostPrompt> will be used after the end of the conversation with the agent (it will remain hidden from the user, but the response of the agent will be available in the postPromptURL request). You typically use <PostPrompt> to instruct the agent to emit a final message that you'll consume from your API (e.g., summarizing the conversation, or retrieving a specific entity — such as a customer id — from the conversation).

Both <Prompt> and <PostPrompt> accept the following attributes:

Attribute
temperature optionalWhat statistical sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
topP optionalAn alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. Accepts values between 0 and 1. We recommend setting temperature=1 when altering this parameter.
confidence optionalConfidence threshold, between 0 and 1, needed to consider the current utterance as end of speech. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives.
bargeConfidence optionalConfidence threshold, between 0 and 1, needed to consider the current utterance as end of speech. This only applies when the user is speaking over the AI agent. Decreasing this value will reduce the time it takes the agent to stop, but may introduce false positives.
presencePenalty optionalNumber between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
frequencyPenalty optionalNumber between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.

The default values change depending on the prompt type:

AttributeDefault for <Prompt>Default for <PostPrompt>
temperature0.30.0
topP1.01.0
confidence0.60.6
bargeConfidence0.30.0
presencePenalty0.10.0
frequencyPenalty0.10.0

Request parameters for the postPromptURL URL​

The postPromptURL request contains the following parameters:

Parameter
content_type stringType of content. Its value is "Conversation/Log".
app_name stringName of the application that originated this request.
action stringAction that this message is about. Its value is "post_conversation".
call_log objectThe complete log of the call, as a JSON object.
post_prompt_data objectThe answer of the AI agent to the message in <PostPrompt>. See below for the fields within this object.
post_prompt_data.parsed objectIf a JSON object is detected within the answer, it is parsed and provided here.
post_prompt_data.raw stringThe raw answer of the AI agent.
post_prompt_data.substituted stringThe answer of the AI agent, excluding any JSON.

<Languages>​

You can allow the AI agent to speak more than one language using the <Languages> tag. The agent will pick the correct language appropriately. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <AI postPromptURL="https://webhook.site/10d74766-3782-414d-8d40-614dacdaf140">
      <Prompt>You are a translation bot.</Prompt>
      <PostPrompt>Summarize the conversation.</PostPrompt>
      <Languages>
        <Language code="en-US" name="English" voice="en-US-Neural2-J" />
        <Language code="fr-FR" name="French" voice="fr-FR-Neural2-B" />
      </Languages>
    </AI>
  </Connect>
</Response>

Each <Language> tag accepts the following attributes:

Parameter
codeLanguage code. For example, "fr-FR".
nameName of the language. For example, "French".
voiceVoice to use for the language. The engine is the one specified in the <AI>'s engine attribute. For example, "fr-FR-Neural2-B".

Supported Codes and Voices​

You can find the list of supported codes (languages) and voices here

<SWAIG> (SignalWire AI Gateway)​

You can define a set of functions that the AI agent will be able to invoke. Functions allow the agent to perform external actions (e.g., sending an SMS) or gathering data (e.g., the current weather in a specific city). For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <AI postPromptURL="https://webhook.site/10d74766-3782-414d-8d40-614dacdaf140">
      <Prompt>You are a general-purpose AI bot.</Prompt>
      <PostPrompt>Summarize the conversation.</PostPrompt>
      <SWAIG>
        <Defaults webHookURL="https://example.com/commands.cgi" />
        <Function name="get_weather" argument="The location or name of the city"
		              purpose="To indicate to the user what the current weather is in a provided location.">
          <metavar1>Value1</metavar1>
        </Function>
        <Function name="get_world_time" argument="The name of the city to check the time"
		              purpose="Get the time in a specific location" />
      </SWAIG>
    </AI>
  </Connect>
</Response>

In the example above, when needed, the agent will be able to invoke the get_weather or get_world_time functions. At each invocation, a request will be made to the webHookURL, which should respond with the result of the function invocation (for example, "Sunny").

<Defaults>​

In <SWAIG>, use the <Defaults> tag to set default parameters for all function definitions. The allowed parameters are:

Parameter
webHookURL stringThe webhook to invoke when a function is called.
webHookAuthUser stringUsername for webHookURL. Ignored if a username is already provided in webHookURL.
webHookAuthPass stringPassword for webHookURL. Ignored if a password is already provided in webHookURL.

In the content of the tag you can specify default metadata too, for example:

<!-- ... -->
  <SWAIG>
    <Defaults webHookURL="https://example.com/commands.cgi">
      <metavar1>Value1</metavar1>
      <metavar2>Value2</metavar2>
    </Defaults>
  </SWAIG>
<!-- ... -->

<Function>​

In <SWAIG>, use the <Function> tag to define a function that the AI agent will be able to invoke when needed. The allowed parameters are:

Parameter
nameA unique name for the function. For example, "get_weather".
argumentA description of the input to the function. For example, "The location or name of the city".
purposeA description of the context and purpose of the function, to explain the agent when to use it.
webHookURL stringThe webhook to invoke when the function is called. Request parameters are sent to the webook.
webHookAuthUser stringUsername for webHookURL. Ignored if a username is already provided in webHookURL.
webHookAuthPass stringPassword for webHookURL. Ignored if a password is already provided in webHookURL.

In the content of the tag you can specify metadata too, for example:

<!-- ... -->
  <SWAIG>
    <Function name="get_weather" argument="The location or name of the city"
              purpose="To indicate to the user what the current weather is in a provided location.">
      <metavar1>Value1</metavar1>
      <metavar2>Value2</metavar2>
    </Function>
  </SWAIG>
<!-- ... -->

Request parameters for function's webHookURL URL​

The webHookURL request contains the following parameters:

Parameter
app_name stringName of the application that originated this request.
content_type stringType of content. Its value is "Conversation/SWAIG-function".
function stringName of the function that was invoked.
meta_data objectA JSON object containing any metadata, as a key-value map.
call_log objectThe complete log of the call, as a JSON object.
argument objectThe actual argument to the function. See below for the fields within this object.
argument_desc stringThe description of the function that was provided to the agent.
purpose stringThe purpose of the function that was provided to the agent.
argument.parsed objectIf a JSON object is detected within the argument, it is parsed and provided here.
argument.raw stringThe raw argument provided by the AI agent.
argument.substituted stringThe argument provided by the AI agent, excluding any JSON.

You need to answer the request with a JSON object containing the result. For example, if your function was called get_weather, your webhook would check the weather in the requested city using a 3rd party API, and then provide the answer to the agent with the following JSON response:

{
  "response": "It's sunny."
}

Examples​

A Customer Support Agent​

The following agent will help customers troubleshoot the most common problems with their devices. At the end of the conversation, the agent will include in the post_prompt_data field (see request parameters) a token that will indicate whether the troubleshooting was successful ([solved:true] or [solved:false]). You can use the postPromptURL webhook to retrieve this result.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <AI postPromptURL="https://my-application.example.com/my-webhook">
      <Prompt>
        You are a customer support agent for a vacuum cleaner company called "Best Quality Vacuum".
        You are going to help the customer troubleshoot their problem.
        If the vacuum cleaner has lost suction power, the customer needs to empty the container and check for any clogged filter. Filters can be cleaned.
        Sometimes, foreign items can restrict the air flow in the hose. Those can be removed with the help of a long stick.
        If the vacuum does not power on, the customer should check if the battery is charged by pressing the blue button to see the percentage of charge.
        Start by asking the customer what their issue is.
      </Prompt>
      <PostPrompt>
        Did the customer solve the issue? Answer with "true" or "false" in square brackets after the "solved" keyword (e.g, `[solved:true]`).
        Then, summarize the conversation.
      </PostPrompt>
    </AI>
  </Connect>
</Response>

A Voicemail Bot​

The following agent will collect a message from the caller, then will produce a JSON that an application can consume.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <AI postPromptURL="https://my-application.example.com/my-webhook">
      <Prompt>
        You are Franklin's assistant, and your job is to collect messages for him over the phone.
        You can reassure that Franklin will get in touch as soon as possible.
        Collect the user's name and number if you do not already know it from the caller id.
        Start by presenting yourself, then let the contact know that Franklin is not available, then offer to collect a message.
        After collecting the message, do not wait for the user to end the conversation: say good bye and hang up the call.
      </Prompt>
      <PostPrompt>
        Summarize the message as a valid anonymous json object by filling the upper case placeholders in this template:
        { "contact_info": { "name": "CONTACT_NAME", "number": "CONTACT_PHONE" }, "message": "MESSAGE" }
      </PostPrompt>
    </AI>
  </Connect>
</Response>