Your Logic Actions

Your Logic implementation sends the request to https://api.eu.salted.cx/api/v1/live/your-logic endpoint that contains account ID and conversation PID.

https://api.eu.salted.cx/api/v1/live/your-logic/accounts/{accountId}/conversations/{conversationPid}

Each call to this endpoint MUST contain shared secret in the Authorization header. Each response that does not contain the header or contains unexpected value is ignored and no action is taken.

Authorization: Bearer <shared secret>

Reach to Salted CX to retrieve the token for your account.

Control (Upcoming)

Control enables you to modify the default Salted CX behavior for processing the participant actions. Control enables Your Logic to deal with asynchronous communication, provide faster responses to customers and optimize costs by processing less incremental requests.

{
	"requestId": "a9c9f343-8a80-43f5-a6b2-d61cc06d4d1d",
	
	"control": {
		"skipToTime": "2025-04-15T18:15:51Z",
		"skipToLatest": true,
		"ignoreOnCustomerAction": true,
		"ignoreOnAgentAction": true
	}
}

Response without Request

You can also send responses unrelated to any specific requests. In this case you have to reference a conversation. A good example would be a very long running background task that needs to be completed or some action you perform after an timeout unless it is canceled during the conversation.

Responses without requests can contain exactly the same actions as the responses related to a request. The conversation is identified by the Conversation PID in the endpoint URL path; simply omit the requestId from the body.

{
	"actions": [
		{
			"type": "MESSAGE",
			"content": "Your travel plans have been confirmed with all the travel agencies. Here is your itenerary https://demoadventures.com/trips/1679287. Have a nice trip!"
		}
	]
}

No Actions

Empty list of actions means that Salted CX will do nothing as the response. You SHOULD send empty responses to tell Salted CX that it can move forward with the conversation and send the next event into Your Logic if there is any. Sending this event as soon as possible is important for reducing latency.

{
	"actions": [
	]
}

Send Message

This response sends a message that is visible to a customer.

Basic Text Message

{
	"actions": [
		{
			"type": "MESSAGE",
			"content": "Would moving the booking to this Friday at 17:00 work for you?"
		}
	]
}

Text Message Opening a Knowledge Article (Upcoming)

This action creates a new message that opens a knowledge base article in the chat window directly. The link and openLinkIn properties are not supported yet.

{
	"actions": [
		{
			"type": "MESSAGE",
			"content": "Learn about Live Conversations",
			"link": "https://help.salted.cx/en/collections/1755577083-live-conversations",
			"openLinkIn": "Chat"
		}
	]
}

Send Email Message

Email has a dedicated action with email specific properties:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "actions": [
    {
      "type": "EMAIL",
      "contactPid": "550e8400-e29b-41d4-a716-446655440001",
      "subject": "Your requested document",
      "body": "Please find the requested document attached.",
      "attachments": [
        {
          "path": "<path to media uploaded to previously>",
          "name": "document.pdf",
          "mimeType": "application/pdf"
        }
      ]
    }
  ]
}

Attachments

To send an attachment, first upload a file to Salted CX and then reference it in the EMAIL action. You can include multiple attachments in a single email. You have to first upload them all. You upload the file in two steps:

Obtain Upload Link

Send a POST request with an empty body to the /api/v1/live/media/accounts/{accountId}/upload-url endpoint. You will retrieve two properties:

s3PresignedUrl — The URL to which you perform the upload.

path — The path to use in the EMAIL action to attach the dashboard.

Upload the file

Send a PUT request to the s3PresignedUrl URL with the body containing the attachment data and the Content-Type header set to the attachment's mime type.

Send WhatsApp Template Message

Prepared reply is currently specific for WhatsApp. This will change in the future to make it channel independent. Currently you must have a template in WhatsApp that is approved for outbound.

When updating templates in Meta we strongly encourage to create a new template and then switch Your Logic to use the new template.

Sends an approved WhatsApp template to the customer. This enables to start outbound conversations from Your Logic. Prepared messages are picked from the existing approved templates and can be customized using variables.

{
  "actions": [
    {
      "type": "WHATSAPP_TEMPLATE",
      "templateName": "offer_help_named_params",
      "language":{"code": "en"},
      "parameters": {
        "customer_name": "Adam",
        "discount_value": "6",
        "questions_reference" : "serving lunch"
      }
    }
  ]
}

Needs Help

