Get Messages

Get messages or conversations for a messaging platform

GET /messages/:platform

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/messages/facebook

const apiKey = 'API_KEY';
const url = 'https://api.ayrshare.com/api/messages/facebook';

const headers = {
  'Authorization': `Bearer ${apiKey}`,
};

fetch(url, {
  method: 'GET',
  headers: headers,
})
  .then(response => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error(`Request failed. Status code: ${response.status}`);
    }
  })
  .then(data => {
    console.log('Response:', data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

import requests

api_key = 'API_KEY'
url = 'https://api.ayrshare.com/api/messages/facebook'

headers = {
    'Authorization': f'Bearer {api_key}',
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print('Response:', data)
else:
    print(f'Request failed. Status code: {response.status_code}')

<?php

$apiKey = 'API_KEY';
$url = 'https://api.ayrshare.com/api/messages/facebook';

$headers = [
    'Authorization: Bearer ' . $apiKey,
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if ($response === false) {
    $error = curl_error($ch);
    echo 'Error: ' . $error;
} else {
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($statusCode === 200) {
        $responseData = json_decode($response, true);
        print_r($responseData);
    } else {
        echo 'Request failed. Status code: ' . $statusCode;
    }
}

curl_close($ch);

?>

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Text.Json;

class Program
{
    static async Task Main()
    {
        string apiKey = "API_KEY";
        string url = "https://api.ayrshare.com/api/messages/facebook";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

        try
        {
            var response = await client.GetAsync(url);

            if (response.IsSuccessStatusCode)
            {
                var responseBody = await response.Content.ReadAsStringAsync();
                var responseData = JsonSerializer.Deserialize<dynamic>(responseBody);

                Console.WriteLine("Response:");
                Console.WriteLine(responseData);
            }
            else
            {
                Console.WriteLine($"Request failed. Status code: {response.StatusCode}");
            }
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) {
        String apiKey = "API_KEY";
        String url = "https://api.ayrshare.com/api/messages/facebook";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + apiKey)
                .GET()
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                String responseBody = response.body();
                System.out.println("Response:");
                System.out.println(responseBody);
            } else {
                System.out.println("Request failed. Status code: " + response.statusCode());
            }
        } catch (IOException | InterruptedException e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}

200: Success

{
    "status": "success",
    "messages": [
        {
            "senderId": "106638148652444",
            "senderDetails": {
                "name": "Ayrshare"
            },
            "conversationId": "t_10161117434308444",
            "created": "2024-06-06T00:54:32.455Z",
            "action": "sent",
            "recipientId": "7101149746568444",
            "id": "m_JH6o-yS83JoxWmQaLrmgSaHwGtfTgQ",
            "message": "Howdy!",
            "platform": "facebook",
            "reactions": {
                "7101149746568522": "😆". // Reaction by the customer on the Howdy! message
            }
        },
        {
            "recipientDetails": {
                "name": "Sara Smith",
                "id": "736532028017333",
                "picture": "https://img.ayrshare.com/333/messages/facebook-eTZzhE2b.jpeg"
            },
            "senderId": "106638148652329",
            "attachments": [
                {
                    "type": "image",
                    "url": "https://scontent.xx.fbcdn.net/v/t1.15752-9/490986808_1193328359195158"
                }
            ],
            "conversationId": "t_3567590438533",
            "created": "2024-06-06T00:54:32.455Z",
            "action": "sent",
            "recipientId": "736532028017333",
            "id": "m_WJlfgzopxfdRM1wFTKYHKv7zh75P",
            "updated": "2024-06-06T00:54:32.455Z",
            "platform": "facebook",
            "senderDetails": {
                "name": "Ayrshare"
            }
        },
        {
            "senderId": "7101149746568444",
            "senderDetails": {
                "name": "John Smith",
                "profileImage": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
            },
            "conversationId": "t_10161117434308444",
            "created": "2024-06-06T00:54:28.102Z",
            "action": "received",
            "recipientId": "106638148652329",
            "id": "m_HGbotYJUmf4AzyPlJ-2uZqHwGtfTgQihX",
            "message": "Look up!",
            "platform": "facebook"
        },
        {
            "senderId": "7101149746568444",
            "senderDetails": {
                "name": "John Smith",
                "profileImage": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
            },
            "conversationId": "t_10161117434308444",
            "created": "2024-06-06T00:49:11.679Z",
            "action": "received",
            "recipientId": "106638148652444",
            "id": "m_jXoYQIwTXaq2u06PG6Z8vaHwGtfTgQ",
            "message": "How is the weather?",
            "platform": "facebook"
        }
    ],
    "lastUpdated": "2024-06-09T21:46:04.233Z",
    "nextUpdate": "2024-06-09T21:47:04.233Z"
}

{
    "status": "success",
    "messages": [
        {
            "id": "1893410668991234567",
            "conversationId": "1234567890-9876543210",
            "senderId": "9876543210",
            "created": "2024-06-09T21:30:00.000Z",
            "message": "Hey, how are you?",
            "action": "received",
            "senderDetails": {
                "name": "Jane Doe",
                "username": "janedoe"
            }
        },
        {
            "id": "1893410668991234566",
            "conversationId": "1234567890-9876543210",
            "senderId": "1234567890",
            "created": "2024-06-09T21:28:00.000Z",
            "message": "Hello!",
            "action": "sent",
            "senderDetails": {
                "name": "My Account",
                "username": "myaccount"
            }
        }
    ],
    "messagesCount": 2,
    "lastUpdated": "2024-06-09T21:46:04.233Z",
    "nextUpdate": "2024-06-09T21:46:19.233Z",
    "meta": {
        "pagination": {
            "hasMore": true,
            "limit": 5,
            "next": "eyJwYWdpbmF0aW9uVG9rZW4iOiIxODkzNDEwNjY4OTkxMjM0NTY1In0="
        }
    }
}

{
  "status": "success",
  "conversationIds": ["t_10161117434308444", "t_356759043857444"],
  "conversationsDetails": [
    {
      "id": "t_10161117434308444",
      "participant": {
        "name": "John Smith",
        "id": "7101149746568444",
        "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
      },
      "status": "active",
      "watermark": 1717889607444
    },
    {
      "id": "t_356759043857444",
      "participant": {
        "name": "Sara Johnson",
        "id": "7365320280173444",
        "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
      },
      "status": "active"
    }
  ],
  "lastUpdated": "2024-06-09T21:46:04.233Z",
  "nextUpdate": "2024-06-09T21:47:04.233Z"
}

{
  "action": "messages",
  "status": "error",
  "code": 361,
  "message": "Messaging is not enabled for this User Profile. Please subscribe to Messaging and activate Messaging for this User Profile."
}

Get messages or conversations for a messaging platform.

Retrieval times differ on each social network. On Facebook and Instagram, messages are available via Ayrshare in real time. On X/Twitter, there is a delay of up to 3 minutes to see new message updates. Please contact support to learn more about the Enterprise Plan if you need real-time X/Twitter message access.

Response caching: GET messages responses are cached to optimize performance. For Facebook and Instagram, responses are cached for 60 seconds. For X/Twitter, responses are cached for 15 seconds to better support polling. The lastUpdated and nextUpdate fields in the response indicate when the data was last fetched and when fresh data will be available.

Initial message history retrieval for Facebook and Instagram is limited to the last 20 messages. Please see the Message History Retrieval for Facebook and Instagram section for more information.

Header Parameters

Path Parameters

platform · string · required

The platform to get the message: facebook, instagram, twitter

Query Parameters

status · string · default: "active" · required

Return active conversations or archived conversations. Values: active or archived.

conversationId · string

Only return the specific conversation.

conversationsOnly · boolean · default: false

Return all the conversations. If true then conversationId field ignored.

limit · integer

X/Twitter only. Limit the number of messages returned per request (1–100). Enables efficient polling without a full history sync. Use with next for pagination. If omitted, the default behavior (full message retrieval) is used.

next · string

X/Twitter only. Encrypted pagination cursor returned from a previous request’s meta.pagination.next field. Use with limit to fetch the next page of results.

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/messages/facebook

const apiKey = 'API_KEY';
const url = 'https://api.ayrshare.com/api/messages/facebook';

const headers = {
  'Authorization': `Bearer ${apiKey}`,
};

fetch(url, {
  method: 'GET',
  headers: headers,
})
  .then(response => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error(`Request failed. Status code: ${response.status}`);
    }
  })
  .then(data => {
    console.log('Response:', data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

import requests

api_key = 'API_KEY'
url = 'https://api.ayrshare.com/api/messages/facebook'

headers = {
    'Authorization': f'Bearer {api_key}',
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print('Response:', data)
else:
    print(f'Request failed. Status code: {response.status_code}')

<?php

$apiKey = 'API_KEY';
$url = 'https://api.ayrshare.com/api/messages/facebook';

$headers = [
    'Authorization: Bearer ' . $apiKey,
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if ($response === false) {
    $error = curl_error($ch);
    echo 'Error: ' . $error;
} else {
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($statusCode === 200) {
        $responseData = json_decode($response, true);
        print_r($responseData);
    } else {
        echo 'Request failed. Status code: ' . $statusCode;
    }
}

curl_close($ch);

?>

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Text.Json;

class Program
{
    static async Task Main()
    {
        string apiKey = "API_KEY";
        string url = "https://api.ayrshare.com/api/messages/facebook";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

        try
        {
            var response = await client.GetAsync(url);

            if (response.IsSuccessStatusCode)
            {
                var responseBody = await response.Content.ReadAsStringAsync();
                var responseData = JsonSerializer.Deserialize<dynamic>(responseBody);

                Console.WriteLine("Response:");
                Console.WriteLine(responseData);
            }
            else
            {
                Console.WriteLine($"Request failed. Status code: {response.StatusCode}");
            }
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) {
        String apiKey = "API_KEY";
        String url = "https://api.ayrshare.com/api/messages/facebook";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + apiKey)
                .GET()
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                String responseBody = response.body();
                System.out.println("Response:");
                System.out.println(responseBody);
            } else {
                System.out.println("Request failed. Status code: " + response.statusCode());
            }
        } catch (IOException | InterruptedException e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}

200: Success

{
    "status": "success",
    "messages": [
        {
            "senderId": "106638148652444",
            "senderDetails": {
                "name": "Ayrshare"
            },
            "conversationId": "t_10161117434308444",
            "created": "2024-06-06T00:54:32.455Z",
            "action": "sent",
            "recipientId": "7101149746568444",
            "id": "m_JH6o-yS83JoxWmQaLrmgSaHwGtfTgQ",
            "message": "Howdy!",
            "platform": "facebook",
            "reactions": {
                "7101149746568522": "😆". // Reaction by the customer on the Howdy! message
            }
        },
        {
            "recipientDetails": {
                "name": "Sara Smith",
                "id": "736532028017333",
                "picture": "https://img.ayrshare.com/333/messages/facebook-eTZzhE2b.jpeg"
            },
            "senderId": "106638148652329",
            "attachments": [
                {
                    "type": "image",
                    "url": "https://scontent.xx.fbcdn.net/v/t1.15752-9/490986808_1193328359195158"
                }
            ],
            "conversationId": "t_3567590438533",
            "created": "2024-06-06T00:54:32.455Z",
            "action": "sent",
            "recipientId": "736532028017333",
            "id": "m_WJlfgzopxfdRM1wFTKYHKv7zh75P",
            "updated": "2024-06-06T00:54:32.455Z",
            "platform": "facebook",
            "senderDetails": {
                "name": "Ayrshare"
            }
        },
        {
            "senderId": "7101149746568444",
            "senderDetails": {
                "name": "John Smith",
                "profileImage": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
            },
            "conversationId": "t_10161117434308444",
            "created": "2024-06-06T00:54:28.102Z",
            "action": "received",
            "recipientId": "106638148652329",
            "id": "m_HGbotYJUmf4AzyPlJ-2uZqHwGtfTgQihX",
            "message": "Look up!",
            "platform": "facebook"
        },
        {
            "senderId": "7101149746568444",
            "senderDetails": {
                "name": "John Smith",
                "profileImage": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
            },
            "conversationId": "t_10161117434308444",
            "created": "2024-06-06T00:49:11.679Z",
            "action": "received",
            "recipientId": "106638148652444",
            "id": "m_jXoYQIwTXaq2u06PG6Z8vaHwGtfTgQ",
            "message": "How is the weather?",
            "platform": "facebook"
        }
    ],
    "lastUpdated": "2024-06-09T21:46:04.233Z",
    "nextUpdate": "2024-06-09T21:47:04.233Z"
}

{
    "status": "success",
    "messages": [
        {
            "id": "1893410668991234567",
            "conversationId": "1234567890-9876543210",
            "senderId": "9876543210",
            "created": "2024-06-09T21:30:00.000Z",
            "message": "Hey, how are you?",
            "action": "received",
            "senderDetails": {
                "name": "Jane Doe",
                "username": "janedoe"
            }
        },
        {
            "id": "1893410668991234566",
            "conversationId": "1234567890-9876543210",
            "senderId": "1234567890",
            "created": "2024-06-09T21:28:00.000Z",
            "message": "Hello!",
            "action": "sent",
            "senderDetails": {
                "name": "My Account",
                "username": "myaccount"
            }
        }
    ],
    "messagesCount": 2,
    "lastUpdated": "2024-06-09T21:46:04.233Z",
    "nextUpdate": "2024-06-09T21:46:19.233Z",
    "meta": {
        "pagination": {
            "hasMore": true,
            "limit": 5,
            "next": "eyJwYWdpbmF0aW9uVG9rZW4iOiIxODkzNDEwNjY4OTkxMjM0NTY1In0="
        }
    }
}

{
  "status": "success",
  "conversationIds": ["t_10161117434308444", "t_356759043857444"],
  "conversationsDetails": [
    {
      "id": "t_10161117434308444",
      "participant": {
        "name": "John Smith",
        "id": "7101149746568444",
        "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
      },
      "status": "active",
      "watermark": 1717889607444
    },
    {
      "id": "t_356759043857444",
      "participant": {
        "name": "Sara Johnson",
        "id": "7365320280173444",
        "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic/"
      },
      "status": "active"
    }
  ],
  "lastUpdated": "2024-06-09T21:46:04.233Z",
  "nextUpdate": "2024-06-09T21:47:04.233Z"
}

{
  "action": "messages",
  "status": "error",
  "code": 361,
  "message": "Messaging is not enabled for this User Profile. Please subscribe to Messaging and activate Messaging for this User Profile."
}