> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Messages

> Get messages or conversations for a messaging platform

export const XByoNotice = () => <Info>
  <strong>Targeting X/Twitter?</strong> Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
  <br /><br />
  <code>X-Twitter-OAuth1-Api-Key</code> — Your API Key (Consumer Key)<br />
  <code>X-Twitter-OAuth1-Api-Secret</code> — Your API Key Secret (Consumer Secret)
  <br /><br />
  Not linked yet? See the <a href="/dashboard/connect-social-accounts/x-twitter-byo-keys">full setup guide</a> to connect your X account.
  <br /><br />
  Your keys are never logged or stored by Ayrshare.
</Info>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "basic") {
      displayPlans = ["Basic", "Premium", "Business", "Enterprise"];
    } else if (lowerCasePlan === "business") {
      displayPlans = ["Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["business"]} maxPackRequired={false} />

<XByoNotice />

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.

<Note>
  **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.
</Note>

<Info>
  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](/apis/messages/overview#message-history-retrieval-for-facebook-and-instagram)
  section for more information.
</Info>

## Header Parameters

<HeaderAPI />

## Path Parameters

<ParamField path="platform" type="string" required>
  The platform to get the message: `facebook`, `instagram`, `twitter`
</ParamField>

## Query Parameters

<ParamField query="status" type="string" default="active" required>
  Return active conversations or archived conversations. Values: `active` or
  `archived`.
</ParamField>

<ParamField query="conversationId" type="string">
  Only return the specific conversation.
</ParamField>

<ParamField query="conversationsOnly" default={false} type="boolean">
  Return all the conversations. If `true` then conversationId field ignored.
</ParamField>

<ParamField query="limit" type="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.
</ParamField>

<ParamField query="next" type="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.
</ParamField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET https://api.ayrshare.com/api/messages/facebook
  ```

  ```javascript JavaScript theme={"system"}
  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);
    });
  ```

  ```python Python theme={"system"}
  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 PHP theme={"system"}
  <?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);

  ?>
  ```

  ```csharp C# theme={"system"}
  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}");
          }
      }
  }
  ```

  ```java Java theme={"system"}
  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());
          }
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
      "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"
  }
  ```

  ```json 200: Paginated (X/Twitter) theme={"system"}
  {
      "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="
          }
      }
  }
  ```

  ```json 200: Conversations theme={"system"}
  {
    "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"
  }
  ```

  ```json 400: Messaging Not Enabled theme={"system"}
  {
    "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."
  }
  ```
</ResponseExample>