# 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](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Top 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. (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](https://code.salaxy.com/white-label/navigation.md)). 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](https://code.salaxy.com/reference/rest/messagethread.md).

### Worker notifications after payment
Fits when you want to decide how the worker hears about a paid salary. See [Worker notifications](#worker-notifications). For the salary slip itself, see [Salary slips and e-payslips](https://code.salaxy.com/integration/salary-slips.md).

## Message-thread API

All paths are in v03.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v03/api/messages` | List threads with an OData query ([queries](https://code.salaxy.com/reference/queries.md)) |
| `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/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](https://code.salaxy.com/integration/company-settings.md) and [Service models](https://code.salaxy.com/integration/service-models.md).

| 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`:

- **`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](https://code.salaxy.com/integration/salary-slips.md).

## Test it

1. Get a test token ([Get a test account](https://code.salaxy.com/get-started/test-account.md), [REST authentication](https://code.salaxy.com/security/rest-authentication.md)).
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](https://code.salaxy.com/reference/test-endpoints.md).

## 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](https://code.salaxy.com/reference/queries.md).

**Next:** [Go-live checklist](https://code.salaxy.com/integration/go-live.md)
