Your Logic Responses

Your Logic 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/[ACCOUNT]/conversations/[CONVERSATION]

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>

Control

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 requests. They have to contain Conversation PID instead of Request PID.

{
	"conversation": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
	"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 Action

Empty response means that Salted CX will do nothing as the response. You SHOULD send even 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": [
		{
			"type": "NO_ACTION"
		}
	]
}

Send Message

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

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

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.

Sends an approved WhatsApp template to the customer. This enables to start outbound conversations from Your Logic.

{
  "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 WhatsApp Template

This action is the currently specific for WhatsApp and requires to have an approved outbound template. In the future this action will be updated to abstract from the channel.

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

This action sends an outbound message to a customer. Prepared messages are picked from the existing peppered ones. They can be customized using variables.

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

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.

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

Ask Ad-Hoc Question

Asking ad-hoc 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 dynamically generated question. Answers to these questions are not in reporting but are visible in the reporting.

When the customer submits the 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 in case customers click on them.

Update Conversation

Updates custom conversation properties. You can use custom attribute to store up to 1kB of custom object associated with the conversation. This enables you to keep information related to the conversation 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.

{
  "actions": [
    {
      "type": "CONVERSATION_UPDATE",
      "custom": {
	      "customer_name": "Adam",
	      "orderNumber": "ORDER-123",
	      "allOrdersInProgress": [
		      "ORDER-245",
		      "ORDER-982"
	      ]
      }
    }
  ]
}

Update Customer (Upcoming)

Updates custom customer properties. 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. 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.

{
	"request": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"actions": [
		{
			"type": "CUSTOMER_UPDATE",
			
			"contacts": [
				{
					"type": "Phone",
					"contact": "+1234567890"
				},
				{
					"type": "Customer ID",
					"contact": "CUST-123456"
				}
			]
			
			"custom": {
				"totalBusinessValue": 4300,
				"predictedSpend1Y": 2100,
				"customerProgram": "Gold",
				"lastOrders": [
					{
						"orderId": "ORDER-1",
						"status": "Delivered"
					},
					{
						"orderId": "ORDER-2",
						"status": "In Progress"
					}
				]
			}
		}
	]
}

Start Conversation

Starts a conversation from your logic using the selected channel.

{
  "actions": [
    {
      "type": "CREATE_CONVERSATION",
      "conversation": {
        "channelVendor": "WHATSAPP",
        "languageCustomer": "cs"
      },
      "customer": {
        "displayName": "Radek Outbound",
        "contact": {
          "contactType": "PHONE",
          "contact": "+1098765431"
        }
      }
    }
  ]
}

{
	"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": "agent@company.cx",
      "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": "support@partner.com" 
						},
						{
							"name": "Partner - VIP", 
							"email": "vip@partner.com",
						}
					]
				}
			}
		}
	]
}

Complete Engagement (Upcoming)

This action enables you to tell that the engagement is considered complete. By default this action is related to the engagement associated with Your Logic.

{
  "actions": [
    {
      "type": "ENGAGEMENT_COMPLETE",
      "engagementPid": "582fa5da-d423-46ae-b69f-aa1d2b01f736",
      "name": "Engagement Outbound #2",
      "reasonCategory": "CUSTOMER_REQUEST",
      "reason": "Customer requested to end the conversation",
      "outcome": "COMPLETED",
      "outcomeType": "ACCEPTED",
      "outcomeCategory": "Delivered",
      "cost": "0.6"
    }
  ]
}

Complete Conversation (Upcoming)

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

Action has no properties.

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

Disengage Your Logic (Idea)

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.

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