On-site messages

Topics:

About messages

Projects on Open Humans can send messages to their project members. These messages are received as emails by members, where the "reply-to" is set to the "contact email" you've specified for your project.

Messages are sent based on project member ID – this means projects can send messages to their members without having access to their email or other explicitly identifying information.

To test message formatting, we recommend you send messages to yourself. Join the project with your own account (as a test user) and send messages to your project member ID.

Sending via website form

  1. Go to your project management page.

  2. Click the "Send messages" button for your project.

  3. Specify which members you're messaging. You can either message all members in your project, or specify a comma-separated list of project member IDs.

  4. Enter your message subject. A prefix "[Open Humans Project Message]" is added to create the final subject of the email a member receives. If not provided, the default uses your project name, e.g. '[Open Humans Project Message] From "Foobar Project"'.

  5. Enter your message text. You can specify the text {{ PROJECT_MEMBER_ID }} anywhere in your message (multiple times, if needed). It will be replaced with the unique project member ID that identifies the member to your project.

    Including the project member ID can be useful when directing members to activities which collect member-specific information. For example, in a Google Form the ID can be included as parameter in the URL to pre-populate a field in the form. This allows you to automatically match the resulting form responses to the Open Humans member.

  6. Send messages. Click "Send messages" to send the message to the specified project members. Project members will receive an email with a standard footer. The reply-to for the email will be set to your project's "contact email".

    For example, the user "joesmith" might receive the following message if "Foobar Project" sends a message with subject "Quick questions about your data":

    From: "Foobar Project" <foobar.project.contact.email@example.com>

    Subject: [Open Humans Project Message] Quick questions about your data

    Dear participant, thank you for being part of our project! We wanted to check in with a brief survey that will help us better understand your data. This will greatly increase our ability to learn from your data, and should take less than five minutes. To complete our survey, please follow this link: https://www.example.com/foobar-project/survey-url/?userid=PROJECT_MEMBER_ID

    -------------------------------------------------------------------------------

    This email was sent by Open Humans project "Foobar Project" to "joesmith". It has been automatically delivered. The project has not been given your email address. You have no obligation to reply to this email or take any other action that might disclose your identity. Open Humans did not review nor retain a copy of this message’s contents and is not responsible for material sent by this project. You should retain a copy of this message if you may need it in the future.

    If you respond directly, the project will know your email address. Your email will go directly to the project's email address, this communication is not managed by Open Humans.

    When you authorized this project, you granted permission for it to send you messages. You may deauthorize this project by visiting the project management page: foobar-project.

    Please report abuses of messaging to Open Humans support <support@openhumans.org>.

Via API with a master access token

You can use a master access token with the messaging endpoint to send messages to all the members of your project, or a specified subset.

The endpoint takes these parameters as a JSON object:

  • all_members: If specified it must be true or false.
  • project_member_ids: An array of project member IDs to send messages to.
  • subject: The text of the subject to use. A prefix ("[Open Humans Project Message]") is added to create the final subject of the email a member receives. If not provided, the default uses your project's name, e.g. '[Open Humans Project Message] From "Foobar Project"'.
  • message: The text of the message to send. For details on what the message text can contain and how it appears to the end user please see the documentation for messages via online form.

You must either specify true for all_members or specify an array of project_member_ids but not both.

The URL for the messaging endpoint is:

https://www.openhumans.org/api/direct-sharing/project/message/?access_token=<MASTER_ACCESS_TOKEN>

Examples

These two examples show sending a message to all members and to a specified array of project member IDs with the httpie tool:

TOKEN="<MASTER_ACCESS_TOKEN>"
URL="https://www.openhumans.org/api/direct-sharing/project/message/?access_token=$TOKEN"

http -v POST $URL all_members:=true message:='"example message text"'
http -v POST $URL project_member_ids:='["12345678", "56781234"]' message:='"example message text"'

The output of the second command looks like this:

POST /api/direct-sharing/project/message/?access_token=<MASTER_ACCESS_TOKEN> HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 63
Content-Type: application/json
Host: localhost:8000
User-Agent: HTTPie/0.9.3

{
    "message": "test\ntest\n",
    "project_member_ids": [
        "12345678",
        "56781234"
    ]
}

HTTP/1.0 200 OK
Allow: POST, OPTIONS
Cache-Control: no-cache, no-store, must-revalidate, max-age=0
Content-Language: en
Content-Type: application/json
Date: Thu, 21 Apr 2016 16:40:07 GMT
Expires: Thu, 21 Apr 2016 16:40:07 GMT
Last-Modified: Thu, 21 Apr 2016 16:40:07 GMT
Server: WSGIServer/0.1 Python/2.7.11
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN

"success"

About master access tokens

Each project has a "master access token" used for API calls. This token is a password for your project.

To find the token, your project management page and click on your project's name. The master access token should be listed in your project's details.

Keep this token PRIVATE.

  • Do NOT publicly share this token.
  • Do NOT share this token in an unsecured manner.
  • NEVER put this token into a git repository.

This token is used to authorize the following:

  • API access to any private data shared with your project
  • sending messages to project members via API
  • uploading data for project members via API

If you ever believe the security of this token may have been compromised, contact us at support@openhumans.org and we'll reset it to a new value.

When using this token in programs, we recommend you do NOT store it. You should enter the token each time you run your software.

If you want to have fully automated API transactions with Open Humans, you should use OAuth2 endpoints with user-specific access tokens.