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

# Nachrichten abrufen

> Nachrichten oder Konversationen für eine Messaging-Plattform abrufen

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 />

Rufen Sie Nachrichten oder Konversationen für eine Messaging-Plattform ab.

Die Abrufzeiten unterscheiden sich je nach sozialem Netzwerk. Auf Facebook und Instagram sind Nachrichten über Ayrshare in Echtzeit verfügbar. Auf X/Twitter gibt es eine Verzögerung von bis zu 3 Minuten, bis neue Nachrichten-Updates sichtbar sind. Bitte wenden Sie sich an den Support, um mehr über den Enterprise Plan zu erfahren, wenn Sie Echtzeitzugriff auf X/Twitter-Nachrichten benötigen.

<Note>
  **Response-Caching:** GET-Nachrichten-Antworten werden zur Performance-Optimierung zwischengespeichert. Für **Facebook** und **Instagram** werden Antworten **60 Sekunden** lang zwischengespeichert. Für **X/Twitter** werden Antworten **15 Sekunden** lang zwischengespeichert, um Polling besser zu unterstützen. Die Felder `lastUpdated` und `nextUpdate` in der Antwort geben an, wann die Daten zuletzt abgerufen wurden und wann neue Daten verfügbar sein werden.
</Note>

<Info>
  Der initiale Abruf des Nachrichtenverlaufs für Facebook und Instagram ist auf die
  letzten 20 Nachrichten beschränkt. Weitere Informationen finden Sie im Abschnitt [Abruf des Nachrichtenverlaufs für Facebook und
  Instagram](/apis/messages/overview#message-history-retrieval-for-facebook-and-instagram).
</Info>

## Header-Parameter

<HeaderAPI />

## Pfad-Parameter

<ParamField path="platform" type="string" required>
  Die Plattform, für die die Nachricht abgerufen werden soll: `facebook`, `instagram`, `twitter`
</ParamField>

## Query-Parameter

<ParamField query="status" type="string" default="active" required>
  Gibt aktive oder archivierte Konversationen zurück. Werte: `active` oder
  `archived`.
</ParamField>

<ParamField query="conversationId" type="string">
  Gibt nur die angegebene Konversation zurück.
</ParamField>

<ParamField query="conversationsOnly" default={false} type="boolean">
  Gibt alle Konversationen zurück. Wenn `true`, wird das Feld conversationId ignoriert.
</ParamField>

<ParamField query="limit" type="integer">
  **Nur X/Twitter.** Begrenzt die Anzahl der pro Anfrage zurückgegebenen Nachrichten (1–100). Ermöglicht effizientes Polling ohne vollständigen Verlaufsabgleich. Verwenden Sie dies zusammen mit `next` für die Paginierung. Wenn weggelassen, wird das Standardverhalten (vollständiger Nachrichtenabruf) verwendet.
</ParamField>

<ParamField query="next" type="string">
  **Nur X/Twitter.** Verschlüsselter Paginierungs-Cursor, der aus dem Feld `meta.pagination.next` einer vorherigen Anfrage zurückgegeben wird. Verwenden Sie ihn zusammen mit `limit`, um die nächste Ergebnisseite abzurufen.
</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>