Message Media is currently the preferred SMS service provider for the Humanforce products. SMS messages are sent from either the Humanforce web application or the Humanforce desktop application (a.k.a TimeTarget) in certain scenarios, as follows:
| Web | Deskop | |
| Shift offer (*) | ✓ | ✓ |
| Roster offer (*) | ✓ | |
| Sending rosters | ✓ | |
| Roster swap notifications | ✓ | |
| MFA codes | ✓ |
* Shift offer and Roster offer functionalities require that SMS replies be received from the end users. See below for more info.
SOAP VS REST API
TLDR - configure your Message Media account to use the SOAP interface if you want to use the full feature set available in the Humanforce products. Continue reading for more info.
Message Media currently has two programmatic interfaces that can be used. The REST API is the newer and preferred interface. SOAP is still supported but has some limitations.
At the time of writing, the Humanforce Web application uses the SOAP interface exclusively, while the Desktop application supports both SOAP and REST.
An individual Message Media account must be exclusively configured to use either the SOAP or the REST interface, it cannot support both at the same time. Therefore, if any Message Media functionality will be used from Humanforce Web, the Message Media account must be setup for SOAP access.
The main limitation of the SOAP interface is that it does not support receiving SMS replies via web hooks. Therefore, if replies must be received, the Humanforce DataExchange utility must be setup to poll the SOAP API to check for replies on a regular basis.
HTTP ENDPOINTS
When the Web or Desktop application sends data to Message Media, the following URLs are used:
SOAP API: https://soap.m4u.com.au
REST API: https://api.messagemedia.com/v1
When the API is called by the web application, the call is made from the server. The Message Media authentication credentials are never available in the client-side browser.
When the API is called by the desktop application, the call is made directly from the desktop application process. There is no middleware used in this scenario.
RECEIVING REPLIES
If the REST API is in use, the preferred way to receive replies is via webhook. These webhook callbacks are sent from Message Media to the Humanforce web application at the following URL:
https://{client-name}.humanforce.com/callback/messagemedia
Even though the web application is not currently capable of sending messages via the REST API, it is able to receive the webhooks on behalf of the desktop application. The replies are saved in the SQL database where they can be seen by the desktop application.
If the integration is configured to use SOAP, the system must regularly poll the Message Media API to check for incoming replies. This is done via the DataExchange utility, a back-end component of Humanforce that performs integration tasks automatically in the background.
SECURITY
All communication between the Humanforce products and the Message Media APIs is done over an HTTPS connection. All data is encrypted in transit.
Authentication is achieved using the Message Media account username and password. These details are stored in the Humanforce database, encrypted at rest.
When the Message Media API is invoked, the username and password are included inside the HTTPS encrypted payload. For SOAP requests, they are included inside the XML payload. For REST requests, they are sent in the Authorization header using basic authentication.
DATA SENT TO MESSAGE MEDIA
The following data is sent to Message Media when sending an SMS message to a recipient:
| Data sent | Mandatory? | Comments |
| Authentication info | Mandatory | Username & password (see Security paragraph above) |
| Recipient’s phone number | Mandatory | |
| Sender’s phone number | Optional | If configured - a specific phone number from which the messages will appear to have been sent |
| Message content | Mandatory | Plain text content of the message – varies according to functionality and configuration |
| Callback URL for replies | Optional | If configured, and if using the REST API – the HTTP(s) callback URL which replies will be sent to |
The actual content of any given message depends on which feature of Humanforce is being used to send the message. In most cases the message content is not fixed, but instead is user defined using templates within the Humanforce software.
In the case of MFA functionality, the message format is fixed. The message sent is: “Your onetime password is: XXXX” where XXXX is the MFA code.