Package cx.syndeo.script.api

Interface SyndeoScriptAPI

public interface SyndeoScriptAPI
The SyndeoScriptAPI interface provides a comprehensive set of methods for interacting with the Syndeo platform within script environments. For both Javascript and Groovy implementations, the SyndeoScriptAPI interface is accessed via the syndeo object.

Sample JavaScript Usage


    var variables = syndeo.getVariables();
    var userInput = variables.get("UserInput");
    var recognitionResults =  syndeo.getIntents(userInput);
    syndeo.log.debug("Recognition Results: " + JSON.stringify(recognitionResults));

  • Method Details

    • getSurveyId

      Long getSurveyId()
      When a post-conversation survey is configured a Question-Answered event is received. This method is only supported in the "Survey Question Answered Event" script event and returns null in a Flow Script task.
      Returns:
      The ID of the survey the user has responded to, or null if not used in a "Survey Question Answered Event" script event.

    • getSurveyName

      String getSurveyName()
      When a post-conversation survey is configured a Question-Answered event is received. This method is only supported in the "Survey Question Answered Event" script event and returns null in a Flow Script task.
      Returns:
      The name of the survey the user has responded to, or null if not used in a "Survey Question Answered Event" script event.

    • getAnswer

      String getAnswer()
      When a post-conversation survey is configured a Question-Answered event is received. This method is only supported in the "Survey Question Answered Event" script event and returns null in a Flow Script task.
      Returns:
      The answer the user has given to a survey question, or null if not used in a "Survey Question Answered Event" script event.

    • getQuestion

      SurveyQuestion getQuestion()
      When a post-conversation survey is configured a Question-Answered event is received. This method is only supported in the "Survey Question Answered Event" script event and returns null in a Flow Script task.
      Returns:
      The question a user was responding to when they provided a survey answer, or null if not used in a "Survey Question Answered Event" script event.

    • getChannel

      Channel getChannel()
      Returns details of the active Channel, through which this conversation is currently taking place.
      Returns:
      Channel with details like the channel name and target ID. Can't be null.

    • getVariables

      Variables getVariables()
      Returns the current Variables instance, which includes all variables currently in session.
      Returns:
      the transfer variables, or null if they have not been initialized

    • getMessages

      Messages getMessages()
      Messages are the prompts used within the configured flow. This returns the current

    • addExtraChoice

      void addExtraChoice(String answer, String visibleText)
      Creates a new context menu choice with the given visible text and postback answer, and adds it to the extraChoices list. The new extra choice will be shown along with the next question.
      Parameters:
      answer - the postback value that will be sent when the choice is selected
      visibleText - the text displayed to the user for this choice

    • addExtraChoice

      void addExtraChoice(String answer, String visibleText, String fileKey)
      Creates a new context menu choice with the given visible text, postback answer, and associated file key, then adds it to the extraChoices list. The new extra choice will be shown along with the next question.
      Parameters:
      answer - the postback value that will be sent when the choice is selected
      visibleText - the text displayed to the user for this choice
      fileKey - the file key associated with this choice

    • addExtraChoice

      void addExtraChoice(String answer, String visibleText, String fileKey, String url, String urlButtonText, String subtitle)
      Constructs a new context menu choice with the provided properties and appends it to the extraChoices list. The answer is used both as the postback value and as the title of the choice. The new extra choice will be shown along with the next question.
      Parameters:
      answer - the postback value sent when the choice is selected and also used as the choice title
      visibleText - the text shown to the user for this choice
      fileKey - the associated file key
      url - an optional URL linked from the choice
      urlButtonText - the label for the URL button
      subtitle - secondary descriptive text displayed under the title

    • addExtraChoice

      void addExtraChoice(String answer, String title, String visibleText, String fileKey, String url, String urlButtonText, String subtitle)
      Creates a new context menu choice with the given properties and adds it to the extraChoices list. The new extra choice will be shown along with the next question.
      Parameters:
      answer - the postback value sent when the choice is selected
      title - the title of the choice
      visibleText - the text shown to the user for this choice
      fileKey - the associated file key
      url - an optional URL linked from the choice
      urlButtonText - the label for the URL button
      subtitle - secondary descriptive text displayed under the title

    • addExtraChoice

      void addExtraChoice(String answer, String title, String visibleText, String fileKey, String url, String urlButtonText, String subtitle, String altText) throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Creates a new context menu choice with the provided properties, validates the alternative text length, and adds the choice to the extraChoices list. The new extra choice will be shown along with the next question.
      Parameters:
      answer - the postback value sent when the choice is selected
      title - the title of the choice
      visibleText - the text shown to the user for this choice
      fileKey - the associated file key
      url - an optional URL linked from the choice
      urlButtonText - the label for the URL button
      subtitle - secondary descriptive text displayed under the title
      altText - alternative text for accessibility; must not be null and its length must be less than or equal to MAX_ALT_TEXT_LENGTH
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - If altText exceeds MAX_ALT_TEXT_LENGTH characters

    • addExtraCard

      void addExtraCard(String title, String text)
      Creates a new card with the given title and text (wrapped in a paragraph tag) and adds it to the extraCards list.
      Parameters:
      title - the title of the card
      text - the body text; it will be wrapped as HTML inside a <p> element

    • setPath

      void setPath(Integer path)
      Sets the path to be followed according to the script's intended direction.

      This method updates the internal path value, which should align with the logical path defined by the running script.

      Parameters:
      path - the path identifier representing the route the script is meant to follow

    • cancelOutcome

      void cancelOutcome()
      Cancels the current outcome and places the user back to the "start". Current conversation is closed and new one will begin from user's next message. Only remembered variables will be kept.

    • restartOutcome

      void restartOutcome()
      Send the user back to the start of the current outcome. It will still be the same conversation as before so all variables will be kept etc.

    • switchOutcome

      void switchOutcome(int outcomeId)
      Send the user to a different outcome. It will still be the same conversation as before so all variables will be kept etc.

    • populateTextVariables

      String populateTextVariables(String text)
      Finds variables in the text (e.g. ${variable1}) and replaces them with their stored values.
      Parameters:
      text - script to search for variables and replace with their value.
      Returns:
      the updated text with the variables replaced.

    • getConversationHistory

      String getConversationHistory() throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Retrieves the stored reporting data for the Conversation the script is being executed on.

      Contains details such as messages, stored variables, notifications, etc.

      Conversation history will only be available when the conversation has ended (i.e. end of conversation script), and the conversation is a production conversation.
      Returns:
      a JSON serialised representation of the conversation's history.
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - There was an error retrieving the conversation history

    • prepareHttpCall

      HttpCallable prepareHttpCall(String url)
      Creates and prepares an HTTP call for the specified URL
      Parameters:
      url - the target URL for the HTTP call
      Returns:
      a configured HttpCall instance ready for execution

    • getCache

      SyndeoCache getCache()
      Returns the current SyndeoCache instance.
      Returns:
      the cache, or null if it has not been initialized

    • getProperties

      ScriptProperties getProperties()
      Returns the current ScriptProperties instance.
      Returns:
      the script properties, or null if they have not been initialized

    • xmlToJson

      String xmlToJson(String xml) throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Converts XML string to JSON.
      Parameters:
      xml - the XML string to convert
      Returns:
      JSON string representation of the XML data
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - There was an error converting the XML to JSON

    • getIntents

      List<List<IntentResult>> getIntents(String input) throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Function that analyses a sentence for Intents. This will return a List of Intents each with a given score. The input is broken into sentences with each sentence analysed separately. The first list is a list of sentence scoring, the second list is the list of intent scoring on the given sentence. Consequently, if only 1 sentence is detected in the input, then the first list will be of size 1.
      Parameters:
      input - , the sentences to be analysed for intents.
      Returns:
      The types of intent detected in a sentence, each with a given score indicating relevance to the sentence.
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - There was an issue retrieving the intents for input, such as failure to contact remote service.

    • newLLMChat

      String newLLMChat(String llmConfigName) throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Function that initialises new Chat with a configured LLM. This will return a unique ID for the new chat session, as a string. This is typically used when Flow-Guided mode is disabled.
      Parameters:
      llmConfigName - , name of LLM Configuration.
      Returns:
      String Unique ID associated with the new Chat session, as a String.
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - There was an issue creating the LLM session, such as failure to contact remote service.

    • newLLMChat

      String newLLMChat(String llmConfigName, Map<String,Object> parameters) throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Function that initialises new Chat with a LLM. This will return a unique ID for the new chat session, as a string. This is typically used when Flow-Guided mode is disabled.
      Parameters:
      llmConfigName - , name of the LLM Configuration
      parameters - , additional parameters to be used when initialising the new Chat
      Returns:
      String Unique ID associated with the new Chat session, as a String.
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - There was an issue creating the LLM session, such as failure to contact remote service.

    • sendMessageToLLM

      String sendMessageToLLM(String chatSessionId, String message) throws cx.syndeo.scripting.exceptions.SyndeoScriptingException
      Send message to the LLM Session specified by the LLM Chat Session ID. This will return the LLM's response to the message.
      Parameters:
      chatSessionId - , String Unique ID for each LLM Chat
      message - , String message to be sent to the LLM
      Returns:
      String response from the LLM
      Throws:
      cx.syndeo.scripting.exceptions.SyndeoScriptingException - There was an issue sending the message to the LLM, such as failure to contact remote service.

    • getCompanyId

      int getCompanyId()
      The unique ID representing the current company in the Syndeo platform.
      Returns:
      company ID.

    • getUniqueUserId

      Long getUniqueUserId()
      The unique ID representing the conversation's user in the Syndeo platform.
      Returns:
      unique user ID.

    • getPlatform

      String getPlatform()
      The name of the messaging or voice platform through which the conversation is currently taking place.
      Returns:
      Platform name.

    • getConversationId

      Long getConversationId()
      The unique ID representing the conversation on the the Syndeo platform.
      Returns:
      conversation ID.

    • isTest

      boolean isTest()
      Whether the conversation is taking place in a test channel.
      Returns:
      is test version.

    • log

      void log(String message, Object... objects)
      Logs a message and interpolated objects with log level INFO. Will also log to Splunk if enabled.

      Via script, the log level can be set by appending to the log method. 

      
     var intro = "Hello world";
     syndeo.log("{}, welcome to Syndeo", intro);       // No log level set, defaults to INFO
     syndeo.log.trace("{}, welcome to Syndeo", intro); // Log level method TRACE

      Supported levels are [trace|debug|info|warn|error]

      Parameters:
      message - The message to log. Placeholders {} can be used to interpolate objects.
      objects - The objects to interpolate into the message.

    • getRandomUUID

      String getRandomUUID()
      Generates a random UUID
      Returns:
      UUID as a string

    • checkScheduleStatus

      String checkScheduleStatus(String scheduleName)
      Identifies the current status of a Schedule, identified by its display name.

      There are 4 possible schedule statuses:

      • OPEN
      • CLOSED
      • HOLIDAY
      • UNKNOWN - If an invalid schedule name is provided.

      This function checks the schedule status for the current time.

      Parameters:
      scheduleName - The name of the Syndeo Schedule to check
      Returns:
      A string representation of the schedule status

    • checkScheduleStatus

      String checkScheduleStatus(String scheduleName, Long epochMilliTime)
      Identifies the status of a Schedule, identified by its display name.

      There are 4 possible schedule statuses:

      • OPEN
      • CLOSED
      • HOLIDAY
      • UNKNOWN - If an invalid schedule name is provided.

      This function checks the schedule status for the time provided, which may be in the past or future.

      Parameters:
      scheduleName - The name of the Syndeo Schedule to check
      epochMilliTime - The epoch millisecond time to check the status of
      Returns:
      A string representation of the schedule status