Ask for help makes the conversation appear in inbox for the agents. Your Logic still receives all the requests during the communication. However agents can join the conversation and help with its resolution.

{
	"actions": [ 
		{
			"type": "NEEDS_HELP",
			"needsHelp": true
		}
	] 
}

Save Note

This response saves a note that is only visible to agents, external agents but invisible to customers.

{
	"actions": [
		{
			"type": "NOTE",
			"content": "It is unlear what it our policy for Switzerland.",
			"responseTo": "<uuid>"
		}
	]
}

Send File

This action sends a file to a user. Before triggering the action, you must first call the API, which returns an upload URL and file path. After uploading your file to the provided URL, you can then trigger the action using the file path from the API response.

https://api.eu.salted.cx/api/v1/live/media/accounts/[ACCOUNT]/upload-url

Each call to this endpoint MUST contain shared secret in the Authorization header.

Authorization: Bearer <shared secret>

{
	"requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"actions": [
		{
			"type": "SEND_FILE",
			"path": "/path/that/you/retrieved/from/our/file/service.extension",
			"name": "invoice.pdf",
			"content": "Invoice for Order #739281",
			"mimeType": "application/pdf"
		}
	]
}

Ask Question

This action sends a question to the target participant. You can use any Question PID in Salted CX. To find out what is the question PID for a given question open the question in Salted CX and copy its PID from the browser address bar.

Salted CX translates the question to visualization of the target platform. In Universal Chat it shows a list of buttons to choose from. On WhatsApp it creates either a list of buttons or a list depending on the number of possible answers.

{
	"requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"actions": [
		{
			"type": "QUESTION",
			"questionPid": "36c8f00c-44c9-4633-bfa7-2f3a3b51c1df"
		}
	]
}

You can also ask questions to an agent. This is useful for giving agents closed set of options to choose from and make the process more unified.

{
	"actions": [
		{
			"type": "QUESTION",
			"allowedToRespond": ["AGENT", "EXTERNAL_AGENT"],
			"allowedToView": ["AGENT", "EXTERNAL_AGENT"],
			"allowCustomReply": false,
			"questionPid": "<Salted CX question PID>",
			"note": "What should the user take into consideration when answering this question."
		}
	]
}

See Answer how to listen for answers when participants click on them.

Customer Facing Questions

The questions that you ask the customers are translated into the communication platform. The below example shows a question asked to a customer in the Universal Chat. Depending on the preferences you allow the customers to provide a custom answer.

Agent Facing Questions

Agent facing questions enable you to guide agents through decisions.

Ask Dynamic Question

Asking a dynamic question enables you to give customers and other participant dynamically generated choices without the need for a question created in Salted CX. This enables you to have question and answers that take context into consideration. Answers to these questions are not in reporting but are visible in the customer journey. The action supports the same optional properties as Ask Question (allowedToRespond, allowedToView, allowCustomReply, note, reviewEngagementPid, channel, contactPid, content, emailSubject), plus question.shouldCreateReview (Boolean, default false). Currently shouldCreateReview must stay false for dynamic questions — a QUESTION_DYNAMIC action with shouldCreateReview: true is rejected and fails the whole request. Use the QUESTION action with a question defined in Salted CX when the answer should create a review.

When a participant choses an answer you will get the answer in a request sent to Your Logic so you can react to customer clicking on any of the options.

{
  "actions": [
    {
      "type": "QUESTION_DYNAMIC",
      "question": {
        "externalId": "question1",
        "content": "What is your preffered time slot?",
        "answers": [
          {
						"externalId": "16-00",
						"content": "16:00 to 16:30"
					},
					{
						"externalId": "16-30",
						"content": "16:30 to 17:00"
					},
					{
						"externalId": "17-00",
						"content": "17:00 to 17:30"
					}
        ]

      }
    }
  ]
}

See Answer how to listen for answers when participants click on them.

Update Conversation

Updates conversation properties. Property values are then propagated to individual engagements when they are completed. The top-level properties (language, urgency, custom, info, serviceExternalId, serviceSourceId, desktop) sit directly on the action. All attribute pairs listed below must be nested inside an attributes object — see the example. Field names are case-sensitive.

Property names that end with externalId reference entities that are reportable in analytics. External ID is the stable ID that you can use to reference the entity. If the entity already exists in analytics, users will see its user-friendly display name. If the entity is not available in analytics, it will be created with the External ID as a user-facing name (fallback). You can use the Ingest API to import user-facing values and other attributes for the entity.

