messages

Send a broadcast

Changed on

Sends one message to many participants on a study. Each of them gets a new conversation carrying the broadcast's subject, topic and study, with the message as its first message. Replies stay in that conversation, between the participant and the sender.

The broadcast is saved as it was sent and never changes. The conversations are created in the background, so they can take a short while to appear.

Pass your own id to make sending safe to repeat. Sending again with an id you've already used returns that broadcast rather than sending it twice.

Send it to recipient_ids or to a participant_group_id, exactly one of the two. With audience_source: submissions, each recipient must have a submission for the study in any status. With audience_source: TYPED_IDS (IDs typed in) or MESSAGES (participants picked from your conversations), each must be a participant who has taken part in one of your studies or already has a conversation with you. A group's members get it as the group is at the moment of sending, whether or not they're on the study, which only labels the broadcast. Each member must have taken part in one of your studies or already have a conversation with you. A group that isn't in the study's workspace or its organisation, or that you can't view, returns 404, and one with no members returns 400. If your access to the group can't be checked right now, it returns 503. A broadcast has the same recipient limit as a bulk message. Going over it returns a 400 that gives the limit. The study must belong to a workspace you are in. A study you can't broadcast about returns 404, as does the endpoint while broadcasts aren't enabled for the study's workspace.

post/api/v1/broadcasts/

Request

  • Base URL
    https://api.prolific.com
  • URL
    https://api.prolific.com/api/v1/broadcasts/
  • Auth
    API key in header Authorization

Request body

idstring

An id you choose for the broadcast. Sending again with the same id returns the broadcast already sent. One is made for you if it's left out.

study_idstring required

The study the broadcast is about.

subjectstring required

Shown as the title of each recipient's conversation.

topic'payment-timing' | 'payment-issues' | 'technical-issues' | 'feedback' | 'rejections' | 'other'

Which of the fixed categories it falls under, if any.

bodystring required

The message, sent as the first message of each conversation.

recipient_idsstring[]

Participants to send it to. Repeats are ignored. Needs audience_source, which sets who's allowed.

participant_group_idstring

Send to every member of this participant group, as it is at the moment of sending. The group must belong to the study's workspace or its organisation. The study labels the broadcast and doesn't narrow who gets it, so members don't need a submission for it. A group with no members returns 400.

audience_source'submissions' | 'TYPED_IDS' | 'MESSAGES'

Where recipient_ids were picked. submissions for participants picked from the study's submissions, TYPED_IDS for IDs typed in, MESSAGES for participants picked from your conversations. Left out for a participant group, which sets it to PARTICIPANT_GROUP.

workspace_idstring

Send it as this workspace rather than as yourself. Must be the study's workspace, and requires workspace messaging.

Response

The broadcast

idstring required
study_idstring required
subjectstring required
topicstring nullable required
bodystring required
audience_source'submissions' | 'PARTICIPANT_GROUP' | 'TYPED_IDS' | 'MESSAGES' required
recipient_countinteger required
datetime_createdstring date-time required

Changes

    • warning

      added the new MESSAGES enum value to the response property for the response status

    • info

      added the new MESSAGES enum value to the request property

    • warning

      added the new TYPED_IDS enum value to the response property for the response status

    • info

      added the new TYPED_IDS enum value to the request property