> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # List conversations > Inbox. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Without profileId or accountId it reads your default profile. On a profile with an X account, pass accountId or a platform other than twitter: X bills each read. Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated. Supported platforms: Facebook, Instagram, X, Bluesky, Reddit, Telegram, WhatsApp, iMessage and SMS. ### X limitation X has replaced traditional DMs with encrypted "X Chat" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the /2/dm_events endpoint only returns legacy unencrypted DMs). This means some X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See X's docs on encrypted messaging for more details. ### Instagram and Facebook pre-connect history When one of these accounts is connected, AIsa replays the DM history the account already holds on Meta, so conversations that began before the account was connected appear here. Up to 500 conversations per account are replayed. - The replay runs in the background and can finish after a listing you have already taken. - Replayed conversations keep their original lastMessageAt, so they sort into date order rather than appearing at the top. - If you mirror this endpoint into your own store, re-run the sweep rather than relying on a single pass at connect time. - Replayed history emits no webhooks and is stored as already read, so it never affects unread counts. - Threads that Meta refuses to serve are skipped. - An account whose Instagram "connected tools" message access is turned off is not replayed at all. A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. ## Request contract * **Method and path:** GET /apis/v1/social/inbox/conversations * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/social/inbox/conversations` * **profileId:** query; optional * **platform:** query; optional * **status:** query; optional * **folder:** query; optional * **sortOrder:** query; optional * **limit:** query; optional * **cursor:** query; optional * **accountId:** query; optional * **tags:** query; optional * **Runtime facts:** 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/aisa-social.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "get_aisa_social_apis_v1_social_inbox_conversations", "method": "GET", "path": "/apis/v1/social/inbox/conversations", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by platform", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "facebook", "instagram", "twitter", "bluesky", "reddit", "telegram", "whatsapp", "imessage", "sms" ], "type": "string" } }, { "description": "Filter by conversation status", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "archived" ], "type": "string" } }, { "description": "`requests` lists Facebook Page Message Requests (threads from people the account has not accepted) live from Meta, each item with `folder: requests`.\n\nMeta has no accept call: replying moves a thread to the inbox, which is what POST /apis/v1/social/inbox/conversations/{conversationId}/accept does.\n\n- When Meta will not list the folder for the one account asked (`accountId`), the call answers 400 PLATFORM_LIMITATION. Across several accounts, the refusal is reported per account in meta.failedAccounts.\n- Instagram accounts (Instagram Login and Facebook Login) answer PLATFORM_LIMITATION, because Meta does not separate the folder on Instagram. Only Facebook Pages are served.\n\nOne page of up to `limit` threads. `pagination.hasMore` is true when threads past `limit` were cut (narrow with `accountId`). `pagination.nextCursor` is always null and a `cursor` answers 400.", "in": "query", "name": "folder", "required": false, "schema": { "default": "inbox", "enum": [ "inbox", "requests" ], "type": "string" } }, { "description": "Sort order by updated time", "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Maximum number of conversations to return; values above 100 are served as 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Pagination cursor for next page", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated contact tags. Returns only conversations whose contact has any of them. Cannot be combined with folder=requests.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## Cost and request rules A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar. ## OpenAPI ````yaml reference-contracts/aisa-social.json GET /apis/v1/social/inbox/conversations openapi: 3.1.0 info: description: '' title: AIsa Social version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:7f9742cb1ea233c648dcb290fdfbf24e53a27dcf900ec1386f83a8ef2e6b1bf9 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-social x-aisa-catalogs: aisa-social: title: AIsa Social description: '' x-aisa-document: facts_hash: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/social/inbox/conversations: get: summary: List conversations description: >- Inbox. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Without profileId or accountId it reads your default profile. On a profile with an X account, pass accountId or a platform other than twitter: X bills each read. Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated. Supported platforms: Facebook, Instagram, X, Bluesky, Reddit, Telegram, WhatsApp, iMessage and SMS. ### X limitation X has replaced traditional DMs with encrypted "X Chat" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the /2/dm_events endpoint only returns legacy unencrypted DMs). This means some X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See X's docs on encrypted messaging for more details. ### Instagram and Facebook pre-connect history When one of these accounts is connected, AIsa replays the DM history the account already holds on Meta, so conversations that began before the account was connected appear here. Up to 500 conversations per account are replayed. - The replay runs in the background and can finish after a listing you have already taken. - Replayed conversations keep their original lastMessageAt, so they sort into date order rather than appearing at the top. - If you mirror this endpoint into your own store, re-run the sweep rather than relying on a single pass at connect time. - Replayed history emits no webhooks and is stored as already read, so it never affects unread counts. - Threads that Meta refuses to serve are skipped. - An account whose Instagram "connected tools" message access is turned off is not replayed at all. A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. operationId: get_aisa_social_apis_v1_social_inbox_conversations parameters: - description: >- One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent. in: query name: profileId required: false schema: pattern: ^prf_[0-9A-Za-z]{22}$ type: string - description: Filter by platform in: query name: platform required: false schema: enum: - facebook - instagram - twitter - bluesky - reddit - telegram - whatsapp - imessage - sms type: string - description: Filter by conversation status in: query name: status required: false schema: enum: - active - archived type: string - description: >- `requests` lists Facebook Page Message Requests (threads from people the account has not accepted) live from Meta, each item with `folder: requests`. Meta has no accept call: replying moves a thread to the inbox, which is what POST /apis/v1/social/inbox/conversations/{conversationId}/accept does. - When Meta will not list the folder for the one account asked (`accountId`), the call answers 400 PLATFORM_LIMITATION. Across several accounts, the refusal is reported per account in meta.failedAccounts. - Instagram accounts (Instagram Login and Facebook Login) answer PLATFORM_LIMITATION, because Meta does not separate the folder on Instagram. Only Facebook Pages are served. One page of up to `limit` threads. `pagination.hasMore` is true when threads past `limit` were cut (narrow with `accountId`). `pagination.nextCursor` is always null and a `cursor` answers 400. in: query name: folder required: false schema: default: inbox enum: - inbox - requests type: string - description: Sort order by updated time in: query name: sortOrder required: false schema: default: desc enum: - asc - desc type: string - description: >- Maximum number of conversations to return; values above 100 are served as 100. in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer - description: Pagination cursor for next page in: query name: cursor required: false schema: type: string - description: One of your social accounts (acc_...). in: query name: accountId required: false schema: pattern: ^acc_[0-9A-Za-z]{22}$ type: string - description: >- Comma-separated contact tags. Returns only conversations whose contact has any of them. Cannot be combined with folder=requests. in: query name: tags required: false schema: type: string responses: '200': content: application/json: schema: properties: data: items: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string accountUsername: type: string adAttribution: description: >- The ad that opened the conversation, enriched from the ads AIsa syncs for the account owner. null when the conversation did not start from a Meta referral (ad click or ig.me / m.me ref link). Meta's referral carries the ad ID but no campaign or ad set ID. - Ad in your synced ads (`GET /apis/v1/ads`): `synced` is true and the ad name, campaign, ad set and ad account come from there. - Otherwise: `synced` is false, `name` falls back to the ad title (Instagram, Facebook) or headline (WhatsApp) Meta sent with the click, and the other fields are null. A team member limited to some profiles, or a profile-scoped API key, is enriched only from ads it can list with `GET /apis/v1/ads`; any other ad returns `synced` false. A non-null object with `adId` null is a referral that is not an ad click: an ig.me / m.me ref link (`name` null) or a WhatsApp click on a post (`ctwa_source_type` post, `name` is Meta's headline). Nothing is looked up and `synced` is false. properties: adAccountId: description: Meta ad account ID (act_...). Synced ads only. type: - string - 'null' adAccountName: description: Ad account name. Synced ads only. type: - string - 'null' adId: description: >- Meta's ad ID: `meta_ad_id` on Instagram and Facebook, `ctwa_source_id` on WhatsApp when `ctwa_source_type` is `ad`. Accepted by `GET /apis/v1/ads/{adId}`. type: - string - 'null' adSetId: description: Meta ad set ID. Synced ads only. type: - string - 'null' adSetName: description: Ad set name. Synced ads only. type: - string - 'null' campaignId: description: Meta campaign ID. Synced ads only. type: - string - 'null' campaignName: description: Campaign name. Synced ads only. type: - string - 'null' isExternal: description: >- True when the ad was created outside AIsa (synced from Ads Manager), false when created through AIsa, null when not synced. type: - boolean - 'null' name: description: >- The synced ad's name, else the ad title or headline Meta sent. type: - string - 'null' platformPostId: description: >- The post the ad promotes, from the synced ad or else Meta's `post_id` on the click. type: - string - 'null' synced: description: True when the ad was found in your synced ads. type: boolean required: - adAccountId - adAccountName - adId - adSetId - adSetName - campaignId - campaignName - isExternal - name - platformPostId - synced type: - object - 'null' businessScopedUserId: description: >- WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant. type: string folder: description: >- Present only on items listed with folder=requests: a Message Request the account has not accepted yet. enum: - requests type: string id: description: >- Opaque conversation identifier. Pass it back verbatim to any /apis/v1/social/inbox/conversations/{conversationId} route; do not assume a fixed format. type: string instagramProfile: description: >- Instagram profile data for the participant. Only present for Instagram conversations. properties: fetchedAt: description: >- When this profile data was last fetched from Instagram format: date-time type: - string - 'null' followerCount: description: The participant's follower count on Instagram type: - integer - 'null' isFollower: description: >- Whether the participant follows your Instagram business account type: - boolean - 'null' isFollowing: description: >- Whether your Instagram business account follows the participant type: - boolean - 'null' isVerified: description: >- Whether the participant is a verified Instagram user type: - boolean - 'null' type: - object - 'null' isGroup: description: >- iMessage only, true for a group thread. Manage it through the /apis/v1/social/imessage/groups/{conversationId} endpoints. type: boolean lastMessage: type: string metadata: description: >- Click attribution for a conversation that started from a Meta ad or a ref-tagged ig.me / m.me link, as Meta sent it. Absent when the conversation did not come from an attributable click. For the ad name, campaign and ad set, read `adAttribution`. **First referral wins.** Values come from the referral Meta delivers for the click. If the same person later arrives through another ad or link, the original values are kept. For the fresh referral per click, read the `message.received` / `referral.received` webhooks. On Instagram Click-to-Direct, Meta usually delivers the ad post first as an attachment-only `share` / `ig_post` message with no referral, then attaches the referral to the next message. WhatsApp exception: when Meta omits `ctwa_clid` from the referral, a later Meta automatic event can supply it and refresh `ctwa_captured_at`. Treat `ctwa_captured_at` as when AIsa stored the value, not when the click happened. **Two key families, one per surface, never together:** - `ctwa_*`: WhatsApp Click-to-WhatsApp. The ad ID is `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp. - `meta_ad_*`: Instagram Click-to-Direct, Facebook Messenger Click-to-Message, and ig.me / m.me ref links. The ad ID is `meta_ad_id` (ad clicks only; a link capture carries `meta_ad_ref` without it). `ctwa_clid` never appears here. Every key is optional and only keys Meta supplied are returned, so read defensively. Meta sends no campaign or ad set ID; those are resolved from your synced ads in `adAttribution`. More keys may be added; treat unknown keys as opaque strings. Key names differ from the `message.received` webhook on purpose. The webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`), while the stored conversation uses the prefixed names. Renaming either side would break existing integrations, so both spellings stay. properties: ctwa_body: description: >- WhatsApp only. Body text of the ad creative at click time. type: string ctwa_captured_at: description: >- WhatsApp only. When AIsa stored this referral. Always present when a WhatsApp referral was captured. format: date-time type: string ctwa_clid: description: >- WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it. type: string ctwa_headline: description: >- WhatsApp only. Headline of the ad creative at click time. type: string ctwa_image_url: description: >- WhatsApp only. Image of the ad creative at click time (image ads). type: string ctwa_media_type: description: >- WhatsApp only. Media type of the ad creative, image or video. type: string ctwa_source_id: description: >- WhatsApp only. The Meta ad ID the user clicked (or the post ID when `ctwa_source_type` is post). This is the WhatsApp equivalent of meta_ad_id. type: string ctwa_source_type: description: >- WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post). type: string ctwa_source_url: description: >- WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link. type: string ctwa_thumbnail_url: description: >- WhatsApp only. Thumbnail of the ad video at click time (video ads). type: string ctwa_video_url: description: >- WhatsApp only. Video of the ad creative at click time (video ads). type: string meta_ad_captured_at: description: >- Instagram and Facebook only. When AIsa stored this referral. Always present when an Instagram or Facebook referral was captured. format: date-time type: string meta_ad_flow_id: description: >- Instagram and Facebook only. The Meta flow the ad launched, for flow ads. type: string meta_ad_id: description: >- Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link. type: string meta_ad_photo_url: description: >- Instagram and Facebook only. Image of the ad creative at click time. type: string meta_ad_post_id: description: >- Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post. type: string meta_ad_product_id: description: >- Instagram and Facebook only. The catalogue product the user clicked, for product ads. type: string meta_ad_ref: description: >- Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link. type: string meta_ad_source: description: >- Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque). type: string meta_ad_title: description: >- Instagram and Facebook only. Title of the ad creative at click time. type: string meta_ad_type: description: >- Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD. type: string meta_ad_video_url: description: >- Instagram and Facebook only. Video of the ad creative at click time. type: string type: - object - 'null' pageId: description: >- The bare Facebook Page id behind the account, for Facebook and Instagram connected through Facebook Login. Null when the account has no Facebook Page. type: - string - 'null' participantId: type: string participantName: type: string participantPicture: type: - string - 'null' participantVerifiedType: description: >- X verified badge type. Only present for X conversations. enum: - blue - government - business - none type: - string - 'null' platform: type: string status: enum: - active - archived type: string threadControl: description: >- Present once a handover has touched the thread (WhatsApp, Facebook, Instagram). ai_agent: Meta Business Agent answers (WhatsApp) and new inbound arrive flagged metadata.standby; app: you hold control; other: another app does (a WhatsApp partner, or a Messenger / Instagram receiver such as Page Inbox). Change it with POST /apis/v1/social/inbox/conversations/{conversationId}/thread-control. enum: - app - ai_agent - other type: string unreadCount: description: >- Number of unread incoming messages, capped at 1000. Read from a replica, so it can trail a conversation you just marked read by a few seconds. maximum: 1000 type: - integer - 'null' updatedTime: format: date-time type: string url: description: >- Direct link to open the conversation on the platform (if available) type: - string - 'null' whatsappUsername: description: >- WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound. type: string type: object type: array meta: properties: accountsFailed: type: integer accountsQueried: type: integer accountsSkipped: description: >- Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it items: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string platform: type: string type: object type: array failedAccounts: items: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string accountUsername: type: - string - 'null' code: description: Error code if available type: - string - 'null' error: type: string platform: type: string retryAfter: description: Seconds to wait before retry (rate limits) type: - integer - 'null' type: object type: array lastUpdated: format: date-time type: string type: object pagination: properties: hasMore: type: boolean nextCursor: type: - string - 'null' type: object type: object description: Aggregated conversations default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: enum: - never - after_delay - after_reconnect - reconcile_first - null type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.