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>"
}This endpoint is prepared for rollout and is not yet deployed.
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
Your FlowIQ API key (from Settings → Profile → API Keys), sent as a bearer token. Format: Bearer fiq_YOUR_API_KEY
Query Parameters
Available options:
conversation-messages, contacts, find-by-instagram Defaults to 50 for contacts
Required range:
1 <= x <= 100Required range:
1 <= x <= 1000000Message ordering; newest first by default
Substring search in message text, or Instagram username when listing contacts
Response
Messages, contacts or a contact, according to action

