Appearance
Messages and notifications
Salaxy keeps conversations as message threads: a title, a list of messages and attachments, and read marks for each side. The embedded white label UI has a Messages view, and you can read and write the same threads through the REST API. After a salary is paid, Salaxy can also notify the worker. Examples use the test environment; see Environments for demo and production.
Which fits you?
Messaging in the embedded UI
Fits when your customers use the embedded Salaxy UI, Salaxy Business or Salaxy Pro (build path 1): there is nothing to build.
Messaging in the embedded UI: how it works
The embedded payroll UI has a Messages view at the route #/messages (see Navigation). Users read and write threads there. If you use your own menu, link it to that route.
Your own UI on the message-thread API
Fits when you build your own UI (build path 2), or want to show or start threads from your product.
Your own UI: how it works
Use the endpoints below. A thread belongs to an owner (typically the company or household, the party that can delete the thread) and has an other party (typically the partner or Salaxy). Each side has its own workflow block (ownerWorkflow, otherPartyWorkflow) with the last message text, a salary date and an unread count: the number of messages that side has posted and the other side has not read yet. The generated reference for the tag is MessageThread.
Worker notifications after payment
Fits when you want to decide how the worker hears about a paid salary. See Worker notifications. For the salary slip itself, see Salary slips and e-payslips.
Message-thread API
All paths are in v03.
| Method | Path | Purpose |
|---|---|---|
GET | /v03/api/messages | List threads with an OData query (queries) |
GET | /v03/api/messages/new | Get a new empty thread to fill in |
POST | /v03/api/messages | Create or update a thread |
GET | /v03/api/messages/{id} | Get one thread with its messages |
DELETE | /v03/api/messages/{id} | Delete the thread and its attachment files |
POST | /v03/api/messages/{id}/messages | Add or edit one message in the thread |
POST | /v03/api/messages/{id}/files | Add an attachment file as a message |
POST | /v03/api/messages/{id}/messages/blobFileMessage | The same action as /files, at a second address |
POST | /v03/api/messages/{id}/read-by/{readBy} | Mark all messages as read by owner or otherParty |
POST | /v03/api/messages/{id}/notifications?subject=... | Send an email notification to the owner of the thread |
Rules
- Create.
POST /v03/api/messagescreates a thread whenidis empty. You may also set your ownidfor a new thread; it must not be in use already. - Owner and other party. The owner is the account that saves the thread; you cannot set it. Set
otherParty(the account id of the other party) when you create the thread. Once the thread has another party, a later save does not change it. - Attachments.
POST /v03/api/messages/{id}/filestakes a multipart form upload. Each file becomes a message of typeblobFile. An optional form fieldfromsetsfromParty; the default isowner. A file that cannot be saved becomes a message with an error invalidation. - Add a message.
POST /v03/api/messages/{id}/messageswith a message that has noidappends it. With anidit replaces that message; an unknownidis an error. Iftimeis before the thread was created or in the future, it is set to now. - Message types.
typeis one oftext,blobFile,calculation,payroll,workerAccount,email,salaxyEmail,sms,salaxySms,timer,timerEdited,hourlyReport,timeReport,absence,annualLeave,calcRow,travel,expense. Forcalculationandpayroll, put the id incontentId. On save, Salaxy fills the gross salary, payment, salary date and period intocontentDataand links the calculation or payroll to the thread. - Sender.
fromPartyisowner,otherPartyorsystem. - Thread status.
statusisdraft,active,approved,rejected,archivedortemplate. - Read marks.
read-byaccepts onlyownerorotherParty; any other value is an error. Each message hasreadByOwnerandreadByOtherPartytimes. - Email notification. The request body is the plain-text message and
subjectis a query parameter. Salaxy emails the address of the thread owner's account and adds the email to the thread as a message of typeemailfromotherParty. If sending fails, the call still returns the thread: checkvalidationon the new message. - Lists. The thread list leaves out the threads that record emails Salaxy itself has sent.
Sample
Create a thread, then add a message. Replace {id} with the id in the first response.
http
POST https://test-secure.salaxy.com/v03/api/messages
Authorization: Bearer <token>
Content-Type: application/json
{
"title": "Question about the March payroll",
"status": "active",
"messages": [
{ "type": "text", "content": "Can the salary date move to the 28th?", "fromParty": "owner" }
]
}http
POST https://test-secure.salaxy.com/v03/api/messages/{id}/messages
Authorization: Bearer <token>
Content-Type: application/json
{ "type": "text", "content": "Yes, we updated the payroll.", "fromParty": "otherParty" }Worker notifications
The messaging part of the company settings controls what the worker gets after a salary payment. A service model can set the defaults; see Company settings and Service models.
| Setting | Values | Meaning |
|---|---|---|
workerSalaryNotifications | array of always, silent | Whether the worker gets an email after the salary payment |
workerSalarySlipDeliveryMethods | array of default, payslip, omapalkka | How the salary slip is delivered to the worker; payslip is the electronic payslip |
partnerMessages | true, false | Partner messages enabled |
After the salary payment, Salaxy can email the worker that the salary slip is ready. For most payment channels this happens when the calculation reaches paymentSucceeded. Whether the email is sent follows workerSalaryNotifications:
silentin the list: no email. It wins overalways.alwaysin the list: the email is sent.- Empty list: the default of the payment channel applies.
The email is the same for every worker: it links to the worker site, where the worker signs in with strong authentication to see the slip. It is separate from the electronic payslip in the worker's online bank, which is sent only when workerSalarySlipDeliveryMethods includes payslip; see Salary slips and e-payslips.
Test it
- Get a test token (Get a test account, REST authentication).
- Call
GET /v03/api/messages/new, fill intitle, andPOSTit to/v03/api/messages. - Add a message, then call
POST /v03/api/messages/{id}/read-by/owner. Each message now has areadByOwnertime. - In the embedded UI, open
#/messagesand check that the thread is listed.
The test and demo environments do not send real email. The email message is still saved and looks sent, so check the thread, not an inbox. See Test endpoints and test data.
Checklist
- You create threads as the company, so the company is the owner, and you use
ownerandotherPartyconsistently. - You do not rely on an email being delivered: a sent notification records only that Salaxy handed it on.
- You mark messages as read only for the party that actually read them.
- You choose the worker notification and salary slip delivery settings deliberately, per company.
- You filter and page thread lists with OData queries.
Next: Go-live checklist

