> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt > Use this file to discover all available pages before exploring further. # Instagram Conversations > Instagram conversation history stored in FlowIQ. Also available as GET /conversations?platform=instagram. Only Instagram messages are returned, even for a contact merged with WhatsApp or email. Does not mark messages read or import earlier Instagram history. Contacts lists connected Instagram identities. Use contact_id or instagram_id for conversation-messages / find-by-instagram; contactId and instagramId aliases are also accepted. This endpoint is prepared for rollout and is not yet deployed. Read Instagram inbox history and contacts with the same `fiq_` API key used for WhatsApp. `GET /conversations?platform=instagram` is an alias with the same actions and response format. ## Available Actions | Action | Description | Required Parameters | | - | - | - | | `conversation-messages` | Get Instagram messages (default) | `contact_id` or `instagram_id` | | `contacts` | List contacts with an Instagram identity | — | | `find-by-instagram` | Find an Instagram contact | `instagram_id` or `contact_id` | ## Get Conversation Messages ```bash theme={null} curl "https://api.flowiq.live/instagram-conversations?instagram_id=17841400000000000&limit=20&page=1" \ -H "Authorization: Bearer fiq_YOUR_API_KEY" ``` Messages are newest first. Set `ascending=true` for oldest first, or `query=hello` to find a substring in message text. Only Instagram messages are returned, even for contacts merged with WhatsApp or another channel. ### Response (200) ```json theme={null} { "success": true, "contact": { "id": "00000000-0000-4000-8000-000000000003", "full_name": "Customer", "instagram_scoped_id": "17841400000000000", "instagram_username": "customer", "instagram_display_name": "Customer", "instagram_profile_picture_url": null, "instagram_last_message_at": "2026-10-08T10:00:00Z", "created_at": "2026-10-08T10:00:00Z" }, "messages": [ { "id": "00000000-0000-4000-8000-000000000001", "contact_id": "00000000-0000-4000-8000-000000000003", "message": "Hello!", "sender_type": "user-instagram", "created_at": "2026-10-08T10:00:00Z", "message_status": null, "instagram_message_id": "ig.message.example", "media_type": null, "media_url": null, "media_file_name": null, "assignee": null, "voice_note_transcription": null, "reactions": [], "read_at": null, "read_receipt_received": false, "sent_at": null, "delivered_at": null, "failed_at": null } ], "count": 1, "pagination": { "currentPage": 1, "totalPages": 1, "totalMessages": 1, "messagesPerPage": 20, "hasNextPage": false, "hasPrevPage": false } } ``` `count` is the number of messages on this page; `totalMessages` counts all messages matching the contact and search. Sender types are `user-instagram` (customer), `human-instagram` (staff or API) and `bot-instagram` (automated reply). ## List Contacts ```bash theme={null} curl "https://api.flowiq.live/instagram-conversations?action=contacts&limit=50&page=1&query=customer" \ -H "Authorization: Bearer fiq_YOUR_API_KEY" ``` Returns `success`, `contacts`, `count` and `pagination`. Contacts use the same shape as `contact` above. `query` searches the Instagram username. Pagination uses `totalContacts` and `contactsPerPage` in place of the message fields. Contacts are ordered by their most recent Instagram message, then contact ID. ## Find a Contact ```bash theme={null} curl "https://api.flowiq.live/instagram-conversations?action=find-by-instagram&instagram_id=17841400000000000" \ -H "Authorization: Bearer fiq_YOUR_API_KEY" ``` Returns `success: true` and `contact`. An ID that does not belong to an Instagram contact in your organization returns `404`. ## Query Parameters | Parameter | Description | | - | - | | `action` | Defaults to `conversation-messages`; also accepts `contacts` or `find-by-instagram` | | `contact_id` | FlowIQ contact UUID; `contactId` is an alias | | `instagram_id` | Numeric Instagram-scoped ID as a string; `instagramId` is an alias | | `limit` | 1–100; defaults to 10 messages or 50 contacts | | `page` | 1–1000000; defaults to 1 | | `ascending` | `true` for oldest-first messages; defaults to `false` | | `query` | Substring in message text, or username when listing contacts | When both recipient identifiers are supplied they must match. The endpoint reads stored history without marking messages as read or fetching earlier Instagram history. ## OpenAPI ````yaml flowiq-api-reference/openapi-instagram.json GET /instagram-conversations openapi: 3.1.0 info: title: FlowIQ Instagram API version: 1.0.0 description: >- Prepared for rollout; not yet deployed. Instagram messaging through FlowIQ, using the same organization API key as WhatsApp. servers: - url: https://api.flowiq.live description: FlowIQ Production API security: - BearerAuth: [] paths: /instagram-conversations: get: tags: - Instagram summary: Read Instagram messages and contacts description: >- Instagram conversation history stored in FlowIQ. Also available as GET /conversations?platform=instagram. Only Instagram messages are returned, even for a contact merged with WhatsApp or email. Does not mark messages read or import earlier Instagram history. Contacts lists connected Instagram identities. Use contact_id or instagram_id for conversation-messages / find-by-instagram; contactId and instagramId aliases are also accepted. operationId: getInstagramConversations parameters: - name: action in: query schema: type: string enum: - conversation-messages - contacts - find-by-instagram default: conversation-messages - name: contact_id in: query schema: type: string format: uuid - name: instagram_id in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 10 description: Defaults to 50 for contacts - name: page in: query schema: type: integer minimum: 1 maximum: 1000000 default: 1 - name: ascending in: query schema: type: boolean default: false description: Message ordering; newest first by default - name: query in: query schema: type: string description: >- Substring search in message text, or Instagram username when listing contacts responses: '200': description: Messages, contacts or a contact, according to action content: application/json: schema: type: object properties: success: type: boolean contact: type: object properties: id: type: string format: uuid full_name: type: - string - 'null' instagram_scoped_id: type: string instagram_username: type: - string - 'null' instagram_display_name: type: - string - 'null' instagram_profile_picture_url: type: - string - 'null' instagram_last_message_at: type: - string - 'null' format: date-time created_at: type: string format: date-time contacts: type: array items: type: object properties: id: type: string format: uuid full_name: type: - string - 'null' instagram_scoped_id: type: string instagram_username: type: - string - 'null' instagram_display_name: type: - string - 'null' instagram_profile_picture_url: type: - string - 'null' instagram_last_message_at: type: - string - 'null' format: date-time created_at: type: string format: date-time messages: type: array items: type: object properties: id: type: string format: uuid instagram_message_id: type: - string - 'null' message: type: - string - 'null' sender_type: type: string created_at: type: string format: date-time media_type: type: - string - 'null' media_url: type: - string - 'null' message_status: type: - string - 'null' read_receipt_received: type: - boolean - 'null' read_at: type: - string - 'null' format: date-time contact_id: type: string format: uuid media_file_name: type: - string - 'null' assignee: type: - string - 'null' voice_note_transcription: type: - string - 'null' reactions: type: - array - 'null' items: type: object sent_at: type: - string - 'null' format: date-time delivered_at: type: - string - 'null' format: date-time failed_at: type: - string - 'null' format: date-time count: type: integer pagination: type: object description: >- currentPage, totalPages, totalMessages/messagesPerPage (or totalContacts/contactsPerPage), hasNextPage, hasPrevPage '400': description: Invalid input or Instagram is not connected content: application/json: schema: type: object properties: success: type: boolean const: false error: type: string '401': description: Missing, expired or revoked fiq_ API key content: application/json: schema: type: object properties: success: type: boolean const: false error: type: string '404': description: Contact not found in the API key’s organization content: application/json: schema: type: object properties: success: type: boolean const: false error: type: string '500': description: >- Send or database operation failed; check the conversation before retrying an ambiguous send content: application/json: schema: type: object properties: success: type: boolean const: false error: type: string security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: >- Your FlowIQ API key (from Settings → Profile → API Keys), sent as a bearer token. Format: `Bearer fiq_YOUR_API_KEY` bearerFormat: fiq_ API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.