> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate Community Data with Your Customer Service Platform
> Use the Community API to retrieve, filter, and reply to social media messages and comments, and track sentiment across platforms.
The Community API lets you sync social media conversations with your customer service platform. This guide covers:
* Retrieving and replying to direct messages across Instagram, Facebook, and X
* Retrieving and replying to comments across Facebook, Instagram, TikTok, and YouTube
* Analyzing sentiment distribution and trends over time
**API update:** DMs have moved from conversation-level to message-level interactions. `GET /community_interactions` now returns one result per message instead of per conversation. See the [migration changelog](/changelog/community-api-migrate-dms-to-message-level-interactions) for full details.
## Use cases
Customer service teams use the Community API to connect social conversations directly into their support workflows.
Filter DMs by keyword to surface complaints and automatically route them to the right support queue in Zendesk or Salesforce.
Pull comments across Facebook and Instagram posts to review, tag, and respond without leaving your existing tooling.
Track positive and negative sentiment trends over time to catch issues early and measure the impact of campaigns or product launches.
## Before you start
Make sure you have:
* **API access token** with permissions to the relevant brand.
* **Brand ID** for the account you want to query.
See [API Quickstart](/guides/get-started/quickstart) for more details.
***
## Use Case 1: Retrieve and Respond to Direct Messages
Filter DMs by platform, keyword, and date range to surface messages that need attention, then reply directly through the API.
### Step 1: Retrieve DMs
`GET /community_interactions` returns a list of individual messages. Each result is a single message with its content in `text` and a `conversation_id` linking it to the thread it belongs to.
See the [Get Community Interactions](/api-reference/community/community-interactions/get-community-interactions) endpoint reference for the full parameter list.
**Parameters**
| Parameter | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id` | **Required.** The brand to query. |
| `types` | Filter by interaction type. Use `,` as OR for multiple types. **DMs:** `INSTAGRAM_CONVERSATION`, `FACEBOOK_CONVERSATION`, `TWITTER_CONVERSATION`, `COMMUNITY_INTERACTION` |
| `source_updated_after` / `source_updated_before` | Date range filter. ISO 8601 format. Time is optional: `2024-08-15` and `2024-08-15T00:00:00-04:00` are both valid. |
| `message_nested_date_filter` | Set to `true` to narrow results to threads where keyword matches fall within the date range. |
| `query` | Keyword filter. Use `,` as OR for multiple keywords. |
| `sort` | Sort order. `-SOURCE_UPDATED_AT` (most recently updated first), `SOURCE_UPDATED_AT` (oldest first), `RELEVANCE`, `SAMPLE` (random sample, only valid for `COMMUNITY_INTERACTION` type) |
| `is_closed` | Set to `false` to exclude closed interactions. |
| `limit` | Number of results to return. Maximum `100` to avoid rate limiting. |
| `offset` | Pagination offset. |
```http theme={null}
GET https://community.dashsocial.com/community_interactions
?brand_id=
&types=INSTAGRAM_CONVERSATION
&source_updated_after=2024-08-15T00:00:00-04:00
&source_updated_before=2024-09-05T23:59:59-04:00
&message_nested_date_filter=true
&sort=-SOURCE_UPDATED_AT
&query=issue,not working,don't like
&is_closed=false
&limit=99
&offset=0
```
Response example:
```json theme={null}
{
"data": [
{
"brand_id": "",
"conversation_id": 1027220732,
"created_at": "2024-09-05T21:08:07.010000",
"id": 263350682,
"is_closed": false,
"tag_ids": [15307],
"text": "I don't like sunny today",
"type": "INSTAGRAM_CONVERSATION",
"updated_at": "2024-09-05T21:08:10"
}
],
"paging": {
"count": 7,
"next": null,
"offset": null,
"previous": null
}
}
```
`INSTAGRAM_CONVERSATION` includes story replies and story mentions, not just direct messages. Check the `story_reply` and `story_mention` fields in the full thread (Step 2) to distinguish them.
### Step 2: Get the Full Thread (optional)
If you need the full message history for a conversation, use the `conversation_id` from Step 1. This step is optional — message content is already available in `text` from Step 1.
See the [Get Interaction Messages](/api-reference/community/community-interactions/get-interaction-messages) endpoint reference.
```http theme={null}
GET https://community.dashsocial.com/conversations/{conversation_id}
```
Response example:
```json theme={null}
{
"data": [
{
"conversation_id": 1027220732,
"created_at": "2024-09-05T21:08:10",
"from_participant_id": "",
"id": 263350682,
"send_failed": false,
"text": "I don't like sunny today",
"to_participant_id": 17841402247948351,
"type": "INSTAGRAM_CONVERSATION",
"updated_at": "2024-09-05T21:08:10"
}
],
"paging": {
"count": 13,
"next": null,
"previous": null
}
}
```
### Step 3: Reply to a Conversation
Send a reply using the `conversation_id` from Step 1.
Instagram and Facebook do not allow replies to DMs received more than 7 days ago through third-party platforms.
```http theme={null}
POST https://community.dashsocial.com/conversations/{conversation_id}/messages
{
"text": "Hello! Is there anything we can help with?"
}
```
***
## Use Case 2: Retrieve and Respond to Comments
Use the same `GET /community_interactions` endpoint to retrieve comments across platforms, then reply to them directly through the API.
### Step 1: Retrieve Comments
Filter by `types` to pull comments across platforms. Use the same parameters as [Use Case 1](#step-1-retrieve-dms). The only difference is the `types` values.
See the [Get Community Interactions](/api-reference/community/community-interactions/get-community-interactions) endpoint reference for the full parameter list.
| Type | Description |
| ----------------------------------------------------------------------------------------------- | ---------------------------------- |
| `FACEBOOK_COMMENT`, `INSTAGRAM_COMMENT`, `TIKTOK_COMMENT`, `TWITTER_RETWEET`, `YOUTUBE_COMMENT` | Organic comments across platforms. |
| `FACEBOOK_ADS_COMMENT`, `INSTAGRAM_ADS_COMMENT` | Comments on paid ad posts. |
```http theme={null}
GET https://community.dashsocial.com/community_interactions
?brand_id=
&types=INSTAGRAM_COMMENT,FACEBOOK_COMMENT,TIKTOK_COMMENT,YOUTUBE_COMMENT
&source_updated_after=2024-08-15
&source_updated_before=2024-09-05
&sort=-SOURCE_UPDATED_AT
&is_closed=false
&limit=99
&offset=0
```
Each result includes an `id` you'll use to reply in Step 2, and platform-specific comment identifiers (e.g. `facebook_comment_id`) in the full comment detail.
If you need comments scoped to a single post, use the platform-specific comment endpoints with a `media_id`. First get the post's `id` from the Library API, then pass it as `media_id`.
```http theme={null}
PUT https://library-backend.dashsocial.com/brands//media/v2
{
"filters": {
"source_created_at": { "start": "2024-08-14", "end": "2024-08-31" },
"brand_media_types": ["FACEBOOK_OWNED"]
},
"limit": 99,
"offset": 0
}
```
Then fetch comments for that post:
```http theme={null}
GET https://community.dashsocial.com/facebook_comments
?media_id=
&brand_id=
```
Replace `facebook_comments` with `instagram_comments`, `tweets`, `tiktok_comments`, or `youtube_comments` for other platforms. See the endpoint references for [Facebook comments](/api-reference/community/facebook-comments/get-facebook-comments), [Instagram comments](/api-reference/community/instagram-comments/get-instagram-comments), [TikTok comments](/api-reference/community/tiktok-comments/get-tiktok-comments), and [YouTube comments](/api-reference/community/youtube-comments/get-youtube-comments).
### Step 2: Reply to Comments
Use the `facebook_comment_id` (or platform equivalent) from Step 1 as `parent_comment_id` to thread the reply under the original comment.
Facebook does not allow replies to comments received more than 7 days ago through third-party platforms.
```http theme={null}
POST https://community.dashsocial.com/facebook_comments
{
"brand_id": "",
"parent_comment_id": "",
"text": "Thank you!"
}
```
Replace `facebook_comments` with `instagram_comments`, `tweets`, `tiktok_comments`, or `youtube_comments` for other platforms.
Response example:
```json theme={null}
{
"brand_id": "",
"brand_user_reply": {
"brand_id": "",
"created_at": "2024-09-04T16:34:28",
"id": 501004,
"resource_id": 1205650847,
"resource_type": "FACEBOOK_COMMENT",
"updated_at": "2024-09-04T16:34:28",
"user_id": 114999
},
"created_at": "2024-09-04T16:34:28+00:00",
"facebook_comment_id": "1574406790058145_824658966449828",
"facebook_parent_comment_id": "1574406790058145_438078445927408",
"id": 1205650847,
"is_owned": true,
"text": "Thank you!",
"type": "FACEBOOK_COMMENT",
"updated_at": "2024-09-04T16:34:28+00:00"
}
```
***
## Use Case 3: Analyze Community Sentiment
Track interaction volume, sentiment, and top keywords across platforms. All endpoints support multiple brands in a single request.
### Sentiment Distribution
`POST /sentiment_distribution_stats` returns the positive, neutral, and negative breakdown for a brand's interactions. Filter by date range, platform type, and other attributes.
See the [Get Sentiment Distribution Stats](/api-reference/community/community-overview-v2/create-sentiment-distribution-stats) endpoint reference.
**Step 1: Map Your Parameters**
| Parameter | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. |
| `source_updated_after` / `source_updated_before` | Date range for the interactions. ISO 8601 format. |
| `types` | Filter by interaction type. Same values as `GET /community_interactions`. |
| `is_positive` / `is_negative` / `is_neutral` | Filter to interactions with a specific sentiment label. |
| `is_closed` | Filter by closed status. |
| `query` | Keyword filter. |
| `tag_ids` | Filter by interaction tag IDs (AND condition). |
**Step 2: Make the API Call**
```http theme={null}
POST https://community.dashsocial.com/sentiment_distribution_stats
{
"brand_ids": [144],
"source_updated_after": "2024-08-01T00:00:00Z",
"source_updated_before": "2024-08-31T23:59:59Z",
"types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"]
}
```
Response returns a `data` object with sentiment counts broken down per platform.
***
### Sentiment Time Series
`POST /sentiment_time_series` returns per-platform sentiment data over time. Use this to chart sentiment trends across a date range.
See the [Get Sentiment Time Series](/api-reference/community/community-overview-v2/create-sentiment-time-series) endpoint reference.
**Step 1: Map Your Parameters**
| Parameter | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. |
| `source_updated_after` / `source_updated_before` | Date range for the time series. ISO 8601 format. |
| `scale` | Time series granularity: `DAY`, `HOUR`, `WEEK`, `MONTH`, `QUARTER`. |
| `types` | Filter by interaction type. Same values as `GET /community_interactions`. |
| `is_closed` | Filter by closed status. |
| `query` | Keyword filter. |
| `tag_ids` | Filter by interaction tag IDs (AND condition). |
**Step 2: Make the API Call**
```http theme={null}
POST https://community.dashsocial.com/sentiment_time_series
{
"brand_ids": [144],
"source_updated_after": "2024-08-01T00:00:00Z",
"source_updated_before": "2024-08-31T23:59:59Z",
"scale": "DAY",
"types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"]
}
```
Response returns a `data` object with per-platform sentiment counts indexed by date.
***
### Volume Time Series
`POST /volume_time_series` returns interaction volume over time, broken down by interaction type per date. Use this to track how many comments, messages, and mentions your brand receives across platforms.
DM messages are now included in volume calculations. If your brand has active DMs, expect higher counts compared to previous results.
See the [Get Volume Time Series](/api-reference/community/community-overview-v2/create-volume-time-series) endpoint reference.
**Step 1: Map Your Parameters**
| Parameter | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. |
| `source_updated_after` / `source_updated_before` | Date range filter. ISO 8601 format. Time is optional: `2024-08-15` and `2024-08-15T00:00:00-04:00` are both valid. |
| `scale` | Time series granularity: `DAY`, `HOUR`, `WEEK`, `MONTH`, `QUARTER`. |
| `types` | Filter by interaction type. Same values as `GET /community_interactions`. |
| `is_closed` | Filter by closed status. |
| `query` | Keyword filter. |
| `tag_ids` | Filter by interaction tag IDs (AND condition). |
**Step 2: Make the API Call**
```http theme={null}
POST https://community.dashsocial.com/volume_time_series
{
"brand_ids": [144],
"source_updated_after": "2024-08-01T00:00:00Z",
"source_updated_before": "2024-08-31T23:59:59Z",
"scale": "DAY",
"types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"]
}
```
Response example:
```json theme={null}
{
"data": {
"2026-02-06": {
"facebook_comment": 4,
"facebook_message": 0,
"instagram_comment": 0,
"instagram_message": 15,
"tiktok_comment": 0,
"twitter_mention": 6,
"twitter_message": 0,
"twitter_quote": 2,
"twitter_retweet": 4,
"youtube_comment": 0,
"total": 31
}
}
}
```
Each key is a date. The value breaks down volume by interaction type, with `total` as the sum across all types for that day.
***
### Top Keywords
`POST /top_keywords` returns the most frequent keywords from community interactions, ranked by total mentions. Each keyword includes a sentiment breakdown so you can see whether mentions are positive, neutral, or negative.
See the [Get Top Keywords](/api-reference/community/community-overview-v2/create-top-keywords) endpoint reference.
**Step 1: Map Your Parameters**
| Parameter | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. |
| `source_updated_after` / `source_updated_before` | Date range filter. ISO 8601 format. Time is optional: `2024-08-15` and `2024-08-15T00:00:00-04:00` are both valid. |
| `types` | Filter by interaction type. Same values as `GET /community_interactions`. |
| `query` | Keyword filter to scope results. |
| `is_closed` | Filter by closed status. |
| `tag_ids` | Filter by interaction tag IDs (AND condition). |
**Step 2: Make the API Call**
```http theme={null}
POST https://community.dashsocial.com/top_keywords
{
"brand_ids": [144],
"source_updated_after": "2024-08-01T00:00:00Z",
"source_updated_before": "2024-08-31T23:59:59Z",
"types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"]
}
```
Response example:
```json theme={null}
{
"data": {
"love": { "negative": 3, "neutral": 10, "positive": 30, "total": 43 },
"style": { "negative": 4, "neutral": 6, "positive": 11, "total": 21 },
"order": { "negative": 7, "neutral": 1, "positive": 2, "total": 10 },
"perfect": { "negative": 0, "neutral": 1, "positive": 10, "total": 11 },
"wait": { "negative": 0, "neutral": 0, "positive": 12, "total": 12 }
}
}
```
Each key is a keyword string. The values show how many interactions containing that keyword were negative, neutral, positive, and the total count.
***
## Limitations
* **All channels:** Group DMs are not supported.
* **Instagram:** Brands cannot reply to DMs received more than 7 days ago. Deleted comments are not reported back to Dash Social.
* **Facebook:** Brands cannot reply to DMs received more than 7 days ago. Deleted comments are not reported back to Dash Social.
* **TikTok:** `@mentions` in replies are rendered as plain text without linking to the mentioned profile.
* **X (Twitter):** Deleted comments are not reported back to Dash Social.
* **YouTube:** Only root-level comments are imported. Replies to comments are not supported. Native emojis are not rendered when replying via the API.