Placeholders are %TOKEN% strings you embed in the notification Web Link. When Samply fires the notification, it replaces each token with that participant real value before opening the URL. Every participant gets a personalised link — no manual work required.
Token reference
| Token | Replaced with | If unavailable |
|---|---|---|
| %SAMPLY_ID% | The participant anonymous Samply ID. | Always substituted — every participant has one. |
| %PARTICIPANT_CODE% | The custom code the participant entered when joining. | Left unreplaced if the participant did not enter a code. Enable "Ask for participant code" in Edit study and ensure participants fill it in. |
| %GROUP_ID% | The short ID of the group the participant belongs to. | Left unreplaced if the participant has no group assigned. |
| %MESSAGE_ID% | A unique ID generated for this specific send to this participant. | Always substituted. |
| %TIMESTAMP_SENT% | Unix timestamp (milliseconds) of the moment the notification was dispatched. | Always substituted. |
| %BATCH% | How many notifications this participant has received from this study so far, counting from 1. The first notification has batch = 1, the second has batch = 2, and so on. | Always substituted. |
How substitution works
Substitution happens at send time, inside the notification dispatcher, immediately before the push is enqueued for delivery. The original URL stored in the schedule definition is never modified — the substituted URL exists only in the notification payload delivered to the device. Each participant therefore receives a unique URL even though all their notifications come from the same schedule.
Samply only performs substitution when the URL contains at least one % character. URLs without any % are passed through unchanged, so there is no performance penalty for schedules that do not use placeholders.
Constructing the URL
Append placeholders as standard query string parameters. You can combine as many as you need. A typical URL for a study that tracks participants, waves, and completions looks like this:
When Samply fires this notification for participant abc123 on their third send, the URL becomes:
Tool-specific setup
- In your survey flow, add an Embedded Data element before the first question block.
- Create fields named id, code, wave, messageid (or whatever names match your URL params).
- Qualtrics captures query string parameters automatically when the survey loads from a URL that includes them.
- Reference the values in question text or logic with ${e://Field/id} syntax.
- Use a survey queue or public survey link with the record parameter.
- Pass %PARTICIPANT_CODE% as the record value so each submission maps to the correct REDCap record.
- Pass %MESSAGE_ID% as a hidden field if you need to wire up completion callbacks to cancel reminders.
- Enable "URL fields" in the survey settings.
- Pass placeholder values as URL parameters — LimeSurvey stores them as response data automatically.
MESSAGE_ID and completion tracking
%MESSAGE_ID% is the key that connects a survey response back to the notification that triggered it. When a participant completes your survey, your survey tool must send a callback to Samply with this ID. Samply uses it to:
- Mark the corresponding result record as completed.
- Cancel any pending reminder notifications for that send.
Without this callback, Samply has no way to know the survey was submitted, and reminders will fire regardless of completion. The callback setup is covered in Reminders.
Placeholders in the permanent study link
The same tokens work in the permanent study link — the URL participants can tap in the Samply app at any time, outside of scheduled notifications. This is the foundation of event-contingent designs: instead of pushing a notification at a fixed time, you let participants self-initiate a report whenever a relevant event occurs in their day. Configure the permanent link in the Settings tab of your study dashboard, under Event-contingent design.
Things to watch out for
- Unreplaced tokens in the URL
- If a token has no value for a participant (no code, no group), it is left in the URL as a literal string — for example,
?code=%PARTICIPANT_CODE%. Your survey tool will receive that literal string as the parameter value. Test with a participant who has no code set to confirm your survey handles it gracefully. - URL encoding
- Substituted values are inserted as-is. Samply IDs and message IDs use only alphanumeric characters and are URL-safe. Participant codes are researcher-defined — avoid spaces and special characters in codes if they will be used in URLs.
- BATCH counts all sends from the study, not just one schedule
- The batch number is the total number of results Samply has recorded for that participant across the entire study, not just within one schedule. If a participant is targeted by two schedules, their batch counter increases with every send from either schedule.