The Open Source Salted CX Conversations SDK is the easiest way to build and maintain automated conversations. The Conversation SDK seamlessly integrates with Salted CX’s Your Logic and leverages all features available in Salted CX, including handover to agents and powerful analytics.

Salted CX brings Conversations as Code to seamlessly fuse rule-based logic with the power of generative AI and guidelines described in the knowledge bases. Your Conversations as a Code are in a single place that fuses all your knowledge and business rules with the customer experience.

Your First Conversation

You can use your favorite programming language to respond to customer and agent activity. In the code snippet below we show example of reposting to a customer. For more details on how Conversations as a Code look like see Your First Conversation article.

// if there is already a human agent, do nothing
if (isAgentEngaged())
	return;

// if the converastion waits for an agent, just let the customer know
if (isWaitingForAgent()) {
	tell("Give us a few moments. My human colleague will join soon.");
	return;
}

// otherwise tell out bot is new here ...
tell("I am new here and still learning. Let me tranfer you to my human colleague. 😉");
	
// ... and ask human agents for help
askForHelp();

Bridge Between Business and Engineering Worlds

Conversations SDK aims to provide an API that is easy to read, even for business people without strong technical skills, so they have visibility into their processes as they really are. The programming language can naturally hide complexity behind methods, exposing the right amount of information at the right level.

Exact Rules

You can use exact rules to make decisions when handling the conversation. These are not different from programming in any other language. While the rules can be on the highest level, the complexity of the actions can be hidden in methods.

if (refundValue < 100)
  issueRefund();
else
	askForHelp();

Maintain State

You can easily remember what happened in the conversation in the past and use it later in the conversation, so you do not have to re-retrieve data.

if (message.isAbusive()) {
	badBehavior.increment();
	
	if (badBehavior.get() >= 3) {
		tell(Reply.End_due_to_Abuse);
		muteConversation();
	}
} 

Reasoning

We strongly encourage using exact rules for decisions whenever possible to make conversations faster, cheaper and more predictable. However, sometimes you need to understand what the customer says to make a decision.

if (askYesNo("Is there a high risk the customer will cancel the contract?") 
	|| askYesNo("Does customer mention a potential legal issue?")) {
	
  askForHelp();
}

Choose Knowledge for Response

If your bot mostly provides an information

// for every conversation we include refund policy if most of the covnersations are about refunds
usePage("https://demoadventures.com/refund-policy");

