- sdk:swml - product:ai - product:voice # Creating a Santa AI with SWML: Engaging in the Spirit of Christmas ## **Prerequisites** * A SignalWire account ([sign up](https://signalwire.com/signup) for free!) * A SignalWire phone number ([buy a number](/platform/phone-numbers/getting-started/buying-a-phone-number) if you dont have one) * Real-Time Amazon Data API ([subscribe](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) 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 well 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)](/swml). The Santa AI well 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. Well explain each of these steps in detail throughout the article. Follow along, and dont 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 AIs personality, languages, and capabilities. yaml andJson 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 AIs purpose and his personality traits. Within prompt also define the AIs top_p, temperature and text parameters, which are used to control the AIs response. The top_p parameter defines the probability of the AIs response, while the temperature parameter defines the randomness of the AIs response. The prompts text parameter uses [Markdown](https://www.markdownguide.org/) 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 AIs 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](https://webhook.site/) to view the post prompt logs. This site will provide a unique URL that can be used as the post_prompt_url. yaml andJson 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 theres 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 Santas voice as the default voice. Santas 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 Santas speech, making it more realistic. yaml andJson languages: - name: English code: en-US voice: gvU4yEv29ZpMc9IXoZcd engine: elevenlabs fillers: - one moment please, - uhh ha, - aah ha, - hmm... - lets see, ### Params The params parameter is used to define the AIs eleven_labs_stability and eleven_labs_similarity parameters. The eleven_labs_stability parameter is used to define the stability of the AIs voice, while the eleven_labs_similarity parameter is used to define the similarity of the AIs voice to the voice that is defined in the voice parameter. This allows us to control the AIs voice and make it more realistic and as close to Santas voice as possible. You can learn more about these settings here: [Eleven Labs Documentation](https://elevenlabs.io/docs/speech-synthesis/voice-settings#stability). yaml andJson 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 users 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. yaml andJson 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 users input. When the present_lookup function is called, it will make a GET request to the [Real-Time Amazon Data API](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) to search for gifts based on the users 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 Santas ability to know all the best gifts and where to find them. yaml andJson 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 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 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](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) to search Amazon for the top three gifts based on the users 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](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) to search Amazon for the top three gifts based on the users 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](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) 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](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) 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](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) 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 json { status: OK, data: { total_products: 3, country: US, domain: www.amazon.com, products: [ { asin: B010RWDJOY, 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_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_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. yaml andJson 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: type: string present_url: type: string present_photo: type: string 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, heres 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 users 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 users 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 callees 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](/messaging/get-started/campaign-registry). More information on Toll-Free Number Verification can be found [here](/messaging/guides/general/toll-free-number-overview#get-verified). 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](https://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](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) page. - X-RapidAPI-Host - Replace with the host of the webhook which can be found on the [Real-Time Amazon Data API](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-amazon-data/) page. - from_number - Replace with your own SignalWire phone number. yaml andJson 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 theres 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... - lets 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 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 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: type: string present_url: type: string present_photo: type: string 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, heres 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 SignalWires 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](tel:+12019714214) **Hosting your own Santa AI** To host your own Santa AI, simply copy and paste the SWML script [above](#final-swml-script) into a new relay script then assign it in your phone number settings, located on your [SignalWire Dashboard](https://my.signalwire.com). Dont 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.