> ## 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 # Get conversation > 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. Retrieve details and metadata for a specific conversation. Requires accountId query parameter. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** GET /apis/v1/social/inbox/conversations/\{conversationId} * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/social/inbox/conversations/{conversationId}` * **conversationId:** path; 必填 * **accountId:** query; 必填 * **Runtime 事实版本:** 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-social.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "get_aisa_social_apis_v1_social_inbox_conversation_d09eb3", "method": "GET", "path": "/apis/v1/social/inbox/conversations/{conversationId}", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "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" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-social.json GET /apis/v1/social/inbox/conversations/{conversationId} 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/{conversationId}: get: summary: Get conversation 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. Retrieve details and metadata for a specific conversation. Requires accountId query parameter. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: get_aisa_social_apis_v1_social_inbox_conversation_d09eb3 parameters: - description: >- Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed. in: path name: conversationId required: true schema: type: string - description: One of your social accounts (acc_...). in: query name: accountId required: true schema: pattern: ^acc_[0-9A-Za-z]{22}$ type: string responses: '200': content: application/json: schema: properties: data: 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 id: 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' lastMessage: type: string lastMessageAt: format: date-time 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 participantVerifiedType: description: >- X verified badge type. Only present for X conversations. enum: - blue - government - business - none type: - string - 'null' participants: items: properties: id: type: string name: type: string type: object type: array platform: type: string status: enum: - active - archived type: string updatedTime: format: date-time type: string 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: object description: Conversation details 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.