Property names that end with sourceId enable to reference leaf entities imported from other data sources. For example if you have queues in a legacy contact center platform that you want to use within Live Conversations you use the sourceId of that legacy platform to reference the same same queue.

Desktop

The desktop object controls what agents can see and do in the agent desktop for this conversation. Each update replaces the whole stored desktop configuration — always send the complete object, not a diff. Elements you do not mention keep their default behavior (visible and enabled).

Statuses are case-sensitive: Disabled shows the element but prevents its use, Hidden removes it from the desktop. Items with a missing id or an unrecognized status are dropped from the update.

{
  "actions": [
    {
      "type": "CONVERSATION_UPDATE",
      "desktop": {
        "defaultReply": {
          "title": "Suggested reply",
          "subject": "Your order",
          "message": "Hello, thank you for reaching out about your order."
        },
        "actions": {
          "resolve": { "status": "Disabled" },
          "inviteExternal": { "status": "Hidden" }
        },
        "customActions": [
          { "id": "refund", "status": "Hidden", "title": "Issue Refund" }
        ],
        "attributes": [
          { "id": "orderNumber", "status": "Disabled" }
        ]
      }
    }
  ]
}

Attributes

The following reporting attributes are sent nested inside the attributes object of the action — not at the top level. All of them are optional strings (max 100 characters); only the fields present in the payload are updated.

{
  "actions": [
    {
      "type": "CONVERSATION_UPDATE",
      "language": "en",
      "urgency": 1000,
      
      "attributes": {
	      "attribute01ExternalId": "Example Value 1",
	      "attribute01SourceId": "d0a1b2c3-0000-0000-0000-000000000001",
	      "attribute02ExternalId": "Example Value 2",
	      "attribute03ExternalId": "Example Value 3",
	      "attribute04ExternalId": "Example Value 4",
	      "caseExternalId": "Case ID",
	      "language": "en",
	      "menuPathExternalId": "main-customer-support",
	      "outcomeExternalId": "escalated-to-agent",
	      "queueExternalId": "queue-id",
	      "queueSourceId": "d0a1b2c3-0000-0000-0000-00000000000b",
	      "priorityExternalId": "High",
	      "reasonExternalId": "Custom Reason",
	      "reasonCategoryExternalId": "Custom Reason Category"
      },
      "info": [
	      {
		      "title": "Memos",
		      "text": "Holidays opening times for the partner: 9:00AM to 12:00PM"
	      },
	      {
		      "title": "Menu",
		      "url": "https://knowledgebase.company.com/article123",
		      "text": "Holidays opening times for the partner: 9:00AM to 12:00PM"
	      }
      ],
      "serviceSourceId": "56710d6f-72d2-658c-eefc-92554e59dead",
      "serviceExternalId": "YOUR-EXTERNAL-ID",
      "custom": {
	      "customer_name": "Adam",
	      "orderNumber": "ORDER-123",
	      "allOrdersInProgress": [
		      "ORDER-245",
		      "ORDER-982"
	      ]
      }
    }
  ]
}

Update Customer

Updates custom customer properties. Note: the CUSTOMER_UPDATE action currently supports only the attribute fields listed below — contacts and custom are not yet supported on this action and are ignored. All properties are composed by two parts:

• <property name>ExternalId — The identifier of the entity in an external system.

• <property name>SourceId — The identifier of an external system, as a UUID. This ID is provided by Salted CX upon request. A SourceId value that is not a valid UUID fails parsing of the whole request.

These two parts enable to solve collisions of IDs between individual systems.

You can use custom attribute to store up to 1kB of custom object associated with the customer. This enables you to keep information related to the customer in Salted CX without having to maintain this information in Your Logic. This enables to handle some scenarios more easily — such as as restarting or upgrading your service.

We take the value of the custom attribute as-is. The custom attribute value has to be a valid JSON value to be parsed successfully. Beyond this requirement and size limitation we do not do any validation of the value. The custom object can contain any inner structure.

We do not process the content of the object in any way. Your Logic implementation is responsible for providing complete object with all values set to the latest state.

Your Logic has to be able to handle multiple parallel conversations from the same customer. While we ensure that we will sequence all requests for individual conversations we do no sequence requests for customers. Customers can be involved in multiple conversations by simply emailing you and chatting at the same time about different topics. Make sure you handle race conditions when updating the customer data. Multiple conversations can update it and read it in parallel. We keep the last value it receives as a whole. We do not resolve any conflicts nor do partial updates.