// we include information about pricing based on country
if ("US".equals(country)) {
	use("The prices do not include taxes.");
else
	use("The prices include taxes.");

// we include special instructions for treating VIP customers if the customer is VIP
if (vipCustomer)
	useNotion("https://notion.com/demoadventures/");
	
// this tries to use the provided knowledge so far and tries to respond to the customer based on the conversation
var attempt = tryToRespond();

// if the attempt to respond based on the provided content is not successful, we escalate to agents
if (attempt.notSuccessful())
	askForHelp();

Hidden Complexity

Conversations SDK provides implementation for commonly used patterns in the contact center, so you do not have to reinvent the wheel. For example, tryRespondUsingKnowledgeBase tries to determine which questions were not answered yet using an LLM. Then queries the knowledge base for content that may be related to the questions. Then it uses the LLM to formulate the answers to the questions.

var attempt = tryRespondUsingKnowlegeBase();

if (attempt.allQuestionsAnswered())
	askQuestion(Confirm_Resolution);
else
  askForHelp();

Slower Growth in Implementation Complexity

We always highly encourage reducing your business and process complexity before implementing anything, including your bot. However, there is often a point in reducing your process complexity that you cannot go beyond. This can be caused by objective factors, but also by differing opinions of stakeholders.

Conversations SDK is built on top of Live Conversations and Your Logic, providing additional convenience features so you do not have to work with JSON or process individual events. You can focus on delivering the best customer experience and the most efficient, automated business processes.

Conversations SDK and the entire stack underneath are designed for people who are not senior DevOps engineers. We empower engineers to focus on their code and remove as much operational complexity as we can.

Features provided by Live Conversations and Your Logic:

• Fallback to agents. When your bot does not know what to do next it is very easy to ask agents to take over the conversation. Salted CX also automatically asks agents for help if your implementation experiences issues or is unavailable.

• Web chat widget. Web chat widget to talk to your customers that handles all the major browsers, remembers sessions and gets updated with new updates of major operating systems and browsers so you do not have to care.

• Unification of channels. You handle conversations in a unified way no matter whether they are web chats, emails, WhatsApp, etc. All the complexities of the individual channels and platforms are handled by us. You can have different business behavior for individual channels but technically you handle them in a unified way.

• Translations. You focus on handling conversations in a single language. Incoming and outgoing messages get automatically translated.

• Stateless-friendly. Your code that handles the conversations can be completelly stateless if you want. You can store state data related to conversation to Salted CX and you will receive them when a next action happens.

• Survive short downtimes in your implementation. Your Logic helps you survive short unavailability of your code for a brief period of time. This enables you to do application updates even without complex support for downtime-free upgrades.

• Sequencing of events for conversations. You do not have to care about complexity of processing two customer messages in the same conversation in parallel.

Features provided by Conversations SDK on top of the above:

• Converting JSON data to convenient objects and vice versa. You do not have to parse and process JSONs. Instead you have convenient objects that have features that you most commonly need to handle teh customer conversations.

• Integration with AI. The Conversations SDK provides easy and natural integration with AI so you can take naturally integrate reasoning with deterministic rules and you can combine static polished messages with generated ones.

• Glass Box. The Conversations SDK does as little or as much for you as you want and enables you to customize its behavior on every level. You have a great starting point to get a bot out of the gate quickly with absolute freedom where to take from there. No strings attached.

• Integration into runnable environments. Conversations SDK enableys you to quickly get a runnable implementation of Your Logic information. You can use lightweight server or easily deploy the conversation to AWS Lambda.

• Logging and data collection.

Use Your Engineering Talent and Environment

Conversations SDK enables you to write Conversations as a Code in major programming languages such as TypeScript and Java. This enables you to build the customer experience using the engineers you already have in the development and runtime environment you already have.

Version Control. You can use your existing version control system, such as GIT, to manage changes, perform rollbacks, and work on new versions of your conversations.

Code Reviews. You can use your existing workflow for ensuring code quality, such as code reviews.

Continuous Integration. You can run a battery of tests before deploying each change to ensure there are no significant regressions or that the new functionality behaves as expected.

Use AI to Build AI

The AI is getting better in coding every day. Take advantage of AI to kickstart building your conversation. AI can quickly convert your description of the customer experience into robust code that ensures consistent execution of automated conversations in Salted CX.

Testing Toolkit

Unlike traditional code that is always deterministic, AI responses are not. The Conversation SDK provides testing utilities to help you test AI and reduce the risk of unexpected behavior and regressions.

You can test whether the change of your AI model, your change of prompts, or flow changes has not caused a regression in the test suite you have. Whenever you encounter AI behavior that is unsatisfactory, and you want it improved in the future, add it to the test suite to ensure it is resolved in the next release and does not regress.

public class DemoAdventurelInsuranceTest extends SingleConversationTest {

	public DemoAdventurelInsuranceTest() {
		super(10, // Number of attempts
				  90, // Required success rate in percentages
				  DemoAdventuresConversation::new, // Conversation we will test
					transcript() // Create a mock conversation
							.bot("Hello, how can I help you?")
							.customer("Hello, is the travel insurance included?"));
	}

	protected void testResponse(TestedResponse response) {
	  // we want to ensure bot has not escalated to agent
	  assertFalse(response.needsHelp());
	  
		// we want bot to reply in a single message
		assertEquals(1, response.messages().count());
		
		// we want bot to start with clear answer, followed by explanation (thus space in after period)
		assertTrue(response.messages().startsWith("Yes. "));
		
		// we want to be sure that the answer explicitly contains "included"
		assertTrue(response.messages().containsAllIgnoreCase("included"));
		
		// we can also use the AI to double check the AI
		assertTrue(response.askYesNo("The bot confirmed that the insurance is included in the price."));
	}
}

As generative AI is inherently non-deterministic, even when you have some buffer in the number of successes, the test may still occasionally fail. You should balance the number of required successes with the time you want to invest in reviewing the failed tests. Note that the boundaries are primarily intended to detect significant performance degradation.

Bring Your Own AI

The Conversation SDK lets you choose which AI model or service to use. You can even use multiple AI models for different use cases to balance response speed, cost, and reliability. You can use a sequence of LLMs.

AISetup.easyTasks(new Fallback(
	new Ollama(Ollama.PHI), 
	new OpenAI("SECRET_TOKEN", "gpt-4.1-mini"));
AISetup.normalTasks(new OpenAI("SECRET_TOKEN", "gpt-4.1-mini"));
AISetup.complexTasks(new OpenAI("SECRET_TOKEN", "gpt-5.1"));

Provide the Response Piece by Piece

You can contribute to the reply to the customer in multiple parts of the conversation.

// add greeting if we know we have not greeted yet
if (!greeted.get()) {
	greeted.true();
	tell("Hello?");
}

// if we do not know what customer is asking
if (!theCustomerRequestIsKnown())
	tell("How can help you?");
else {
	// depending on the metadata we tell what knowledge we will use to respond to customer questions
	if (product.category == TOYS_UNDER_14)
		use(Knowledge.ToysUnder14);
	
	if (product.country == US)
		use(Knowledge.ProductsInUs);
	else
		use(Knowledge.ProductsInternational);
	
	var attempt = tryAnsweringUsingContent();
}

Start Easily

The Conversation SDK is designed to handle common conversation patterns with ease, offering complete flexibility for future conversation handling.

public void customerMessage(Message message) {
	// a message towards the customer
	tell("Hello, I am new here and need more time to be useful. I will ask my human colleagues for help. Please give them few moments to join.");
	
	// a note visible only to agents
	note("Please help the customer.");
	
	// ask agents to join the conversation and attend to the customer
	askForHelp();
	
	// tell we do not want to be notified about future activity in the conversation
	disengage();
}

if (allCustomerQuestionsAreAnswered()) {
	// we answered everyhing, lets ask the customer it is really the case
	askQuestion(Questions.Have_We_Resolved_Your_Request);
}
else {
	// still some work to do
}

if (customer.isAngry()) {
	// we ask for a human agent to be engaged
	askForHelp(); 
}

var nextStep = tryRespondUsingContent(
									webPage("https://help.company.com/article/123");
if (nextStep == Retry) {
	// fallback when the answer is on the web page
}

var questions = customer.unansweredQuestions();
note("The customer questions that still need and answer:" 
			+ newLine() 
			+ unorderedList(questions));
askForHelp();

Your Logic Only versus Conversations SDK

The world is complex, the business is complex.

Request Handling in Your Logic

Request Using Conversations SDK

If using the Conversations SDK, much more work is done for you.

Knowledge Base and Web Content

The Conversation SDK offers built-in support for connecting to a knowledge base, enabling RAG (Retrieval Augmented Generation) to respond to customers based on a vast volume of knowledge specific to your business.

Using knowledge bases and content from your website or other web-based applications enables you to resolve a large volume of customer requests without using a complex rule-based logic. This lets you focus on cases that are hard to describe in your knowledge base or require interaction.

var responseAttempt = tryRespondingUsingKnowledgeBase();

if (responseAttempt.unableToAnswerCustomerQuestion()) {
	// alternative handling of the conversation
}

Full Power of Your Programming Language

Conversation SDK empowers you without restricting you to a proprietary tool or language that has numerous limitations. You can use your programming language to integrate with your services, querying them for information or triggering actions.

var availableTimeSlots = yourCompanyBookingService.listFreeTimeslots();

question("Please pick the timeslot that works for you.", availableTimeSlots);

Easy to Read for Stakeholders

While the Conversation SDK is targeted at engineers, we also aimed to make it readable for other stakeholders so they can understand why the bot behaves the way it does. This enables closer collaboration among engineers, product managers, customer experience professionals, and others.

You can involve other stakeholders to modify canned responses and AI instructions.

public enum CannedReplies implements Expression {

	// Unwanted behavior
	Hacking_Attempt_Reply("To continue your hacking attempts please share your credit card details so we step up the game! :)"),

	// Esclalations
	Talk_to_Agent_Refuse("I'm sorry. Our agents are busy attending to customers who need help with their bought."),

	// Deal Conversation
	No_Answer_in_Knowledge_Base("Unfortunatelly, I could not find the answer for your question. Try to contact the merchant directly."),

	// Give up resolution
	Give_Up("I am trying, but I have trouble helping you. Please reach directly to the travel agent."),

	// Feedback to agent
	Note_Action_Not_Supported("The action is currently not supported.")
	;
	
	// the rest of the code is here
}

Instruction.Abusive = "";

Versioning

You can manage Conversations as Code using powerful existing tools such as Git. This enables you to iterate on the user experience with confidence, knowing that you can always roll back. You can also establish a process for publishing changes that includes code reviews. You can use branches to develop major upgrades in parallel to doing small increments on the existing experience.

Optimizing Resources

The Conversations SDK uses aggressive caching and enables you to use different AI model for different tasks based on their complexity to shield you from the chore of managing costs.

Optimizing the use of resources also improves response times and enables handling more conversations on the same hardware.

Raw Your Logic vs. Conversations SDK

Both Your Logic and Conversations SDK are useful for handling conversations with customers. As Conversations SDK is built on top of Your Logic, it provides everything Your Logic provides, plus extra features to get you started.

Conversations SDK is a great way to jump-start your development and have your first production-ready bot today.

Message Consolidation

When you try to respond to the customer, you can have multiple items you would like to tell the customer. However, there might be complex logic under which circumstances you want to tell something.

Content Selection

When AI generates replies to answer customer questions, it needs information that provides answers to the questions. Ideally, the AI receives as input the minimum information possible while not missing content that is important for answering the customer's question.

Missing information makes it impossible for AI to answer the customer question and increases the chance of hallucinations. Providing high volume of unnecessary information makes it harder for AI to answer the specific questions. Often it is not possible to provide all information because it is simply too many.

Rule-Based Content

You can use conversation metadata to choose which content to provide for a reply attempt.

Pros:

• Very fast decisions on what to include

Cons:

• Rules for knowledge inclusion may be complex and require manual maintenance

• Does not take into consideration the customer question

Static Content

You can use

if (purchases.containsCustomizedItem())
	use("Customized items cannot be refunded. Customer is warned before purchase as these products cannot be sold to somebody else.");
else
	use("All purchases can be refunded without stating a reason within 14 days since the purchase.");

Even when using static content we recommend to store these statements in a separate file as variables to have all knowledge easy to locate and manage in a single place.

if (customer.isVIP())
	use(Knowledge.Info_for_VIP_Customers);

Web Page Content

You can use content from a publicly accessible web page.

usePage("https://demoadventures.com/refund-policy");

if ("US".equals(customer.region))
	usePage("https://demoadventures.com/privacy-us");
else
	usePage("https://demoadventures.com/privacy-international");

Knowledge Base Content

You can also use the content from an internal knowledge base. Currently, Conversations SDK supports Notion.

use(knowledge.content("article-123"));

Specifically for Notion

Search-Based Content

You can use the knowledge base to search for content

useKnowledgeBase(knowledgeBase, search);