Skip to main content

Creating a Santa AI with SWML: Engaging in the Spirit of Christmas

Prerequisites​

  • A SignalWire account (sign up for free!)
  • A SignalWire phone number (buy a number if you don't have one)
  • Real-Time Amazon Data API (subscribe to the API)

Overview​

Join SignalWire in getting into the spirit of Christmas with an innovative, serverless, and seasonal application of our new AI Agents! Today we'll build a Santa AI designed to interact with users on the phone and inquire about their Christmas wishes using the powerful and flexible SignalWire Markup Language (SWML).

The Santa AI we'll build together communicates with users over the phone in spoken natural language, powered by OpenAI and Eleven Labs' Text-To-Speech engine, to determine what they want for Christmas. Santa then uses the Real-Time Amazon Data API to search for the top three gifts based on their wishes. Once the user chooses their favorite gift, the Santa AI sends an SMS to the user with a link to the chosen gift.

This helps to create a magical and interactive experience for children, allowing them to communicate their Christmas wishes in a fun and engaging way. It also helps to ease the gift-buying process for parents, as they can get a better idea of what their child wants for Christmas, and then purchase the gift directly from Amazon.

Setup​

To get our AI Santa set up, we will take the following steps:

  1. Sign into your SignalWire Space and navigate to your Dashboard.
  2. Create a new Relay (SWML) Script using the sample script and provided instructions.
  3. Assign a phone number to the Relay (SWML) Script.

We'll explain each of these steps in detail throughout the article. Follow along, and don't hesitate to reach out if you have questions or run into issues!

The Santa AI SWML Breakdown​

The AI Section​

The heart of our Santa AI lies in its AI section. Here, specific parameters like prompt, post_prompt_url params, languages, and SWAIG (SignalWire AI Gateway) are defined. These parameters are critical to the Santa AI experience, as they define the AI's personality, languages, and capabilities.

version: 1.0.0
sections:
  main:
  - ai:
      prompt:
        ...
      post_prompt_url: Put Your Personal Post Prompt Webhook Here
      params:
        ...
      languages:
        ...
      SWAIG:
        ...

Prompt and Post Prompt​

The prompt parameter is used to define the AI's purpose and his personality traits. Within prompt also define the AI's top_p, temperature and text parameters, which are used to control the AI's response.

The top_p parameter defines the probability of the AI's response, while the temperature parameter defines the randomness of the AI's response.

The prompts text parameter uses Markdown to format the text. This allows us to break down the conversation into steps using Markdown headers, making it easier for the Santa AI to follow and understand the conversation flow. Here, we are using the ### header to define the steps of the conversation. We include a brief description of each step, as well as the function that will be used during that step. In each step, we include specific instructions for the AI to following while on that current step, such as letting the user they can only choose one gift after already choosing a gift.

The post_prompt_url parameter is used to define the webhook that will be called after the AI's conversation is complete. This webhook will be sent the logs of the conversation which will contain a transcript of the conversation and SWAIG function calls. For testing purposes, it is recommended to use Webhook.site to view the post prompt logs. This site will provide a unique URL that can be used as the post_prompt_url.

version: 1.0.0
sections:
  main:
  - ai:
      prompt:
        top_p: 0.3
        temperature: 0.6
        text: |-
          Greet the user in a festive manner.
          Engage with a child as Santa Claus, spreading Christmas joy.
          In a jolly Santa voice, ask one cute, festive question at a time to discover what the children want for Christmas.
          ### Step 1 Ask them what they want for christmas.
          ### Step 2 Use the present_lookup function to search for the requested gift and provide a summary.
          If the presents summary is empty, explain there's an issue with the elves at Amazon and suggest trying later and then hangup.
          ### Step 3 Ask the child to pick one out of the top three presents listed in the presents summary.
          If the user wants a different present, acknowledge they want a different present and go back to Step 1.
          ### Step 4 Ensure the chosen present is from the present summary.
          If multiple presents are selected, request the child to choose only one.
          ### Step 5 Once confirmed, use the send_present function to finalize the gift choice.
          ### Step 6 Continue the conversation, keeping it playful and entertaining.
          If another present is requested, gently remind them that only one gift can be chosen.
      post_prompt_url: Post Prompt Webhook Here

Languages and Voices​

This section covers how we are using the elevenlabs engine to use Santa's voice as the default voice.

Santa's voice is defined in the voice parameter, which is set to gvU4yEv29ZpMc9IXoZcd for both languages. We use the code parameter to define the language code, which is en-US for English. The fillers parameter is used to define the filler words Santa uses to make his speech more natural. These fillers are randomly selected and inserted into Santa's speech, making it more realistic.

languages:
  - name: English
    code: en-US
    voice: gvU4yEv29ZpMc9IXoZcd
    engine: elevenlabs
    fillers:
      - one moment please,
      - uhh ha,
      - aah ha,
      - hmm...
      - let's see,

Params​

The params parameter is used to define the AI's eleven_labs_stability and eleven_labs_similarity parameters.

The eleven_labs_stability parameter is used to define the stability of the AI's voice, while the eleven_labs_similarity parameter is used to define the similarity of the AI's voice to the voice that is defined in the voice parameter. This allows us to control the AI's voice and make it more realistic and as close to Santa's voice as possible.

You can learn more about these settings here: Eleven Labs Documentation.

params:
  eleven_labs_stability: 0.1
  eleven_labs_similarity: 0.25

SWAIG: SignalWire AI Gateway​

SWAIG is an essential component of our Santa AI, housing the critical functions that make the magic happen. The two functions we will be focusing on are present_lookup and send_present. These functions are responsible for searching Amazon for the top three gifts based on a user's input and sending an SMS to the users phone with a link to the chosen gift, respectively. Additionally, the AI will also be using native_functions which are functions that are built into the AI and do not require any setup.

native_functions​

  • check_time - Checks the time of day and returns a string of the time of day to the AI to refer to during the conversation.
SWAIG:
  native_functions:
  - check_time

present_lookup Function​

The present_lookup function plays a crucial role in the Santa AI experience. It enables Santa to search and provide three gifts as options for the user to choose from. based on a user's input. When the present_lookup function is called, it will make a GET request to the Real-Time Amazon Data API to search for gifts based on the user's input. The API will return a payload containing the search results, which will be used to generate a summary of the top three gifts.

This function adds an element of realism to the interaction, as it mimics Santa's ability to know all the best gifts and where to find them.

SWAIG:
  functions:
  - function: present_lookup
  meta_data_token: summary
  purpose: To look for presents on Amazon, getting top 3 results.
  argument:
    type: object
    properties:
      query:
        type: string
        description: the present to look up
  data_map:
    webhooks:
    - require_args: query
      error_keys: error
      url: https://real-time-amazon-data.p.rapidapi.com/search?query=%{lc:enc:args.query}&page=1&country=US&category_id=aps
      method: GET
      headers:
        X-RapidAPI-Key: Rapid API Token Here
        X-RapidAPI-Host: real-time-amazon-data.p.rapidapi.com
      foreach:
        input_key: data.products
        output_key: summary
        max: 3
        append: 'title: %{this.product_title} photo: %{this.product_photo}
          url: %{this.product_url}'
      output:
        response: |
          If the present summary is not empty, repeat the titles of the top 3 presents from the summary to the user.
          ### Present Summary:
          %{summary}
        action:
        - toggle_functions:
          - active: true
            function: send_present

Explanation of the present_lookup function:

  • purpose - This parameter is used to describe the purpose of the function.

  • argument - This parameter is used to define the arguments that the function requires.

  • properties - This parameter is used to define the properties of the argument. In this case, the query argument is a string, which represents the present that the user wants to look up.

  • data_map - This parameter is used to define how the function will process the data it receives during the function call.

  • webhooks - This parameter is used to define the webhook that will be called during the function call, and its method, headers, and the data that will be sent to the webhook. In this case, we are using the Real-Time Amazon Data API to search Amazon for the top three gifts based on the user's input.

  • require_args - This parameter is used to define the arguments that are required for the webhook to be called. In this case, the query argument is required for the webhook to be called.

  • error_keys - This parameter is used to define the error keys that will be returned from the webhook. In this case, the error key will be returned if the webhook is not called successfully.

  • method - This parameter is used to define the method that will be used to call the webhook. In this case, we are using the GET method to call the webhook.

  • url - This parameter is used to define the URL of the webhook. In this case, we are calling the Real-Time Amazon Data API to search Amazon for the top three gifts based on the user's input, in a serverless manner. When the request is made, the following parameters will be passed to the API as query strings:

    • query - The search query to look up on Amazon. This will be the present that the user wants to look up.
    • country - The country code of the Amazon domain to search on.
    • category_id - The category ID of the Amazon category to search in.
    • page - The page number of the search results to return.

    The lc:enc: prefix is used to lowercase and encode the argument, which is required for the webhook to be called properly.

  • headers - This parameter is used to define the headers that will be sent to the webhook. The X-RapidAPI-Key header is used to authenticate the webhook using the Rapid API token, while the X-RapidAPI-Host header is used to define the host of the webhook. Make sure to replace the X-RapidAPI-Key header with your Rapid API token and the X-RapidAPI-Host header with the host of the webhook which can be found on the Real-Time Amazon Data API page.

  • foreach - This parameter is used to iterate through the data that is returned from the webhook. In this case, we are iterating through the data.products array that is returned from Real-Time Amazon Data API and then using append to add the title, photo, and url of the first three products to the summary variable.

  • response - This parameter is used to define the response that will be sent to the AI after the function is complete. In this case, we are letting the AI know that we are repeating the top three presents that are stored in the summary variable. If the summary variable is empty, we will let the AI know that there was an issue with the elves at Amazon, and suggest trying again later. This will prevent the Santa AI from sending the user an SMS with a link to a gift that does not exist. This usually happens the Real-Time Amazon Data API fails.

  • output - This parameter is used to define the output of the function. In this case, we are feeding the summary variable to the response parameter, which will be used to summarize the results of the search. This will allow the Santa AI to repeat the top three gifts to the user.

  • action - This parameter is used to define the action that will be taken after the function is complete. In this case, we are using the toggle_functions action to toggle the send_present function active state to true, which will allow the Santa AI to send the chosen gift to the user.

Response Example from present_lookup Function​
{
  "status": "OK",
  "request_id": "4f79fec8-b6d9-4721-b9d6-0d4819ed9786",
  "data": {
    "total_products": 3,
    "country": "US",
    "domain": "www.amazon.com",
    "products": [
      {
        "asin": "B010RWDJOY",
        "product_title": "Nike Performance Cushion Crew Socks with Band (6 Pairs)",
        "product_price": "$25.00",
        "unit_price": "$4.17",
        "unit_count": 6,
        "product_original_price": "$29.90",
        "currency": "USD",
        "product_star_rating": "4.6",
        "product_num_ratings": 15788,
        "product_url": "https://www.amazon.com/dp/B010RWDJOY",
        "product_photo": "https://m.media-amazon.com/images/I/81XwDw-bXpL._AC_SR525,789_FMwebp_QL65_.jpg",
        "product_num_offers": null,
        "product_minimum_offer_price": "$25.00",
        "is_best_seller": false,
        "is_amazon_choice": false,
        "is_prime": true,
        "climate_pledge_friendly": false,
        "sales_volume": "10K+ bought in past month",
        "delivery": "FREE delivery Mon, Feb 5 on $35 of items shipped by AmazonOr fastest delivery Thu, Feb 1"
      },
      {
        "asin": "B07FKDZPZW",
        "product_title": "Nike Unisex Everyday Cushion Crew 3 Pair",
        "product_price": "$14.00",
        "unit_price": "$4.67",
        "unit_count": 3,
        "product_original_price": "$18.99",
        "currency": "USD",
        "product_star_rating": "4.6",
        "product_num_ratings": 24998,
        "product_url": "https://www.amazon.com/dp/B07FKDZPZW",
        "product_photo": "https://m.media-amazon.com/images/I/61LBNRTTxqL._AC_SR525,789_FMwebp_QL65_.jpg",
        "product_num_offers": null,
        "product_minimum_offer_price": "$14.00",
        "is_best_seller": false,
        "is_amazon_choice": false,
        "is_prime": true,
        "climate_pledge_friendly": false,
        "sales_volume": "8K+ bought in past month",
        "delivery": "FREE delivery Sun, Feb 4 on $35 of items shipped by AmazonOr fastest delivery Thu, Feb 1"
      },
      {
        "asin": "B08NMWT76M",
        "product_title": "Nike Womens Club Fleece Jogger Sweatpants",
        "product_price": "$50.00",
        "product_original_price": "$56.24",
        "currency": "USD",
        "product_star_rating": "4.3",
        "product_num_ratings": 1361,
        "product_url": "https://www.amazon.com/dp/B08NMWT76M",
        "product_photo": "https://m.media-amazon.com/images/I/51gvdUQ2I6L._AC_SR525,789_FMwebp_QL65_.jpg",
        "product_num_offers": null,
        "product_minimum_offer_price": "$50.00",
        "is_best_seller": false,
        "is_amazon_choice": false,
        "is_prime": true,
        "climate_pledge_friendly": false,
        "sales_volume": "400+ bought in past month",
        "delivery": "FREE delivery Mon, Feb 5 Or fastest delivery Thu, Feb 1 Prime Try Before You Buy"
      }
    ]
  }
}

send_present Function​

Following the present_lookup function, the child will be asked to choose their preferred gift from the top three gifts that were returned from the present_lookup function. The send_present function will then send an SMS to the user with a link to the chosen gift.

SWAIG:
    function: send_present
    meta_data_token: summary
    purpose: To send an SMS of an Amazon present to the user.
    active: 'false'
    argument:
      type: object
      properties:
        present_title:
          type: string
          description: The title of the present to send to the user.
        present_url:
          type: string
          description: The url of the present to send to the user.
        present_photo:
          type: string
          description: The photo of the present to send to the user.
    data_map:
      expressions:
      - pattern: ".*"
        string: ".*"
        output:
          response: Let the user know that the present will be delivered on
            Christmas.
          action:
          - toggle_functions:
              - active: false
                function: present_lookup
              - active: false
                function: send_present
          - SWML:
              version: 1.0.0
              sections:
                main:
                - send_sms:
                    to_number: "%{caller_id_num}"
                    body: |-
                      Hey there, its Santa Claus!
                      As we discussed, here's the link for the %{args.present_title} you wanted for Christmas: %{args.present_url}
                      Have a Merry Christmas!
                    from_number: "Your SignalWire Number Here"
                    media:
                      - "%{args.present_photo}"

Explanation of the send_present function:

  • purpose - This parameter is used to describe the purpose of the function.

  • active - This parameter is used to define whether the function is active or not. In this case, the function is set to false by default, as it will be toggled on by the present_lookup function. This will prevent Santa Ai from sending the user an SMS before they have chosen their preferred gift.

  • argument - This parameter is used to define the arguments that the function requires.

  • properties - This parameter is used to define the properties of the argument. In this case, we have a present_title, present_url, and present_photo argument, which represent the title, url, and photo of the present that the user wants to send to the user.

  • data_map - This parameter is used to define how the function will process the data it receives during the function call.

  • expressions - This parameter is used to define the expressions that will be used to process the data that is received during the function call. In this case, we are using the .* expression to match any string that is received during the function call and feeding it to the response parameter. The string the expression is being fed to is the present argument, which is the present url that the user will receive as a sms.

  • response - This parameter is used to define the response that will be sent to the AI after the function is complete. In this case, we are letting the AI know that we are sending the present to the user's phone as a text message.

  • action - This parameter is used to define the action that will be taken after the function is complete. In this case, we are using the toggle_functions action to turn the active state of both the send_present and present_lookup function to false. This will prevent the AI from sending the user additional SMS messages after the gift has been sent, as well as prevent the AI from looking up additional gifts. The SWML action is also action used to embed a separate SWML script into the current SWML script. This will allow us to call the send_sms method, which will send the chosen gift url to the user's phone as an SMS. We are using the caller_id_num variable to define the to_number parameter, which will send the SMS to the current callee's phone number.

Final SWML Script​

caution

If you are finding that the SMS is not being sent to your phone, even after replacing the from_number parameter with your own SignalWire phone number, it may be due to the fact that you have not registered your phone numbers messaging. Depending on if the phone number is a 10DLC or Toll-Free number, you will need to register or verify your phone number for messaging.

More information on 10DLC Message Campaign Registration can be found here.

More information on Toll-Free Number Verification can be found here.

If you do not wish to register or verify your phone number, you can check the logs in the post_prompt_url to see if the SMS was sent successfully in the SWAIG logs section.

Replace the following values:

  • post_prompt_url - Replace with your own post prompt webhook URL. Use Webhook.site for testing purposes.
  • X-RapidAPI-Key - Replace with your own Rapid API token which can be found on the Real-Time Amazon Data API page.
  • X-RapidAPI-Host - Replace with the host of the webhook which can be found on the Real-Time Amazon Data API page.
  • from_number - Replace with your own SignalWire phone number.
---
version: 1.0.0
sections:
  main:
  - ai:
      prompt:
        top_p: 0.3
        temperature: 0.6
        text: |-
          You can speak in English.
          Greet the user in a festive manner.
          Engage with a child as Santa Claus, spreading Christmas joy.
          In a jolly Santa voice, ask one cute, festive question at a time to discover what the children want for Christmas.
          ### Step 1 Ask them what they want for Christmas.
          ### Step 2 Use the present_lookup function to search for the requested gift and provide a summary.
          If the present summary is empty, explain there's an issue with the elves at Amazon and suggest trying later and then hang up.
          ### Step 3 Ask the child to pick one out of the top three presents listed in the presents summary.
          If the user wants a different present, acknowledge they want a different present and go back to Step 1.
          ### Step 4 Ensure the chosen present is from the present summary.
          If multiple presents are selected, request the child to choose only one.
          ### Step 5 Once confirmed, use the send_present function to finalize the gift choice.
          ### Step 6 Continue the conversation, keeping it playful and entertaining.
          If another present is requested, gently remind them that only one gift can be chosen.
      post_prompt_url: Post Prompt Webhook Here
      params:
        eleven_labs_stability: 0.1
        eleven_labs_similarity: 0.25
      languages:
      - name: English
        code: en-US
        voice: gvU4yEv29ZpMc9IXoZcd
        engine: elevenlabs
        fillers:
        - one moment please,
        - uhh ha,
        - aah ha,
        - hmm...
        - let's see,
      SWAIG:
        native_functions:
        - check_time
        functions:
        - function: present_lookup
          meta_data_token: summary
          purpose: To look for presents on Amazon, getting top 3 results.
          argument:
            type: object
            properties:
              query:
                type: string
                description: the present to look up
          data_map:
            webhooks:
            - require_args: query
              error_keys: error
              url: https://real-time-amazon-data.p.rapidapi.com/search?query=%{lc:enc:args.query}&page=1&country=US&category_id=aps
              method: GET
              headers:
                X-RapidAPI-Key: "Your Rapid API Token Here"
                X-RapidAPI-Host: real-time-amazon-data.p.rapidapi.com
              foreach:
                input_key: data.products
                output_key: summary
                max: 3
                append: 'title: %{this.product_title} photo: %{this.product_photo}
                  url: %{this.product_url}'
              output:
                response: |
                  If the present summary is not empty, repeat the titles of the top 3 presents from the summary to the user.
                  ### Present Summary:
                  %{summary}
                action:
                - toggle_functions:
                  - active: true
                    function: send_present
        - function: send_present
          meta_data_token: summary
          purpose: To send an SMS of an Amazon present to the user.
          active: 'false'
          argument:
            type: object
            properties:
              present_title:
                type: string
                description: The title of the present to send to the user.
              present_url:
                type: string
                description: The URL of the present to send to the user.
              present_photo:
                type: string
                description: The photo of the present to send to the user.
          data_map:
            expressions:
            - pattern: ".*"
              string: ".*"
              output:
                response: Let the user know that the present will be delivered on
                  Christmas.
                action:
                - toggle_functions:
                    - active: false
                      function: present_lookup
                    - active: false
                      function: send_present
                - SWML:
                    version: 1.0.0
                    sections:
                      main:
                      - send_sms:
                          to_number: "%{caller_id_num}"
                          body: |-
                            Hey there, it's Santa Claus!
                            As we discussed, here's the link for the %{args.present_title} you wanted for Christmas: %{args.present_url}
                            Have a Merry Christmas!
                          from_number: "Your SignalWire Number Here"
                          media:
                            - "%{args.present_photo}"

Santa AI Live Demo​

Testing SignalWire's Santa AI

To test a live demo of the Santa AI, call the SignalWire phone number below! Make sure to call from a phone number that has messaging services enabled, as the Santa AI will send you an SMS with a link to the chosen gift.

Santa AI Phone Number: +12019714214

Hosting your own Santa AI

To host your own Santa AI, simply copy and paste the SWML script above into a new relay script then assign it in your phone number settings, located on your SignalWire Dashboard. Don't forget to replace the sample values with your active post prompt webhook URL, Rapid API token, webhook host, and From number, as described above the sample script. Once assigned, call your SignalWire phone number and enjoy the magic of Christmas!

Conclusion​

In conclusion, this Santa AI, built with SWML, offers a magical and interactive way for children to communicate their Christmas wishes. It also helps to ease the gift-buying process for parents, as they can get a better idea of what their child wants for Christmas, and then purchase the gift directly from Amazon.