> ## 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.

# Lấy Tin nhắn

> Lấy tin nhắn hoặc cuộc trò chuyện cho một nền tảng messaging

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 />
  <strong>One-time setup per Ayrshare account.</strong> You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do <em>not</em> create a new app per customer.
  <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 === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "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 />

Lấy tin nhắn hoặc cuộc trò chuyện cho một nền tảng messaging.

Thời gian truy xuất khác nhau trên từng mạng xã hội. Trên Facebook và Instagram, tin nhắn có sẵn qua Ayrshare theo thời gian thực. Trên X/Twitter, có độ trễ lên đến 3 phút để thấy các cập nhật tin nhắn mới. Vui lòng liên hệ hỗ trợ để tìm hiểu thêm về gói Enterprise Plan nếu bạn cần truy cập tin nhắn X/Twitter theo thời gian thực.

<Note>
  **Bộ nhớ đệm phản hồi:** Các phản hồi GET messages được lưu vào bộ nhớ đệm để tối ưu hóa hiệu suất. Đối với **Facebook** và **Instagram**, các phản hồi được lưu vào bộ nhớ đệm trong **60 giây**. Đối với **X/Twitter**, các phản hồi được lưu vào bộ nhớ đệm trong **15 giây** để hỗ trợ polling tốt hơn. Các trường `lastUpdated` và `nextUpdate` trong phản hồi cho biết khi dữ liệu được lấy lần cuối và khi dữ liệu mới sẽ có sẵn.
</Note>

<Info>
  Truy xuất lịch sử tin nhắn ban đầu cho Facebook và Instagram được giới hạn ở
  20 tin nhắn cuối cùng. Vui lòng xem phần [Truy xuất Lịch sử Tin nhắn cho Facebook và
  Instagram](/apis/messages/overview#message-history-retrieval-for-facebook-and-instagram)
  để biết thêm thông tin.
</Info>

## Tham số Header

<HeaderAPI />

## Tham số Path

<ParamField path="platform" type="string" required>
  Nền tảng để lấy tin nhắn: `facebook`, `instagram`, `twitter`
</ParamField>

## Tham số Query

<ParamField query="status" type="string" default="active" required>
  Trả về các cuộc trò chuyện đang hoạt động hoặc cuộc trò chuyện đã lưu trữ. Giá trị: `active` hoặc
  `archived`.
</ParamField>

<ParamField query="conversationId" type="string">
  Chỉ trả về cuộc trò chuyện cụ thể.
</ParamField>

<ParamField query="conversationsOnly" default={false} type="boolean">
  Trả về tất cả các cuộc trò chuyện. Nếu `true` thì trường conversationId sẽ bị bỏ qua.
</ParamField>

<ParamField query="limit" type="integer">
  **Chỉ dành cho X/Twitter.** Giới hạn số lượng tin nhắn trả về mỗi request (1–100). Cho phép polling hiệu quả mà không cần đồng bộ lịch sử đầy đủ. Sử dụng với `next` để phân trang. Nếu bỏ qua, hành vi mặc định (truy xuất tin nhắn đầy đủ) sẽ được sử dụng.
</ParamField>

<ParamField query="next" type="string">
  **Chỉ dành cho X/Twitter.** Con trỏ phân trang đã mã hóa được trả về từ trường `meta.pagination.next` của request trước. Sử dụng với `limit` để lấy trang kết quả tiếp theo.
</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": "😆". // Phản ứng của khách hàng đối với tin nhắn Howdy!
              }
          },
          {
              "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>