Skip to content

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.

Messages and notificationsTop row: a company user and the other party, for example you as the partner or Salaxy, exchange messages in a message thread stored in Salaxy. The thread shows in the embedded UI or in your own UI through the REST API. Bottom row: when a salary is paid, Salaxy notifies the worker by email or with an electronic payslip.MESSAGE THREADCompany userembedded UI or your UIMessage threadmessages, files, read marksOther partyyou as partner, or SalaxyAFTER PAYMENTSalary paidpaymentSucceededSalaxy notifiesby company settingsWorkeremail or e-payslip
Purple: Salaxy. Grey: people and your side. Green: a paid salary.

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.

MethodPathPurpose
GET/v03/api/messagesList threads with an OData query (queries)
GET/v03/api/messages/newGet a new empty thread to fill in
POST/v03/api/messagesCreate 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}/messagesAdd or edit one message in the thread
POST/v03/api/messages/{id}/filesAdd an attachment file as a message
POST/v03/api/messages/{id}/messages/blobFileMessageThe 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/messages creates a thread when id is empty. You may also set your own id for 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}/files takes a multipart form upload. Each file becomes a message of type blobFile. An optional form field from sets fromParty; the default is owner. A file that cannot be saved becomes a message with an error in validation.
  • Add a message. POST /v03/api/messages/{id}/messages with a message that has no id appends it. With an id it replaces that message; an unknown id is an error. If time is before the thread was created or in the future, it is set to now.
  • Message types. type is one of text, blobFile, calculation, payroll, workerAccount, email, salaxyEmail, sms, salaxySms, timer, timerEdited, hourlyReport, timeReport, absence, annualLeave, calcRow, travel, expense. For calculation and payroll, put the id in contentId. On save, Salaxy fills the gross salary, payment, salary date and period into contentData and links the calculation or payroll to the thread.
  • Sender. fromParty is owner, otherParty or system.
  • Thread status. status is draft, active, approved, rejected, archived or template.
  • Read marks. read-by accepts only owner or otherParty; any other value is an error. Each message has readByOwner and readByOtherParty times.
  • Email notification. The request body is the plain-text message and subject is a query parameter. Salaxy emails the address of the thread owner's account and adds the email to the thread as a message of type email from otherParty. If sending fails, the call still returns the thread: check validation on 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.

SettingValuesMeaning
workerSalaryNotificationsarray of always, silentWhether the worker gets an email after the salary payment
workerSalarySlipDeliveryMethodsarray of default, payslip, omapalkkaHow the salary slip is delivered to the worker; payslip is the electronic payslip
partnerMessagestrue, falsePartner 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:

  • silent in the list: no email. It wins over always.
  • always in 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 ​

  1. Get a test token (Get a test account, REST authentication).
  2. Call GET /v03/api/messages/new, fill in title, and POST it to /v03/api/messages.
  3. Add a message, then call POST /v03/api/messages/{id}/read-by/owner. Each message now has a readByOwner time.
  4. In the embedded UI, open #/messages and 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 owner and otherParty consistently.
  • 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

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.