> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors Overview

> Platform capabilities and feature matrix.

Connectors give SocialAPI.ai one unified API across social networks: each connector normalizes a platform's comments, messages, mentions, reviews, and publishing into the shared SocialAPI schema.

[SocialAPI.AI](https://social-api.ai) uses a connector pattern - each platform implements the same interface. If a platform doesn't support a feature, the API returns `501` with `error.code: "resource.not_supported"`. Your code doesn't need to branch per platform; just handle the 501.

## Feature matrix

For the full per-feature, per-platform support table (reply, hide, like, delete, private reply, DMs, reviews, mentions, publishing), see [Platform support](/guides/platforms). It is the single source of truth and is kept in sync with each connector page.

## OAuth app ownership

Every connector except Twitter uses SocialAPI's managed platform app. You don't need to create your own Meta App, Google Cloud project, or TikTok Developer registration.

| Platform    | OAuth app provided by                                        |
| ----------- | ------------------------------------------------------------ |
| Instagram   | SocialAPI                                                    |
| Facebook    | SocialAPI                                                    |
| Threads     | SocialAPI                                                    |
| TikTok      | SocialAPI                                                    |
| LinkedIn    | SocialAPI                                                    |
| YouTube     | SocialAPI                                                    |
| WhatsApp    | SocialAPI                                                    |
| Telegram    | **You (bot token from @BotFather)** - no OAuth               |
| X / Twitter | **You (BYOK)** - see [setup guide](/connectors/twitter-byok) |
| Google      | SocialAPI (beta)                                             |
| Pinterest   | SocialAPI                                                    |
| Trustpilot  | API key (Coming soon)                                        |

See [Platform credentials](/guides/platform-credentials) for the full story, including consent-screen branding and FAQs.

## Account object

`GET /v1/accounts` returns an array of Account objects:

```json theme={null}
{
  "id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "platform": "instagram",
  "name": "Acme Corp",
  "username": "acmecorp",
  "brand_id": "b7e2c1a0-4f3d-11ee-be56-0242ac120002",
  "status": "active"
}
```

| Field                 | Type   | Description                                                                                         |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `id`                  | string | Account ID. Pass this as `:id` in all account-scoped endpoints.                                     |
| `platform`            | string | Platform identifier (e.g. `instagram`, `facebook`, `tiktok`, `youtube`, `twitter`).                 |
| `name`                | string | Display name of the connected page or profile.                                                      |
| `username`            | string | Platform handle or username.                                                                        |
| `brand_id`            | string | Internal brand UUID this account belongs to. Always present.                                        |
| `status`              | string | Account status. One of: `active`, `reconnect_required`. Always present.                             |
| `profile_picture_url` | string | Profile picture URL. Omitted when not available.                                                    |
| `bio`                 | string | Profile biography or description. Omitted when not available.                                       |
| `reconnect_reason`    | string | Human-readable reason why reconnection is required. Only set when `status` is `reconnect_required`. |

## Connect response metadata

The `metadata` object is not included in the `GET /v1/accounts` account list response. It is returned only on the connect (`POST /v1/accounts/connect`) and OAuth exchange (`POST /v1/oauth/exchange`) responses. Use it to read platform-specific profile data at connection time.

The following platforms populate `metadata`:

| Key                   | Type    | Platform                                 |
| --------------------- | ------- | ---------------------------------------- |
| `avatar_url`          | string  | TikTok                                   |
| `follower_count`      | integer | TikTok                                   |
| `following_count`     | integer | TikTok                                   |
| `video_count`         | integer | TikTok, YouTube                          |
| `likes_count`         | integer | TikTok                                   |
| `subscriber_count`    | integer | YouTube                                  |
| `uploads_playlist_id` | string  | YouTube                                  |
| `byok_source`         | string  | X/Twitter (value: `"user"` or `"brand"`) |
| `bot_id`              | string  | Telegram                                 |
| `phone_number_id`     | string  | WhatsApp                                 |
| `waba_id`             | string  | WhatsApp                                 |

Platforms not listed above omit `metadata` entirely.

## What "not supported" means

When a platform doesn't support a feature (e.g. Instagram has no reviews), calling that endpoint returns:

```json theme={null}
{
  "error": {
    "code": "resource.not_supported",
    "message": "Operation not supported for this platform"
  },
  "request_id": "01HZAB1234CDEF5678GHIJ9012"
}
```

The `request_id` field is always present on every error response. Use it when reporting issues.

This is expected behavior, not a bug. Design your app to handle `501` gracefully.

## Auth types

| Type     | How it works                                                                                                                                                                                                                                  |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `oauth2` | `POST /accounts/connect` with a top-level `redirect_uri` returns an `auth_url`. Send the user there; SocialAPI handles the platform callback and redirects the user to your `redirect_uri` with the result. See [OAuth flows](/guides/oauth). |
| `apikey` | Pass the platform API key in `metadata` in `POST /accounts/connect`. Returns account ID immediately.                                                                                                                                          |

## Private replies

On Instagram and Facebook, posting a reply with `"private": true` sends a DM to the commenter instead of a public reply. This is the platform's native "Send Private Reply" feature. The `private` field is silently ignored on platforms that don't support it.