CommunityRecommendations.md

Community Recommendations

There are two types of community recommendations: user-aware and journal-entry-aware. The type of community recommendation is not provided through the endpoint, and is inferred in the underlying execution of the API call. However, it is helpful to understand the differences.

---

User-Aware

User-aware community recommendations only take into account user information for determining the best order of communication recommendations. This type of community recommendation is needed because some users don't have journal entries.

Journal-Entry-Aware

Journal-entry-aware community recommendations takes into account both user information and the information of their latest journal entry. This provides additional accuracy over a user-aware community recommendation, as the latest journal entry's transcription and sentiment score can be used when determining relevance with other community journal entries.

---

To get the community recommendations for a user under <user-id>, send a GET request to:

/community/recommend/<user-id>

The returned JSON should be:

{
    "data": [
        "journal_entry_1".
        "journal_entry_2",
        ...
    ],
    "success": true
}

Community Engagement

When a user engages with a community recommendation, this engagement must be recorded in order to prevent the community recommendation from showing up again over other community recommendations that have less engagement. Engagement is defined through two areas:

1. Whether the community recommendation is viewed.
2. If the community recommendation is viewed, whether the community recommendation has engagement messages.

Therefore they are 3 possible types of engagements:

1. A community recommendation is not viewed nor engaged.
2. A community recommendation is viewed but not engaged.
3. A community recommendation is viewed and engaged.

Community recommendations will be presented in order of these priorities, with item 1 having the highest priority and item 3 having the lowest priority.

---

To get the community engagements for a user under <user-id> for all journal entries, send a GET request to:

/community/engage/<user-id>

The returned JSON should be:

{
    "data": {
        "journal_entry_1": {
            "viewed": false / true?
            "engagement_messsages": [...]?
        },
        "journal_entry_2": {
            "viewed": false / true?
            "engagement_messages": [...]?
        },
        ...
    },
    "success": true
}

---

To get the community engagement for a user under <user-id> for a journal entry under <journal-entry-id>, send a GET request to:

/community/engage/<user-id>/<journal-entry-id>

The returned JSON should be:

{
    "data": {
        "viewed": false / true?
        "engagement_messages": [...]?
    },
    "success": true
}

If the community engagement from a user for only one journal entry is required, this will be much more efficient than fetching all of a user's community engagements through /community/engage/<user-id>.

---

To update the community engagement for a user under <user-id> for a journal entry under <journal-entry-id>, send a POST request to:

/community/engage/<user-id>/<journal-entry-id>

The posted JSON should be:

{
    "viewed": false / true?
    "engagement_messages": [...]?
}

---

To update the community engagements for a user under <user-id>, send a POST request to:

/community/engage/<user-id>

The posted JSON should be:

{
    "journal_entry_1": {
        "viewed": false / true?
        "engagement_messages": [...]?
    },
    "journal_entry_2": {
        "viewed": false / true?
        "engagement_messages": [...]?
    },
    ...
}