Update participant data docs to include info about scheduled messages

[snopoke]

https://dimagi.github.io/open-chat-studio-docs/concepts/participant_data/

[lisa-tarbo]

Researching into what feature and information will be useful for the user docs

From DeepWiki

Participant data is used in scheduled messages through two main mechanisms:

1. storing schedule definitions within participant data, and
2. making scheduled messages available to bots during prompt generation.

2. Scheduled Messages in Prompt Context

When generating prompts for bots, the PromptTemplateContext.get_participant_data() method retrieves participant data and automatically includes scheduled messages by calling get_schedules() on the participant data proxy. This merges the scheduled messages into the participant data dictionary under the scheduled_messages key.

The ParticipantDataProxy.get_schedules() method fetches active scheduled messages for the participant in the current experiment by calling participant.get_schedules_for_experiment(). This allows bots to _access information about upcoming scheduled messages during conversation_s.

The ScheduledMessage model stores schedule parameters in custom_schedule_params including name, prompt_text, frequency, time_period, and repetitions. When schedules are triggered, they use the prompt_text as the message to send to the bot.

Considerations for documenting this feature

• The Python node can call the get_participant_schedules() which Returns all active scheduled messages for the participant in the current experiment session. https://docs.openchatstudio.com/tech-hub/python_node/#python_node.get_participant_schedules
• Using Tools, a recurring reminder or a Once Off Reminder can be set for participant documented here: https://docs.openchatstudio.com/concepts/tools/#recurring-reminders

Claudes understanding of OCS feature

• OCS reminder tools are asynchronous and persistent. When the LLM calls recurring-reminder or one-off-reminder, OCS doesn't just return a value — it writes a scheduled message to the database and the platform later delivers it to the participant at the right time, via their channel (WhatsApp, Telegram, web, etc.). The LLM itself never "fires" the reminder. It just makes the scheduling request. OCS owns the delivery.
• Example in OCS : A user is chatting with a medication support bot on WhatsApp: User: "Can you remind me to take my pills every morning at 8am?"
  • The LLM recognises the intent and calls the recurring-reminder tool .OCS creates the schedule. At 8am each day, OCS sends "Good morning! Time to take your medication." to the participant on WhatsApp — no further LLM involvement needed.
  • User (later): "Actually, can you move it to 9am?" The LLM calls move-scheduled-message-date with the schedule's message_id to update the time.
• The reminder tools essentially give the LLM the ability to schedule outbound messages as a side effect of a conversation, which is something most general-purpose LLM frameworks don't handle natively.

Ideas

1. The example of how reminders are used in OCS is valuable for users to understand as it is a power feature of OCS
2. Briefly mention reminders in participant docs in that the data is stored there...
3. Improve tools pages to group reminder tools together
4. Examples: prompt = "Hello {participant_data.name}, your age is {participant_data.age}"
5. The system supports CSV-based import and export of participant data. - add this

[lisa-tarbo]

@snopoke can I assist with this?

[snopoke]

@lisa-tarbo yes please - I don't think it needs to be very detailed.

[lisa-tarbo]

Suggestions from Claude

1. New subsection under "Using participant data" — Scheduled messages

Participant data is available as a variable in scheduled message content, just like in regular prompts. This lets you personalize timed outreach — for example, addressing a participant by name or including data specific to their record in a reminder message. Use the {participant_data} variable in the scheduled message body the same way you would in a chatbot prompt.

2. New item under "Updating participant data" — Update with scheduled messages

A scheduled message that runs a pipeline can update participant data as part of its execution. For example, a weekly check-in message could both send content to the participant and write a last_contacted date back to their record using the Update Participant Data Node.

3. Addition to "Managing participant records" — Viewing scheduled messages

On the Participant Details page, you can view any pending scheduled messages for that participant. This is useful for confirming that a scheduled workflow is active or for diagnosing why a participant is or isn't receiving timed messages.

4. Clarifying note to distinguish events from scheduled messages (within the existing "Update with events" section)

The events section already covers timeout-triggered pipelines. A short note distinguishing these from scheduled messages would help new users: events react to participant activity (or inactivity), while scheduled messages fire at fixed times regardless of conversation state. Both can read and write participant data, but they serve different use cases.