Read Instagram messages and contacts
curl --request GET \
--url https://api.flowiq.live/instagram-conversations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.flowiq.live/instagram-conversations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.flowiq.live/instagram-conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.flowiq.live/instagram-conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.flowiq.live/instagram-conversations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.flowiq.live/instagram-conversations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.flowiq.live/instagram-conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"full_name": "<string>",
"instagram_scoped_id": "<string>",
"instagram_username": "<string>",
"instagram_display_name": "<string>",
"instagram_profile_picture_url": "<string>",
"instagram_last_message_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
},
"contacts": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"full_name": "<string>",
"instagram_scoped_id": "<string>",
"instagram_username": "<string>",
"instagram_display_name": "<string>",
"instagram_profile_picture_url": "<string>",
"instagram_last_message_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}
],
"messages": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"instagram_message_id": "<string>",
"message": "<string>",
"sender_type": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"media_type": "<string>",
"media_url": "<string>",
"message_status": "<string>",
"read_receipt_received": true,
"read_at": "2023-11-07T05:31:56Z",
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"media_file_name": "<string>",
"assignee": "<string>",
"voice_note_transcription": "<string>",
"reactions": [
{}
],
"sent_at": "2023-11-07T05:31:56Z",
"delivered_at": "2023-11-07T05:31:56Z",
"failed_at": "2023-11-07T05:31:56Z"
}
],
"count": 123,
"pagination": {}
}{
"success": false,
"error": "<string>"
}{
"success": false,
"error": "<string>"
}{
"success": false,
"error": "<string>"
}{
"success": false,
"error": "<string>"
}Instagram
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.
GET
/
instagram-conversations
Read Instagram messages and contacts
curl --request GET \
--url https://api.flowiq.live/instagram-conversations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.flowiq.live/instagram-conversations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.flowiq.live/instagram-conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.flowiq.live/instagram-conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.flowiq.live/instagram-conversations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.flowiq.live/instagram-conversations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.flowiq.live/instagram-conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"full_name": "<string>",
"instagram_scoped_id": "<string>",
"instagram_username": "<string>",
"instagram_display_name": "<string>",
"instagram_profile_picture_url": "<string>",
"instagram_last_message_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
},
"contacts": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"full_name": "<string>",
"instagram_scoped_id": "<string>",
"instagram_username": "<string>",
"instagram_display_name": "<string>",
"instagram_profile_picture_url": "<string>",
"instagram_last_message_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}
],
"messages": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"instagram_message_id": "<string>",
"message": "<string>",
"sender_type": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"media_type": "<string>",
"media_url": "<string>",
"message_status": "<string>",
"read_receipt_received": true,
"read_at": "2023-11-07T05:31:56Z",
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"media_file_name": "<string>",
"assignee": "<string>",
"voice_note_transcription": "<string>",
"reactions": [
{}
],
"sent_at": "2023-11-07T05:31:56Z",
"delivered_at": "2023-11-07T05:31:56Z",
"failed_at": "2023-11-07T05:31:56Z"
}
],
"count": 123,
"pagination": {}
}{
"success": false,
"error": "<string>"
}{
"success": false,
"error": "<string>"
}{
"success": false,
"error": "<string>"
}{
"success": false,
"error": "<string>"
}Read Instagram inbox history and contacts with the same
Messages are newest first. Set
Returns
Returns
When both recipient identifiers are supplied they must match. The endpoint reads stored history without marking messages as read or fetching earlier Instagram history.
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
curl "https://api.flowiq.live/instagram-conversations?instagram_id=17841400000000000&limit=20&page=1" \
-H "Authorization: Bearer fiq_YOUR_API_KEY"
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)
{
"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
curl "https://api.flowiq.live/instagram-conversations?action=contacts&limit=50&page=1&query=customer" \
-H "Authorization: Bearer fiq_YOUR_API_KEY"
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
curl "https://api.flowiq.live/instagram-conversations?action=find-by-instagram&instagram_id=17841400000000000" \
-H "Authorization: Bearer fiq_YOUR_API_KEY"
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 |
Authorizations
Query Parameters
Response
Messages, contacts or a contact, according to action

