Skip to main content

Manage how your AI Agent hands customers off to live agents

For situations that your AI Agent can't handle, you can configure procedures for handing customers off to live agents. In this topic, you'll learn about how to configure different handoffs to suit different situations for your customers, and how to build your handoff content using modular blocks to ensure a smooth customer experience.

Understand different handoff situations

Your AI Agent handles different situations that might require handoffs differently:

  • Handoffs to live agents

    On the Ada dashboard, when you go to AI Agent profile > Handoffs, on the Handoffs tab, you can view and modify handoffs to live agents. You can have up to five active handoffs at a time.

    These are the most important handoffs that you can configure. When your AI Agent knows it needs to hand a customer off to a live agent, it then chooses which of these handoffs to perform, based on the name and description you provide (e.g., you might want to have different handoff procedures based on whether a customer is asking for a subscription renewal or a return).

  • Fallback handoffs

    Additionally, on the Off hours tab, you can edit pre-existing content created for fallback handoff scenario:

    • Off-Hours: When a customer requests a handoff to a live agent outside of your hours of operation
    • Error Fallback: When an error occurs when your AI Agent tries to either hand a customer off to a live agent, or to make an API request
    note

    Depending on the features your organization has enabled, you may see more preconfigured handoff types in your dashboard. For more information, reach out to your Ada team.

Understand how variables work in handoffs

You can create variables to capture or set a piece of information (e.g., get the customer's name), so you can use the value saved in the variable later. Variables are useful for referring to basic pieces of information in a conversation, or for more complex use cases like making an API call, then saving the response as a variable that you can then use to populate a list of options a customer can choose (e.g., a list of the customer's recent orders).

You can use the same variable in other places where you can use blocks in your AI Agent, too - your AI Agent will know not to ask for the same piece of information twice, and if you do want it to ask twice, it'll know to always use the newest value.

note

These variables only work within the structured content you create with blocks, and are separate from information that your AI Agent collects for Actions.

As a best practice, when you're using a variable to repeat a piece of information in text (e.g., if you're repeating the customer's name), make sure you set fallback values so that if the variable isn't set, your AI Agent can still have something to say.

Edit your AI Agent's handoff content

Every piece of handoff content contains default content. You can edit that content directly, or you can edit it by adding or removing blocks.

