Automatic messages
An automatic message is one Trialflare sends to participants for you: on a schedule, when they join, when they complete a stage, or relative to an anchor date. Each goes out by the channels you choose and appears in the participant's conversation like any other message. The Getting started series covers when to use them.
Trial-wide messages need trial.admin. A message scheduled for a single participant can be created and edited by anyone with trial.support.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/trials/<trialId>/automaticMessages |
The trial's automatic messages, as {"automaticMessages": [...]}. |
POST |
/trials/<trialId>/automaticMessages |
Create one. |
PATCH |
/trials/<trialId>/automaticMessages/<messageId> |
Update one. |
DELETE |
/trials/<trialId>/automaticMessages/<messageId> |
Delete one. |
Messages sent by hand are under Participant management.
Fields
| Field | Type | Notes |
|---|---|---|
sendWhen |
schedule, joinedTrial, completedStage, anchor |
Required. What triggers the message. |
message |
string | Required. 5–500 characters. |
sendVia |
list | Required. Any of push, email, sms, whatsapp. SMS and WhatsApp are charged to the trial's wallet. |
attachments |
list of strings | Stored file names from an upload with forType=trial. |
stage |
stage _id |
For completedStage: the stage whose completion sends it. |
stageRecurrence |
integer | For completedStage on a recurring stage: which occurrence, from 0. Omit for every occurrence. |
schedule |
object | For schedule and anchor — see below. |
Scheduled messages
schedule for sendWhen: "schedule":
| Field | Notes |
|---|---|
frequency |
daily, weekly or specific. |
hour |
0–23. The hour to send, in the participant's time zone. Required for daily and weekly. |
day |
0–6, Monday first. Required for weekly. |
dates |
List of ISO datetimes. Required for specific. |
group |
A group _id, to send only to its members. |
participant |
A participant _id, to send only to them. |
Anchored messages
schedule for sendWhen: "anchor": anchor (the anchor _id), dayOffset (days after the anchor date, negative for before) and hour (0–23), with the same optional group or participant. The message is sent once per participant, when their anchor date plus the offset arrives.