{
	"requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"actions": [
		{
			"type": "CUSTOMER_UPDATE",
			
			"countryExternalId": "de",
			"segmentExternalId": "enterprise"
		}
	]
}

Start Conversation

Starts a conversation from your logic using the selected channel.

{
  "actions": [
    {
      "type": "CREATE_CONVERSATION",
      "conversation": {
        "channelVendor": "EMAIL",
        "brandPid": "8a1b2c3d-0000-0000-0000-000000000001",
        "languageCustomer": "cs"
      },
      "customer": {
        "displayName": "Carol",
        "contact": {
          "contactType": "Phone",
          "contact": "+1098765431"
        },
        "relatedContacts": [
	        {
		        "contact": "+420123456789",
			      "contactType": "Phone"
	        },
	        {
		        "contact": "CUSTOMER-12345",
		        "contactType": "Custom"
	        }
        ]
      }
    }
  ]
}

{
	"actions": [
		{
			"type": "START_CONVERSATION",
			
			"customer": {
				"displayName": "Radek",
				"contact": {
					"contactType": "Phone",
					"contact": "+1234567890",
				}
			},
			"conversation": {
				"channelVendor": "WhatsApp",
				"companyContact": "+1800111222333",
				
				"custom": {
				}
			}
		}
	]
} 

Invite External Agent

This action sends an invite to an external agent to join the conversation. The external agent will receive a notification (email) with link authorizing them to access the conversation.

{
  "actions": [
    {
      "type": "INVITE_EXTERNAL_AGENT",
      "email": "[email protected]",
      "name": "Agent Name",
      "subject": "Help with order",
      "message": "Hello, I need assistance with order from your shop.",
      "expires": "2025-07-29T10:30:00Z"
    }
  ]
}

Customize External Invites (Upcoming)

Enables you to list email addresses that agents are enabled to invite into a conversation. This enables to offer these emails to the agent and also restricts their options. These restrictions do not apply to Your Logic.

{
	"actions": [
		{
			"type": "CONVERSATION_UPDATE",
			
			"conversation": {
				"externalAgents": {
					"inviteSubject": "Help us with the Customer",
					"inviteMessage": "Hello, how are you?",
					
					"allowCustomization": false,
				
					"allowCustomEmails": true,
					"allowed":[
						{ 
							"name": "Partner",
							"email": "[email protected]" 
						},
						{
							"name": "Partner - VIP", 
							"email": "[email protected]",
						}
					]
				}
			}
		}
	]
}

Complete Engagement

This action enables you to tell that the engagement is considered complete.

{
  "actions": [
    {
      "type": "ENGAGEMENT_COMPLETE",
      "engagementPid": "582fa5da-d423-46ae-b69f-aa1d2b01f736",
      "name": "Engagement Outbound #2",
      "outcomePid": "c8b61d87-6fe4-44e2-a419-bbc0963f58f2",
      "outcomeType": "AGENT_RESOLVED",
      "cost": 0.6
    }
  ]
}

Complete Conversation

This action completes the conversation and all of its engagements (if there are any). Complete conversation action has no properties.

{
	"actions": [
		{
			"type": "CONVERSATION_COMPLETE"
		}
	]
}

Completing conversation is an indicator for the customer that the conversation is completed. However customer, bots and agents can contribute to a completed conversation and change its status to in progress again.

Engage Your Logic

In case Your Logic no longer wants to be included the conversation in any way it can let Salted CX know by setting the property engageYourLogic to false. From this moment Your Logic will receive no updates regarding this conversation.

You can also switch the flag to true when sending it without responding to any Your Logic event (as you will receive them). For example Your Logic can be performing a time consuming operation, ask not to receive events, after performing the operation it can return back and ask to be notified about the conversation again.

{
	"requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"actions": [
		{
			"type": "ENGAGE_YOUR_LOGIC",
			"engageYourLogic": false
		}
	]
}

Navigate to Page (Upcoming)

This action enables to navigate a user to the provided web page when using the Universal Chat. This enables you to guide a user through a process in a more intective way.

When using a channel that does not support automatic navigation. Salted CX uses an alternative behavior such as showing a button that opens the target page.

{
	"requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"actions": [
		{
			"type": "NAVIGATE_TO_PAGE",
			"target": "help_123",
			"url": "https://help.salted.cx/article/to/navigate/to",
			"title": "Read the help article"
		}
	]
}