For any piece of handoff content, the process to edit it is the same:

  1. On the Ada dashboard, go to AI Agent profile > Handoff.

  2. Choose the type of handoff you want to configure.

    • To create or edit a regular handoff, go to the Handoffs tab. Then, click New Handoff, or click an existing handoff type to edit it.
      1. Under Identify this Handoff, fill in information about the handoff under Name and Describe when to use this Handoff.

        Your AI Agent will use the information you enter here when it's reasoning through when it's appropriate to trigger this handoff.

      2. If required, you can restrict handoff to certain users, based on information your AI Agent collects about your users and saves in variables.

        note

        You can only use variables your AI Agent can collect through your browser, or that you collect in a block and allow to be available outside of the structured content the block is in. You can't use variables your AI Agent collects using Actions.

        • To make the handoff available to all users, select Everyone.

        • To restrict the handoff to certain users, select Based on the following rules. A section expands where you can enter the logic your AI Agent will use to decide whether to serve the handoff.

          1. Beside Where, in the Choose a variable list, select a variable.
          2. In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target.

            Understand comparison operators

            Comparison operators are logic statements that tell your AI Agent to match customer information that’s captured in the variable you’re using. The available operators vary based on the variable type you’re using:

            OperatorVariable typesDescription

            Begins With

            • All text variables (including phone and email)

            Match information in the variable that begins with certain text (partial match).

            Ends With

            • All text variables (including phone and email)

            Match information in the variable that ends with certain text (partial match).

            Contains

            • All text variables (including phone and email)

            • List variables

            Match information in the variable that contains certain text in any position (partial match).

            Is

            • All text variables (including phone and email)

            • Number variables

            Match information in the variable that equals specific text exactly (exact match).

            Is Not

            • All text variables (including phone and email)

            • Number variables

            Match information in the variable that does not equal specific text exactly (exact match).

            Is Not Set

            • All text variables (including phone and email)

            • Number variables

            • List variables

            Match if there is no information contained in the variable.

            Is Set

            • All text variables (including phone and email)

            • Number variables

            • List variables

            Match if there is any information contained in the variable.

            Greater Than

            • Number variables

            Match if the information in the variable is greater than a specific value.

            Less Than

            • Number variables

            • List variables

            Match if the information in the variable is less than a specific value.

            Is True

            • Yes/No variables

            Match if the information in a variable is Yes (or True).

            Is False

            • Yes/No variables

            Match if the information in a variable is No (or False).

            Does Not Contain

            • List variables

            Match if none of the selected items contains this value.

            Is Equal To

            • List variables

            Match if the customer selected a particular number of options in a List Option block.

            Is Greater Than

            • List variables

            Match if the customer selected more than a particular number of options in a List Option block.

            Is Less Than

            • List variables

            Match if the customer selected fewer than a particular number of options in a List Option block.

          3. In the Value field, enter or select a value for the variable that you want to use to target users.

          4. If required, add additional conditions.

            • By default, if you click the Add icon , new conditions will be added with "or" statements, meaning customers will see the handoff if they fulfil any of your criteria.
            • You can click And to add additional conditions that must all be satisfied for your AI Agent to serve the handoff.
    • To edit an off-hours handoff, go to the Off hours tab. Then, click a handoff situation to edit it.
  3. Use blocks to build your handoff content. You can:

    • Drag blocks from the block drawer on the right side of your screen into your handoff content, then add content in them
    • Edit content in existing blocks directly
    • Click the Delete icon on a block to remove it

    Depending on the way your AI Agent is configured, the blocks available to you may vary. You can click one of the expanders below to learn more about any one of the blocks:

    Text block

    The Text block delivers simple text messages to your customers. Each Text block appears as a single chat bubble, and can contain up to 320 characters.

    You can add emojis and line breaks to give your Text blocks some personality and formatting 😎


    Use AI to improve your text content

    Any time you serve up content using the Text block, no matter which of Ada's supported languages you're writing in, you have the option to polish it with AI. You can click the Improve button to automatically run your content through GPT and replace it with a rephrased version with improved tone. Even after improving your content automatically, you can always go back and edit it yourself until you're happy with it.

    Add variations to your text content

    You can also use the Text block to create variations of the same message so you can keep your content fresh. Your AI Agent will randomly select a variation to send to your customer, and you can either write your own variations or generate them with AI.

    We recommend using variations with content that is likely to show up repeatedly in a single conversation. For example, adding different versions of "hi" or "hello" in the Greeting will give your AI Agent more personality and prevent the conversation from feeling robotic.

    If your shuffled message contains essential information, make sure that information is in every variation — otherwise, only random customers will get the important message!

    Use AI to create message variations

    To start creating content variations for your AI Agent to shuffle between, start typing a message into your block. If you want, you can use the Improve button to refine your initial message.

    Then, you can use the Create variations button to use GPT to rephrase your content into 3-5 variations for your AI Agent to randomly serve to customers - in any of Ada's supported languages. All of these automatically generated variations are editable and removable, so you can further refine the variations you get from the AI. You can also click Add manually to write additional variations yourself.

    Capture block

    You can use the Capture block to prompt customers for information, like their names, and save it as a variable to use in other blocks. For example, you can ask them their name, save it in a variable, and later use their name in other blocks. For each variable you want to populate with a value from a customer, use a separate Capture block.

    Configure the Capture block using the table below as a guide:

    FieldInstructions

    Content

    Add a message to this field requesting the information you want to capture.

    Placeholder Text on the Chat Input (Optional)

    Use this field to customize the placeholder text visible in the message field. Craft a brief instruction or example to help your customers understand what information they should send.

    Validation

    Set the type of data the created variable will accept:

    • Text – Accepts any character type.

    • Email – Only accepts valid email addresses. Also verifies that the domain is valid, such as .com, .ca, etc.

    • Phone Number – Only accepts input formatted as a phone number, disregarding any letters or special characters.

    • Number – Only accepts numbers; allows periods and commas.

    • Yes and No – Only accepts a positive or negative response (e.g., yes/no, true/false).

    Capture Settings

    This section contains toggles that let you control the block's interaction behavior.

    Always Ask

    • Deactivated – The Capture block won't display for customers if its variable is already populated. This ensures the bot only asks for specific information once, such as a customer's name.

    • Activated – The block will always trigger whenever it is encountered, and overwrite any data that already exists in its variable.

    Required

    • Deactivated – A Skip button displays in the chat window. Clicking this allows the customer to skip the Capture block and move on to the next block in the handoff content.

    • Activated – A Never mind button displays in the chat window. Clicking this exits the handoff content entirely, and directs the customer to ask about something else instead.

    Save Response As

    Use the drop-down menu to choose the variable the Capture block populates with the captured data. You can select an existing variable, or create a new one.

    Smart Detection (Optional)

    Your bot can detect relevant information that returning customers have provided in past conversations. Depending on your bot's configuration, this option may not be available.

    Click the Select entity type drop-down menu and select the relevant entity for this capture event. Click Clear to remove a previously assigned entity type (e.g., full name, city, airport, date or time, etc.)

    Set Variable block

    With the Set Variable block, you can automatically define variables in your handoff content that you can use in other blocks, without your customers ever knowing it's happening behind the scenes.

    1. Under Variable, select a variable to save the value in, or click Make New Variable to create a new one.

      note

      You can’t select metavariables, which your AI Agent sets automatically, or variables that contain list responses.

      If this variable already has a value assigned to it at this point in the conversation, this block will overwrite the old value. If you created a new variable, follow these steps to finish creating it:

      1. If you created a new variable, enter a Name for it that describes the data it will contain.
      2. Under Availability, select either Only this Answer to limit the variable’s use to the current handoff content, or All Answers to make the variable available throughout your AI Agent.
      3. Under Type, select the type of information the variable should store, so your AI Agent can help validate chatter responses to fit it.
      4. Click Save. Your AI Agent saves your new variable.
    2. Under Content, beside the dropdown list, click the More Options icon and select a variable type:

      • Basic: Save a static text value that you add manually into the variable.

      • Variable: Save the content of another existing variable into this variable. For example, you can save the value of an existing metavariable into this variable.

        note

        For security reasons, you can’t save a variable with the value of an authentication variable.

      • True/False: Save either a positive or negative response in the variable.
      • Null: Clear any previously set values from the variable.
    3. Under Content, enter or select a value to save in the variable. The options you have depend on the variable type you selected, or are absent if you selected Null.

    4. If required, click Add new variable to add additional variables to set at the same time.

      If the block contains more than five variables, it will be collapsed by default the next time you view the handoff content, so you can scroll through the handoff content’s content more easily. To expand the block and view all of the variables, click the arrow icon next to the trash can icon in the upper-right corner of the block.

    Conditional block

    With Conditional blocks, you can target specific content to different customers depending on variables associated with them.

    note

    You can't use variables from your Actions when you're setting conditions. This is because you can't control when your customer might trigger an Action, so you can't depend on your AI Agent having that information when it needs to use it.

    The Conditional block uses logic to decide whether it should serve content to customers. Sometimes this is called "if-then-else" logic. Here's how it works in Ada:

    • If statement: Set up the criteria your AI Agent uses to decide whether to serve the customer with a piece of content.

      • Within a single If statement, you can have multiple criteria. You can choose to make all of these criteria necessary ("if x AND y") or just one of them ("if x OR y").
    • Then action: Set up the action your AI Agent takes if the user meets the criteria.

      • For each If statement you create, drag in content blocks to serve to customers who meet that condition. If a customer doesn't meet the criteria, the AI Agent moves on to the next condition and try again, until it reaches the Else condition.
    • Else action: Set up the action your AI Agent takes if none of the above if statements apply. If you don't set up an Else action, the AI Agent effectively doesn't have any instructions, and doesn't perform any of the actions in your Conditional block.

    Create conditions to create targeted content

    To start using the Conditional block in your handoff content, add the Conditional block and follow these instructions:

    1. Create a condition. On the dashboard, your first condition is indicated with the symbol.

      1. If you want your condition to work with multiple criteria, you can choose how that behavior works. Select either If all of or If any of in the dropdown list. With this option, you can create multiple criteria for the same condition, and define the logic that determines whether your AI Agent serves the content for this condition or if it moves on to the next condition.

        Example:

        • You want to send a message to customers who have both gold level accounts and who live in Canada. In this case, you select If all of, and you create two criteria (the account_type variable’s value is equal to “gold”; the country variable’s value is equal to “Canada”).

        • You want to send a message to customers who have either silver or gold level accounts. in this case, you select If any of, and you create two criteria (the account_type variable’s value is equal to “silver”; the account_type variable’s value is equal to “gold”).

      2. Choose a variable to use as a basis of comparison. There’s no limit to the number of variables you can use.

      3. Choose an operator. The comparison operators available vary depending on the type of variable you chose in step b; for more information, see the Understand comparison operators section of this topic.

      4. If the operator you chose compares the variable to a value, configure that value. To the right of the Value field, click the Options button and choose your field options. Then, enter a value to check against the variable’s value.

        • Basic: Compare the variable with a value you type yourself.

        • Variable: Compare the variable with a different variable.

        • Match Case: Only allow matches if the case matches for both the variable and your comparison value. For example, if the value you enter is Word, your AI Agent wouldn’t accept word , WORD, or wOrd as matches.

      5. To add additional criteria, click the Add button and repeat steps ii-iv.

    2. Under the condition you just made, drag and drop blocks that you want those customers to see.

      note

      You can’t drag and drop Conditional blocks into a Conditional block, because they're designed to contain other blocks instead of being contained. If you need more complex logic in your AI Agent, contact your Ada team for assistance.

    3. To add additional conditions, click the Add Condition button and repeat steps a-b. Additional conditions are indicated with the symbol.

    4. Lastly, it’s a good idea to set up an else condition, so customers who don’t meet any of your conditions still see content. The action is indicated with the symbol. For this condition, all you have to do is drag content blocks in. You don’t have to set up this condition, but it’s useful as a best practice.

    Understand comparison operators

    Comparison operators are logic statements that tell the Conditional block to match customer information that's captured in the variable you’re using. The available operators vary based on the variable type you're using:

    OperatorVariable typesDescription

    Begins With

    • All text variables (including phone and email)

    Match information in the variable that begins with certain text (partial match).

    Ends With

    • All text variables (including phone and email)

    Match information in the variable that ends with certain text (partial match).

    Contains

    • All text variables (including phone and email)

    • List variables

    Match information in the variable that contains certain text in any position (partial match).

    Is

    • All text variables (including phone and email)

    • Number variables

    Match information in the variable that equals specific text exactly (exact match).

    Is Not

    • All text variables (including phone and email)

    • Number variables

    Match information in the variable that does not equal specific text exactly (exact match).

    Is Not Set

    • All text variables (including phone and email)

    • Number variables

    • List variables

    Match if there is no information contained in the variable.

    Is Set

    • All text variables (including phone and email)

    • Number variables

    • List variables

    Match if there is any information contained in the variable.

    Greater Than

    • Number variables

    Match if the information in the variable is greater than a specific value.

    Less Than

    • Number variables

    • List variables

    Match if the information in the variable is less than a specific value.

    Is True

    • Yes/No variables

    Match if the information in a variable is Yes (or True).

    Is False

    • Yes/No variables

    Match if the information in a variable is No (or False).

    Does Not Contain

    • List variables

    Match if none of the selected items contains this value.

    Is Equal To

    • List variables

    Match if the customer selected a particular number of options in a List Option block.

    Is Greater Than

    • List variables

    Match if the customer selected more than a particular number of options in a List Option block.

    Is Less Than

    • List variables

    Match if the customer selected fewer than a particular number of options in a List Option block.

    Request block

    You can use the Request block to make an API call. You can save all or part of the response as a variable so you can serve the content in text blocks, or use the response to populate a list of options in the List Option block.

    note

    Currently, you can only make GET requests with the Request block.

    1. Enter the API address in the URL field.

    2. Select your request type from the Method list.

    3. If required, use the Headers fields to pass metadata, like public access tokens, content type, and language.

      Example:

    4. If required, fill out the Body Content fields to pass details or instructions to the API server. Make sure you accurately define the content type (string, number, list, etc.).

    5. Click Test Request to send a sample API call and see the response body that comes back.

      • If you want to repeat the request, click the Repeat icon at the top of the response.

      • If you want to copy the response body to your clipboard, click the Copy icon at the top of the response.

    6. Under Error fallback, you can click to edit the AI Agent's response if an error occurs and it can't complete the call successfully.

    7. Under Save As Variable, save all or a portion of the response body in one or more variables for use in other blocks.

      The easiest way to save a particular attribute is to click a blue tag with a “+” icon in the response body to automatically save that attribute as a variable. You can select or create a variable to save that value in, and the Data Key field automatically populates, as below.

      For more complex use cases, you may have to type in a data key yourself, so you can target a particular attribute or array in the response. For more information, see Use data keys to target a portion of an API response.

    8. To add an additional variable, you can either click another tag in the response body, or click the green “+” icon by the Save As Variable fields.

    Use data keys to target a portion of an API response

    Data keys are a way to tell your AI Agent to target a portion of the API request so you can save it as a variable. There is a variety of ways to do this, depending on your end goal. If you need any assistance, don't hesitate to contact your Ada team.

    Limitations

    Before targeting data in your API response, you should know that there are some limitations to how Ada processes the data they contain:

    • You can target nested data in your response, but only up to eight levels. If you try to target values that are nested farther down in your response, your AI Agent won't be able to retrieve them.
    • Variables can contain up to 100,000 characters. Particularly when you're saving all or part of an API response as a variable, make sure you don't exceed this limit. If you do, you may start seeing errors, because your AI Agent might not be able to correctly parse your variable content.

    Data key notation

    Ada uses different types of notation to target different parts of the response:

    • Target the entire API response

      To save the entire API response in a variable, use the ada_response_string data key.

    • Target a specific attribute or array

      To target a specific attribute or array, enter its name exactly as it appears in the API.

      Example: Target a specific attribute

      Here's a portion of a response from the above Studio Ghibli API, which contains information about Princess Mononoke:

      {
      "id": "0440483e-ca0e-4120-8c50-4c8cd9b965d6",
      "title": "Princess Mononoke",
      "original_title": "もののけ姫",
      "original_title_romanised": "Mononoke hime",
      "image": "https://image.tmdb.org/t/p/w600_and_h900_bestv2/jHWmNr7m544fJ8eItsfNk8fs2Ed.jpg",
      "movie_banner": "https://image.tmdb.org/t/p/original/6pTqSq0zYIWCsucJys8q5L92kUY.jpg",
      "description": "Ashitaka, a prince of the disappearing Ainu tribe, is cursed by a demonized boar god and must journey to the west to find a cure. Along the way, he encounters San, a young human woman fighting to protect the forest, and Lady Eboshi, who is trying to destroy it. Ashitaka must find a way to bring balance to this conflict.",
      "director": "Hayao Miyazaki",
      "producer": "Toshio Suzuki",
      "release_date": "1997",
      "running_time": "134",
      "rt_score": "92",
      ...
      }

      To save the movie title as a variable, use the data key title. Note that the key has to exactly match what's in the API response, so the data key Title wouldn't work.

      Example: Target a specific array

      If the API request returns an array, you can save the whole array as a variable as well. For example, here's a heavily truncated response from the Star Wars API, which contains a list of the Star Wars movies:

      {
      ...
      "results": [
      {
      "title": "A New Hope",
      "episode_id": 4,
      "opening_crawl": "It is a period of civil war...",
      "director": "George Lucas",
      "producer": "Gary Kurtz, Rick McCallum",
      "release_date": "1977-05-25",
      ...
      },
      {
      "title": "The Empire Strikes Back",
      "episode_id": 5,
      "opening_crawl": "It is a dark time for the Rebellion...",
      "director": "Irvin Kershner",
      "producer": "Gary Kurtz, Rick McCallum",
      "release_date": "1980-05-17",
      ...
      },
      ...
      ]
      }

      In this case, you could use the results data key to save an array containing information about all of the movies in your variable.

    • Target a child array or attribute

      You can use dot or bracket notation to target either arrays or attributes nested in other arrays or attributes.

      Any of these notations would get your AI Agent to look for an attribute called parent and save either an array or attribute within it called child:
      • parent.child

      • parent[child]

      • "parent"["child"]

        • Using quotation marks might help if the array or attribute name has a space in it. You must use double quotes, as above; if you use single quotes (e.g., 'parent'['child']), the data key won't work.

      If you're looking for something nested inside an array, you can target a particular instance based on its order in the API response. Note that this numbering starts at 0, not at 1, and that these numbers must be in brackets.

      For example, with this notation, your AI Agent would look for the first item in the array called parent, find the array within it called child, and save the second item within the child array:
      • parent[0].child[1]

      • [parent][0][child][1]

      • ["parent"][0]["child"][1]

      warning

      This method assumes that responses in the API will always be in the same order. Remember to test your API request with a variety of scenarios to ensure your data key correctly selects the attribute you're looking for. If you find that the order of items in your API response varies between calls, contact your Ada team to find a solution.

      Example: Target attributes or arrays nested in an array

      Here's another example from the Star Wars API, this time with a list of species that appear in the movies:

      {
      ...
      "results": [
      {
      "name": "Human",
      "classification": "mammal",
      "designation": "sentient",
      ...
      "films": [
      "https://swapi.dev/api/films/1/",
      "https://swapi.dev/api/films/2/",
      "https://swapi.dev/api/films/3/",
      "https://swapi.dev/api/films/4/",
      "https://swapi.dev/api/films/5/",
      "https://swapi.dev/api/films/6/"
      ],
      ...
      },
      ...
      ]
      }

      "Human" is the first item in the list of Star Wars species in the results array, so if we want to target a piece of information that pertains to human characters, we'll start the data key with results[0]. From there, we can start targeting more specific information:

      • To target the name attribute of the species, use the data key results[0].name.

      • To target the entire array of Star Wars films in which humans appear, use the data key results[0].films.

      • To target only the fourth Star Wars film in which humans appear, use the data key results[0].films[3].

    List Option block

    The List Option block lets your bot offer customers a list of selectable items. Your AI Agent saves the item the customer selects as a variable that you can use in other blocks (e.g., in a Conditional block). You can create the list of options manually, or populate the list with saved variables.

    1. If you want the options in your list to populate dynamically from an API call, do the following:

      1. Set up an HTTP Request block in your handoff content.
      2. Use a data key to save the required portion of the API response as a variable. That portion of the API response is what you’ll use to dynamically generate your list.

        caution

        Variables are limited to 100,000 characters. Particularly when you’re saving all or part of an API response as a variable, take care that you don’t exceed this limit. If you do, you may start seeing errors, because your bot might not be able to correctly parse your variable content.

        Other than the variable text limit, the only limitation on how many options can be in your list is that every message Ada serves must be under 10KB. Messages virtually never reach this size.

    2. In the text field at the top of the block, enter a message prompting the customer to make a selection. It could be as simple as “Pick an option,” but should also include specific instructions when necessary. This bubble will appear right before the list of options.

    3. Under Options Source, choose how you want to populate the list items. Then, depending on your choice, configure how you want the list items to appear under Option Setup.

      • Click Manual to use a static list of options. You can type these out yourself, or use variables.

        Configure manual list options

        By default, when a customer makes a selection, your AI Agent saves the text they selected as the variable value. Optionally, you can define custom values for each option for your AI Agent to save, instead of the text that appears to customers. When configuring manual list options, you have the option of managing those items separately:

        • Label: The text that customers see

        • Value: The text that your AI Agent saves when the customer makes a selection

        If you choose to make custom labels and not separate values, your AI Agent will save the label text upon customer selection instead.

        1. Under Label, enter the labels you want customers to see. You can type out text, use variables, or use a combination of the two.

          To add an option to the list, click Add Option. To delete an option, hover your cursor to the right of an option row and click the Delete button that appears.

          note
          If an option label only consists of a variable, and that variable is empty, that option won’t appear to customers.
        2. In some cases, you may need to save the customer’s selection in the dashboard differently from how it appears to them. To do this, toggle on the Assign different values from label option. Then, in the Value column that appears, enter the values you want to save in your variables.

          tip

          Different values can be useful in use cases like multilingual AI Agents that have manual translations. You may want to use translated variables so customers see the options in their languages, but behind the scenes, you may want the saved variable to be in English for all customers.

          Note that if your AI Agent uses automatically generated text, values are always stored in English in the back end, regardless of the language that customers see.

      • Click Dynamic to use a dynamic list of options from an API response. In this case, you must save an array from the API response so you can use all instances of an attribute in the array to appear as your list options.

        Configure dynamic list options
        1. In the List Option block, beside Data Source, enter the variable you saved the API response portion in.

        2. Beside Label Key Template, enter one or more attributes that appear in the variable to appear in the list options.

          • To include an attribute, put it in curly braces: {{item_name}}.

          • You can include multiple attributes, and have additional text in the items too: {{item_name}}, ordered on {{order_date}}.

    4. Select the Multiple Select checkbox to allow customers to select more than one option.

    5. Under Error fallback, you can click to edit the AI Agent's response if an error occurs.

    6. Under Save Response as Variables/a Variable, create or select a variable to save customers’ responses in, so you can use them later. For more information about the types of variables you can save responses in, see Understand variable types.

      note

      If you turned on Multiple Select, you must save the response in a List type variable.

    7. Under Capture Settings, choose whether you want to allow customers to advance through the handoff content without making a selection.

      • Turn on the Response Required toggle to ensure that customers provide a response before being able to advance through the handoff content.

        • If they don’t, and they click Never mind instead, your AI Agent will stop going through the blocks in your handoff content and prompt the customer to ask about something else.

        • If the Response Required toggle is off, customers will see a Skip button that they can use to move on to the next block in your handoff content.

      • If you turned on the Response Required toggle, a Show Cancel Button toggle appears. Turn this toggle on to show customers a Cancel button. If a customer clicks it, your AI Agent will stop going through the blocks in your handoff content and prompt the customer to ask about something else.

    A completed List Option block looks like this:

    Understand variable types

    When creating a target variable for your options list, the variable type you choose depends on whether you allow the customer to select only one item from the options list or multiple items. If you have multiple select enabled, you must save the response in a List variable.

    • Text – A Text target variable can be used with any type of option variable.

    • Number – To use a Number target variable, all option variables in the list must be number variables.

    • Yes or No – The Yes or No target variable can only be used when the option variables in the list are also yes or no variables.

    • List – If you allow your customers to select more than one item from the options list, you must save their selections as a List variable. Items collected in a List variable are separated by semicolons.

      Once collected using the multiple select functionality, List variables can be used as you would any other variable. Here are a few examples:

      • Added to a block to relay the information back to the user, with each item separated by semicolons (e.g. “The items your shipment was missing are: lipstick; mascara; blush.”)

      • In a Conditional block

      Example: When asking a customer to indicate items missing from an order, assume you have separate sets of instructions for customers missing one item versus those who are missing multiple items. You can use the Conditional block to serve one set of instructions if the list length equals one item, and the second set of instructions if the list length equals two or more items.

    Sign In and Sign Out blocks

    In some cases, you may either serve customers with sensitive data, or give them the chance to make changes to their account, orders, bookings, etc. In these cases, you should authorize customers by asking them to sign in to their account.

    Sign-in confirms the customer is the person they claim to be, which should happen before your AI Agent shares any sensitive data. Sign-in generates an authentication token that you can use to call APIs that require an OAuth token in order to return account-specific information to the customer. After authentication, you can securely provide customers with a more detailed and personalized experience, by sharing information (such as balances, due dates, credits, etc.) or making changes to their account.

    Configure an authentication method

    Before you can use Sign-In and Sign-Out blocks in your handoff content, you have to configure your authentication methods. For more information, see Authenticate your AI Agent's API calls using tokens.

    Add a Sign In block to your handoff content

    After you have set up at least one authentication method in your settings, you can put Sign In/Out blocks in your handoff content.

    note

    If the customer has already signed in from another handoff content or prior to opening the AI Agent, the Sign In button will appear, but the customer won’t need to enter their credentials again.

    1. On the Ada dashboard, go to AI Agent profile > Handoff and open the handoff content you want to add authentication to. Drag the Sign In block into your handoff content.

    2. In the Sign In block, fill in the following fields:

      • Message: Write a prompt asking the customer to sign in.
      • Sign In Button Label: Write custom text to appear on the sign in button.
      • Auth Provider: Select the name of the authentication you configured in your settings.
      • Error Answer: If the authentication fails, the AI Agent will send the handoff content specified here.

    Add a Sign Out block to your handoff content

    The Sign Out block signs out the chatter from the authentication provider wherever you add it to your handoff content. If you don't add a Sign Out block to your AI Agent, the chatter remains signed in until the authorization token expires.

    note

    The Sign Out block only signs the chatter out from the AI Agent. It does not log the customer out of their web experience.

    1. On the Ada dashboard, go to AI Agent profile > Handoff and open the handoff content you want to add authentication to. Drag the Sign Out block into your handoff content.
    2. In the Auth Provider list, select the authentication you configured in your settings.
    Fetch Chat Metadata block

    With the Fetch Chat Metadata block, you can add the chat transcript and/or customer information from a conversation, and save that information as variables. This can be very useful when you're setting up handoffs, so you can pass along additional information to the live agent.

    1. Under Select Variables for Inputs, beside Chatter Token, click inside the field and add the red chatter_token metavariable.

    2. Under Save Response as Variables, click the Select Optional Variables drop-down menu, then select any optional variables you’d like to capture:

      • Chat Transcript: Select this option to save the conversation transcript to a variable.
      • Chatter Info: Select this option to save the customer’s metadata to a variable. This is the same information available about the customer’s meta variables when you’re viewing a chat transcript.
    3. For each optional variable you selected, click the Choose a Variable drop-down menu, then select an existing variable, or create a new one, to capture the information.

    4. Under Fallback Answer, you can click to edit the AI Agent's response if an error occurs.

    Email block

    You can use the Email block to hand customers off via email. In any of the fields you configure for the email, you can include variables so you can pass relevant information on to live agents.

    1. In the Select Variables for Inputs section, complete the mandatory variable fields:

      • Recipient Email(s): Add the primary recipient email address. You can add the email variable, or manually enter the recipient’s email address. Separate multiple email addresses with a comma.
      • Reply-To Email: Enter the Reply-to email address you wish to assign to receive replies to your email.
      • Email Subject: Enter the email subject.
      • Email Content: Enter the body text of the email.
    2. Click the Select Optional Inputs drop-down menu, then select any optional variable fields you’d like to add:

      • BCC Email(s): Add blind carbon copy recipient email addresses. BCC addresses are not visible to other recipients.
      • CC Email(s): Add secondary recipient email addresses. These addresses are visible to other recipients.
      • Content Type: Enter the MIME type you want to use in your email:

        • If you just want to enter plain text, or if you’re not sure what to use, enter text/plain.
        • If you want to use HTML tags, enter text/html.
      • Reply-To Name: Enter the name of the Reply-to recipient.
      • Sender Name: Enter the name of the email sender. This appears in the From field.
    3. Under Fallback Answer, you can click to edit the AI Agent's response if an error occurs.

    Scheduled block

    The Scheduled block allows you to set days of the week and time ranges for your AI Agent to deliver different responses.

    For example, your AI Agent can offer to hand customers off to a human agent when agents are scheduled to be available, or offer to send an email request when agents aren't available.

    Create a schedule

    Before you start using the Scheduled block, you need to create a schedule so your AI Agent knows when to deliver different responses.

    1. On the Ada dashboard, go to Platform > Schedules. The Schedules page displays.
    1. Click New Schedule. The New Recurring Schedule window opens.

    2. In the New Recurring Schedule window, configure the following settings for your schedule:

      1. Under Schedule Name, provide a unique name for your schedule.

      2. Under Timezone, select your time zone.

      3. Under Repeat every, select the days of the week for your schedule to be active. Then, for the days you selected, select either a window of time or click All Day to make the schedule active for the entire 24-hour period.

        If required, click Add a new rule to add additional days and times.

      4. Optionally, under Except, you can add exceptions to your regular schedule for events like holidays.

        For example, if your regular hours are 9 a.m. to 5 p.m., but on December 10 your hours are 9 a.m. to 1 p.m., create an exception for December 10 from 1 p.m. to 5 p.m., during which you can set handoffs to be unavailable.

        If required, click Add a new exception to add additional exceptions.

    3. Click Save. Your schedule is now available for selection in the Scheduled block.

    Add the Scheduled block to your handoff content

    1. On the Ada dashboard, go to AI Agent profile > Handoff, then open the handoff content you want to put scheduled content into.
    2. Drag and drop the Scheduled block from the block drawer into your handoff content.
    3. Under Within Schedule?, select the schedule you want your AI Agent to follow.
    4. Drag and drop blocks into the Yes and No fields, and add content to them as required.

      • If the customer's question occurs within the date and time range, your AI Agent identifies the current state as Yes, and serves the corresponding block content.
      • If the customer's question occurs outside the date and time range, your AI Agent identifies the current state as No, and serves the corresponding block content.
      note

      You can't nest Conditional blocks inside Scheduled blocks.

    5. Click Save. Your AI Agent can now send customers custom content based on your schedule.
    Salesforce handoffs

    You can configure your AI Agent to hand customers off using Salesforce.

    Zendesk handoffs

    You can configure your AI Agent to hand customers off using Zendesk. You have some options for how to configure your handoffs:

  4. At the bottom of the screen, click Save. Your AI Agent saves your changes.

View and manage previous versions of your handoff content

Your AI Agent saves a history of all edits you've made to your handoff content over the last 30 days. You can revert your changes to your handoff content back to any of these saved versions.

  1. On the Ada dashboard, go to AI Agent profile > Handoff, then open the handoff content you want to manage versions for.
  2. At the top of the page, you can see when the handoff content was last edited. Click that text to open a pane that contains a list of versions of the handoff content over the last 30 days. You can click a version to see the handoff content at that time.
  3. Optionally, for significant versions, you can add a name and description for future edits. To do this, hover over the version, click the More options button that appears, filling in the Version Title and Description fields as required, then clicking Save.
  4. To revert to a previous version of your handoff content, select the version you want to go back to. Then, at the top of the page, click Restore Version. Review your changes to ensure you're not reverting anything you want to keep, then click Save to save your reverted changes.

Have any questions? Contact your Ada team—or email us at .