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

# Messages API Overview

> Send and receive direct messages on Facebook, Instagram, X/Twitter, and WhatsApp

The Messaging API allows you to manage direct messages (DM) to correspondents who contact your User Profiles.
A correspondent is the person with whom your user (User Profile) is communicating with.
A conversation is a series of messages between your user (User Profile) and their correspondent.

<ul>
  <li>
    The Messaging API is included with all Ayrshare Business Plans and as a paid add-on for Premium
    plans.
  </li>

  <li>
    For both Business and Premium plans, you must activate Messaging in the Account page of the
    Ayrshare dashboard.
  </li>

  <li>
    Messaging is available for Facebook Messenger, Instagram Direct Messenger,
    X Direct Messages, and WhatsApp (Private Beta).
  </li>
</ul>

> [!NOTE]
>
> **WhatsApp is in Private Beta.** Send and receive WhatsApp messages through
> the Messaging API. If you'd like early access, email
> [lotty@ayrshare.com](mailto:lotty@ayrshare.com).

> [card] [Learn more about the Messaging API](https://www.ayrshare.com/ayrshare-messaging-api-for-facebook-instagram-and-x-twitter/)

## Key Messaging Features

<ul>
  <li>Manage your users' conversations with correspondents.</li>
  <li>Sending text, image, video, and emoji messages on behalf of your users.</li>
  <li>Retrieving complete conversation histories.</li>
  <li>Setting up automated message responses.</li>

  <li>
    Receiving real-time updates via webhooks for messages received, message reactions, read
    receipts.
  </li>
</ul>

## Enable Messaging

### Enable Your Ayrshare Account and User Profiles

You must first enable messaging for your overall Ayrshare account to manage DMs. In the Ayrshare dashboard go to the [Account page](https://app.ayrshare.com/account) and click the "Learn More" button and then "Enable". At this point you have enabled messaging for your overall account, *but have not activated messaging for individual User Profiles*.

You can activate messaging for individual User Profiles either in the [User Profiles page](https://app.ayrshare.com/manage-profiles) by clicking "Messaging Active" checkbox for each profile or using the create or update [profiles endpoint](https://www.ayrshare.com/docs/apis/profiles/overview.md).

Facebook and Instagram grant the messaging permissions when an account is linked, so activate messaging before you link accounts. This works the same whether you activate messaging in the dashboard or with the profiles endpoint:

* **Accounts linked after messaging was activated** need no relink.
* **Accounts linked before messaging was activated** need a relink if their "Messaging" badge shows as a warning instead of the normal badge.
* **Accounts linked through Ayrshare Connect** (the [widget](https://www.ayrshare.com/docs/multiple-users/connect-widget.md) or [direct mode](https://www.ayrshare.com/docs/multiple-users/connect-direct-mode.md)) never get the messaging permissions. To use messaging, relink them on the User Profile's social linking page.

Relink accounts on the [Social Accounts page](https://app.ayrshare.com/social-accounts) or on the User Profile's [social linking page](https://www.ayrshare.com/docs/multiple-users/user-integration.md). To skip the relink, set `messagingActive: true` when you [create the User Profile](https://www.ayrshare.com/docs/apis/profiles/create-profile.md), before linking any accounts.

Accounts that are ready show the normal "Messaging" badge.

> [!NOTE]
>
> The Messages endpoints report these setup steps with distinct error codes, so you can tell them apart
> programmatically:
>
> * **`403` / code `361`** — Messaging is not enabled. Either the account is not subscribed to Messaging, or this
>   User Profile has not been activated. Complete the steps above; relinking a social account will not help.
> * **`400` / code `362`** — Messaging is active for the User Profile, but this **Facebook or Instagram** account
>   still needs to be relinked. This response includes `resolution: { "relink": true }`.

![Messaging badge](https://mintcdn.com/ayrshare-docs/Nmrhj2Gh7WSf62Bh/images/apis/messaging/messaging-badge.webp?fit=max\&auto=format\&n=Nmrhj2Gh7WSf62Bh\&q=85\&s=cee009857e195b2835e913eb36c3b83f)

### Enable Messaging for WhatsApp

> [!NOTE]
>
> **WhatsApp is in Private Beta.** The setup flow and Messaging API endpoints are available to
> approved beta accounts. To request access, email
> [lotty@ayrshare.com](mailto:lotty@ayrshare.com).

Link a WhatsApp Business account through Meta's **embedded signup** flow directly from the
Ayrshare dashboard:

<ul>
  <li>
    You need a **Meta Business Manager** account, a **WhatsApp Business Account (WABA)**, and an
    eligible phone number. Meta verifies the account and phone number during embedded signup.
  </li>

  <li>
    On the Social Accounts page, click **Link** on the WhatsApp tile. Ayrshare launches Meta's
    embedded signup pop-up which walks the customer through selecting/creating their Business
    Manager, WABA, and phone number, and accepting Meta's terms.
  </li>

  <li>
    When signup finishes, Ayrshare verifies ownership of the selected WABA and phone number,
    completes registration, and subscribes the account to WhatsApp webhooks. You do not enter a
    separate registration PIN in the Ayrshare dashboard.
  </li>
</ul>

### Important WhatsApp-Specific Behavior

<ul>
  <li>
    **Recipients are phone numbers, not IDs.** WhatsApp identifies correspondents by E.164
    phone number (digits only, no `+`). Conversation IDs returned from Ayrshare are also the
    correspondent's phone number — there are no opaque conversation IDs the way Facebook and
    Instagram use.
  </li>

  <li>
    **24-hour customer service window.** WhatsApp Business only allows free-form outbound
    messages within 24 hours of the most recent message from the correspondent. Outside that
    window Meta rejects the send. Templated messages outside the 24-hour window are not currently
    supported through Ayrshare.
  </li>

  <li>
    **Address a recipient directly with the API.** Pass the recipient's phone number to
    [Send Message](https://www.ayrshare.com/docs/apis/messages/send-message.md). Meta only delivers a free-form message when that
    recipient is inside the 24-hour customer service window. Approved templates are required for
    cold outreach, and Ayrshare does not currently expose template sending.
  </li>

  <li>
    **Delivery status uses one field.** When available on a stored outbound message,
    [Get Messages](https://www.ayrshare.com/docs/apis/messages/get-messages.md) returns `status` as `sent`, `delivered`, `read`, or
    `failed`. Delivery-status updates and WhatsApp reactions are not currently pushed to your
    registered webhook URL.
  </li>

  <li>
    **Media types and sizes** follow Meta's published WhatsApp Cloud API limits — images up to
    5 MB, audio and video up to 16 MB, and documents up to 100 MB at the time of writing.
  </li>

  <li>
    **Incoming messages are marked as read.** Ayrshare marks each incoming WhatsApp message as read as soon as it arrives, so the sender sees it as read right away.
  </li>

  <li>
    **Keep Messaging on for the receiving profile.** Incoming WhatsApp messages for a profile that does not have Messaging turned on are not stored or sent to your webhook. Turn it on from the Profiles page of the Ayrshare dashboard, or set `messagingActive` to `true` with [Update Profile](https://www.ayrshare.com/docs/apis/profiles/update-profile.md).
  </li>
</ul>

#### Supported WhatsApp Media

<ul>
  <li>**Image:** `.jpg`, `.jpeg`, `.png`</li>
  <li>**Video:** `.mp4`, `.3gp`</li>
  <li>**Audio:** `.aac`, `.amr`, `.mp3`, `.m4a`, `.ogg`</li>
  <li>**Document:** `.txt`, `.pdf`, `.ppt`, `.pptx`, `.doc`, `.docx`, `.xls`, `.xlsx`</li>
</ul>

### Enable Messaging in the Instagram App

You may need to enable messaging for your Instagram account:

<ul>
  <li>
    Go to your profile in the Instagram mobile app and tap the menu icon ≡ in the upper right corner
    to go to the **Settings and activity** page.
  </li>

  <li>Scroll down to the **How others can interact with you** section.</li>
  <li>Click **Messages and story replies**.</li>
  <li>Tap **Message requests**.</li>
  <li>Under **Connected tool** toggle on the **Allow access to messages** switch.</li>
</ul>

> [!TIP]
>
> The **Message requests** setting shown here also governs whether a *recipient* can be reached. If you use [comment-triggered automations](https://www.ayrshare.com/docs/apis/automations/overview.md) to DM people who comment on your posts, delivery depends on each recipient's Message requests setting — a message can be accepted by Instagram (`sent`) and then silently dropped. See [Automation DM Sent but Not Delivered](https://www.ayrshare.com/docs/help-center/technical-support/automation-dm-sent-but-not-delivered.md).

## Important Information on Messaging

> [!NOTE]
>
> **For Facebook and Instagram, a conversation must be initiated by the correspondent.** Once a
> conversation is established, you may then send messages, receive messages, get reactions (e.g.
> thumbs ups), or get read receipts on behalf of your users. WhatsApp follows the 24-hour customer
> service window described above.

> [!NOTE]
>
> **Your user must respond to an Instagram conversation within 7 days of the last message the
> correspondent sent.** If the correspondent has not sent a message in 7 days the conversation is
> considered inactive and cannot be responded to.

> [!NOTE]
>
> **Comment-triggered automations use a different 7-day window.** A [`comment_keyword` automation](https://www.ayrshare.com/docs/apis/automations/overview) replies to a *comment* via a private reply, whose 7-day window is anchored to the comment (not to a prior message), so no existing conversation is required. Delivery is still subject to the recipient's Message requests setting — see [Automation DM Sent but Not Delivered](https://www.ayrshare.com/docs/help-center/technical-support/automation-dm-sent-but-not-delivered.md).

### Message History Retrieval for Facebook and Instagram

When you first enable messaging for a user profile with a linked Facebook or
Instagram, there are important limitations on accessing conversation history:

#### Initial Connection Limitations

<ul>
  <li>
    Facebook and Instagram only allow retrieval of the **last 20 messages** from existing
    conversations when you first link an account for messaging
  </li>

  <li>
    If a conversation has more than 20 messages, only the most recent 20 will be accessible
    initially
  </li>
</ul>

#### After Initial Setup

<ul>
  <li>
    Once messaging is enabled, **all new messages** sent and received will be fully accessible
  </li>

  <li>Ayrshare maintains complete conversation history going forward</li>

  <li>
    For example: If you initially retrieve 20 messages, then 100 new messages are exchanged, you'll
    be able to access all 120 messages total
  </li>
</ul>

This limitation only applies to historical messages that existed before enabling
messaging - all future conversation activity for Facebook and Instagram will be
fully preserved and accessible.

### Conversation Limit & Pricing

<ul>
  <li>
    Each Ayrshare User Profile can have up to **1,000 active conversations per
    billing cycle**. The active conversation count is the sum across all social
    networks. Each User Profile has its own count, including messages sent
    through the API with that profile's `Profile-Key`.
  </li>

  <li>
    **Premium plan**: Messaging is a flat **\$49 per month** add-on per account.
  </li>

  <li>
    **Launch and Business plans**: Messaging is billed at **\$0.09 per active
    conversation** via Stripe metered billing. Volume-based discounts are
    available; contact your Ayrshare account representative for details.
  </li>

  <li>
    A conversation is counted as active for the billing cycle when you send a
    message to a recipient and the social network accepts it. Inbound messages
    from a recipient do not, on their own, mark a conversation as active.
  </li>

  <li>
    Messages Ayrshare sends for you automatically count the same as messages
    you send yourself. This includes [auto responses](https://www.ayrshare.com/docs/apis/messages/set-auto-response.md)
    and the `send_dm` action in [Automations](https://www.ayrshare.com/docs/apis/automations/overview.md).
  </li>

  <li>
    If the 1,000 conversation limit has been reached, you can still receive
    messages and keep replying in conversations that are already active this
    billing cycle, but you cannot message a new recipient until the start of
    the next billing cycle. This applies to auto responses and automation DMs
    too, with one exception: an automation DM triggered by a comment is still
    sent, and still counted (see [Automations](https://www.ayrshare.com/docs/apis/automations/overview.md#rate-limits-and-caps)).
  </li>

  <li>The number of messages, sent or received, in an active conversation is unlimited.</li>

  <li>
    If you need to increase the conversation limit, please contact your
    Ayrshare account representative.
  </li>
</ul>

You can see the current conversation count with the [user endpoint](https://www.ayrshare.com/docs/apis/user/overview.md).

### Messaging Control Issues on Facebook and Instagram

Meta (Facebook and Instagram) uses a "thread control" system for messaging conversations. This means only one app can send messages in a conversation at a time, while other apps can only receive messages.

#### What Does This Mean?

If you see the error **"Message failed to send because another app is controlling this thread now"**, it means:

* A different third-party app currently controls that conversation
* Ayrshare can only receive messages in that conversation
* Ayrshare cannot send messages until it regains control

#### How to Fix This Issue

To allow Ayrshare to send messages again, you need to remove the third-party app that's controlling the conversation.
Please note that Meta (Facebook and Instagram) may update the process for removing third-party apps, so use the following steps as a general guideline.

**For Facebook Pages:**

1. Go to [Facebook.com](https://facebook.com) and log into your account
2. Click the menu (☰) in the top right → **Settings & Privacy** → **Settings**
3. In the left sidebar, click **Apps and Websites**
4. Find the third-party app that's controlling your messaging
5. Click **Remove** next to that app
6. Confirm the removal

**For Instagram Business Accounts:**

1. Open the Instagram app on your phone
2. Go to your **Profile** → tap the menu (☰) → **Settings and Privacy**
3. Tap **Apps and Websites**
4. Find and remove the third-party app

**Alternative for Instagram:**

1. Go to [business.facebook.com](https://business.facebook.com)
2. Navigate to **Business Settings**
3. Under **Accounts**, click **Instagram Accounts**
4. Select your Instagram account
5. Check for connected apps and remove the problematic one

#### After Removal

Once you've removed the third-party app:

<ul>
  <li>Thread control will automatically return to Ayrshare</li>
  <li>You should be able to send messages normally again</li>
  <li>No further action is required on your part</li>
</ul>

If you continue to experience issues after removing the app, please contact our support team.

## Message WebHooks

See [Messages Webhooks](https://www.ayrshare.com/docs/apis/webhooks/actions.md#messages-action) to automatically receive messages, read receipts, or reactions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.