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

# Send Message

> Send a direct message on Facebook, Instagram, X/Twitter, or WhatsApp with text or mediaUrls; reactions are WhatsApp only. Active conversation pricing applies.

> [!NOTE]
>
> **Targeting X/Twitter?** Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
>
> `X-Twitter-OAuth1-Api-Key` — Your API Key (Consumer Key)
>
> `X-Twitter-OAuth1-Api-Secret` — Your API Key Secret (Consumer Secret)
>
> **One-time setup per Ayrshare account.** You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do *not* create a new app per customer.
>
> Not linked yet? See the [full setup guide](https://www.ayrshare.com/docs/dashboard/connect-social-accounts/x-twitter-byo-keys.md) to connect your X account.
>
> Your keys are never logged or stored by Ayrshare.

Send a new direct message to a recipient.

> [!NOTE]
>
> **Pricing & Limits:** Each User Profile can have up to **1,000 active
> conversations per billing cycle** across all social networks. Pricing depends
> on your plan: **Premium** plans pay a flat **\$49 per month** add-on, while
> **Launch** and **Business** plans are billed at **\$0.09 per active
> conversation**. A conversation is counted as
> active when you send a message to a recipient during the billing cycle;
> inbound messages alone do not count. The number of messages within an active
> conversation is unlimited.

<ul>
  <li>You can send an emoji as part of the `message` text.</li>

  <li>
    Facebook and Instagram `mediaUrls` must end in a known extension. Including query parameters
    will cause the media URL to fail.
  </li>
</ul>

> [!NOTE]
>
> **WhatsApp 24-hour customer service window.** WhatsApp Business only permits free-form
> outbound messages within **24 hours** of the most recent message from the correspondent. After
> that window, message sends will be rejected by Meta until the correspondent messages again.
> Templated messages outside the 24-hour window are not currently supported through this endpoint.

## Header Parameters

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

## Path Parameters

**platform** `string` *required*

The platform to send the message: `facebook`, `instagram`, `twitter`, `whatsapp`

## Body Parameters

**recipientId** `string`

The ID of the message recipient. Required for Facebook, Instagram, and WhatsApp. For X/Twitter,
send `recipientId` or `conversationId`.

<ul>
  <li>
    For **Facebook**, **Instagram**, and **X/Twitter** this is the platform-specific user ID
    (PSID, IGSID, or user ID).
  </li>

  <li>
    For **WhatsApp** this is the recipient's phone number in E.164 digits-only format (for
    example `14155551234`, not `+1 (415) 555-1234`).
  </li>
</ul>

**message** `string`

The message to send to the recipient. Required unless `mediaUrls` or `reaction` is sent. Must be
left out when sending a `reaction`.

<ul>
  <li>
    Facebook, Instagram, and WhatsApp `message` may be an empty string or omitted entirely when
    `mediaUrls` is provided.
  </li>

  <li>
    X requires a message of at least one character even if a `mediaUrls` is provided.
  </li>
</ul>

**mediaUrls** `array`

Array of media URLs for attaching images, video, audio (including voice messages), or documents.

<ul>
  <li>
    URLs of media items should end in the file extension without additional parameters appended.
  </li>

  <li>Facebook and Instagram support multiple media URLs.</li>
  <li>X only accepts a single media URL.</li>
  <li>Voice messages are supported on Facebook and Instagram as an `aac` or `wav` file.</li>

  <li>
    **WhatsApp** accepts multiple media URLs. Ayrshare fetches each URL and uses its response
    `Content-Type` to select the WhatsApp media category. Meta accepts:

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

**conversationId** `string`

X/Twitter only. Send the message into an existing conversation instead of to a `recipientId`.
Get the ID from [Get Messages](https://www.ayrshare.com/docs/apis/messages/get-messages.md).

**reaction** `object`

WhatsApp only. React to a message instead of sending one. Do not send `message` or `mediaUrls`
with a reaction.

<ul>
  <li>`messageId`: Required. The ID of the WhatsApp message to react to.</li>
  <li>`emoji`: Required. A single emoji. Send an empty string `""` to remove your reaction.</li>
</ul>

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"message": "What's up!", "recipientId": "283j839222"} \
-X POST https://api.ayrshare.com/api/messages/instagram
```

```javascript JavaScript theme={"system"}
const apiKey = 'API_KEY';
const url = 'https://api.ayrshare.com/api/messages/instagram';

const data = {
  message: "What's up!",
  recipientId: '283j839222',
};

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json',
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data),
})
  .then(response => response.json())
  .then(data => {
    console.log('Response:', data);
  })
  .catch(error => {
    console.error('Error:', error);
  });
```

```python Python theme={"system"}
import requests

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

data = {
    'message': "What's up!",
    'recipientId': '283j839222',
}

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json',
}

response = requests.post(url, json=data, headers=headers)
print('Response:', response.json())
```

```php PHP theme={"system"}
<?php

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

$data = [
    'message' => "What's up!",
    'recipientId' => '283j839222',
];

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
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 {
    $responseData = json_decode($response, true);
    print_r($responseData);
}

curl_close($ch);

?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

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

        var data = new
        {
            message = "What's up!",
            recipientId = "283j839222"
        };

        var jsonData = JsonSerializer.Serialize(data);

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

        var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

        try
        {
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();

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

            Console.WriteLine("Response:");
            Console.WriteLine(responseData);
        }
        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/instagram";

        String data = "{\"message\": \"What's up!\", \"recipientId\": \"283j839222\"}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(data))
                .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());
        }
    }
}
```

```json 200: Success theme={"system"}
{ // single text message
    "status": "success",
    "recipientId": "72706337063589124",
    "messageId": "aWdfZAG1faXRlbToxOkl",
    "message": "What is up?"
}
```

```json 400: Error theme={"system"}
{
  // single text message
  "action": "messages",
  "status": "error",
  "code": 363,
  "message": "The recipient ID was not found. Please confirm the recipient ID is correct."
}
```

```json 200: Media Urls theme={"system"}
{
  // single image
  "status": "success",
  "recipientId": "761943",
  "messageId": "m_EgvfBrgjaM",
  "type": "image",
  "mediaUrl": "https://img.ayrshare.com/012/gb.jpg"
}
```

```json 400: Media Urls theme={"system"}
{
  // text and image message
  "action": "send",
  "status": "error",
  "code": 337,
  "message": "Error sending message.",
  "messages": [
    {
      "recipientId": "727063370635",
      "messageId": "aWdfZAG1faXRlbT",
      "message": "What a great day"
    },
    {
      "action": "messages",
      "status": "error",
      "code": 365,
      "message": "An error occurred sending the message attachment. Please verify the attachment is still available and try again."
    }
  ]
}
```

```json 200: WhatsApp Text theme={"system"}
{
  "status": "success",
  "messagingProduct": "whatsapp",
  "contacts": [
    {
      "input": "14155551234",
      "waId": "14155551234"
    }
  ],
  "recipientId": "14155551234",
  "messageId": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBI4OUYxRkExNzE0M0EwQTYwM0EA",
  "message": "Thanks — your order has shipped."
}
```

```json 200: WhatsApp Text + Media theme={"system"}
{
  "status": "success",
  "messages": [
    {
      "messagingProduct": "whatsapp",
      "recipientId": "14155551234",
      "messageId": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBI3MEM3Q0NDQjlGRTUzMjJBNEUA",
      "message": "Here's the shipping label you requested."
    },
    {
      "messagingProduct": "whatsapp",
      "recipientId": "14155551234",
      "messageId": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBJDODc3NEJBRTdGN0NGNkVCMEMA",
      "type": "document",
      "mediaUrl": "https://example.com/label.pdf"
    }
  ]
}
```


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