messages

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

Currently in select Beta. Please contact your Ayrshare account representative if you're interested in joining the Beta. The Messaging Add-On is required to access all messages endpoints.


The Messaging Add-On allow you to manage direct messages 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.

Messaging is available for Facebook Messenger, Instagram Direct Messenger, and X/Twitter Direct Messages.

A conversation must be initiated by the correspondent. Once a conversation is established, you may then freely send messages, receive messages, get reactions (e.g. thumbs ups), or get read receipts on behalf of your users.

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.

Monthly Conversation Limit

Each Ayrshare User Profile can have up to 100 active conversations each month. A conversation is considered active for the month if a customer has sent as a message. If 100 monthly conversations has been reached you can still receive messages, but will not be able to respond until the start of the month. If you need to increase the monthly conversation limit, please contact your Ayrshare account representative.

You may see the current converation count with the user endpoint.

Message WebHooks

See Messages Webhooks to automatically receive messages.

POST Message

POST https://app.ayrshare.com/api/messages/:platform

Send a new direct message to a recipient.

  • Send an emoji as part of the message text.

  • Facebook and Instagram mediaUrls must end in a know extension. Having query parameters will cause the media url to fail.

Headers

NameValue

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile key of a user profile.

Path Parameters

NameValue

platform*

string

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

Body

NameTypeDescription

recipientId*

string

The ID of the message recipient.

message

string

The message to send to the recipient.

mediaUrls

array

Array of media URLS. Used for images and videos. URLs of media items should end in the file extension without additional parameters appended.

Response

{ // single text message
    "status": "success",
    "recipientId": "72706337063589124",
    "messageId": "aWdfZAG1faXRlbToxOkl",
    "message": "What is up?"
}

Request Examples

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

GET Messages

GET https://app.ayrshare.com/api/messages/:platform

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 the messages. Please contact us to learn more about Enterprise Plans if you need real-time X/Twitter message access.

Headers

NameValue

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile key of a user profile.

Path Parameters

NameValue

platform*

string

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

Query

NameTypeDescription

status

string

Return active conversations or archived conversations. Values: active or archived. Default: active

conversationId

string

Only return the specific conversation.

conversationsOnly

boolean

Return all the conversations. Default: false If true then conversationId field ignored.

Response

{
    "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
            }
        },
        {
            "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"
}

Request Examples

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/messages/facebook

PUT Update Messages

PUT https://app.ayrshare.com/api/messages/:platform/:conversationId

Update the status of a conversation to active or archived. You may want to archive conversations if they are no longer active or relevant.

Headers

NameValue

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile key of a user profile.

Path Parameters

NameValue

platform*

string

The platform for status update: facebook, instagram, twitter

conversationId*

string

The ID of the conversation to archive.

Body

NameTypeDescription

status*

string

Values: active or archived.

Response

{
    "status": "success"
}

Request Examples

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status": "archived"' \
-X PUT https://app.ayrshare.com/api/messages/instagram/aWdfZMTpIyzQw

POST Set Auto Response

POST https://app.ayrshare.com/api/messages/autoresponse

Automatically send message auto responses to the correspondent. This is useful if your customer service support desk is not currently available.

If active, the auto response is used for all social networks for a given User Profile.

Headers

NameValue

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile key of a user profile.

Path Parameters

NameValue

platform*

string

The platform for status update: facebook, instagram, twitter

conversationId*

string

The ID of the conversation to archive.

Body

NameTypeDescription

autoResponseActive

boolean

Default value: false

autoResponseWaitSeconds

number

The number of seconds to wait before sending the auto response again to the correspondent. Default: 86,400 seconds (24 hours).

autoResponseMessage

string

The auto response message. Default: "Thank you for contacting us. A customer care agent will get back to you soon.". Send and empty "" string to reset the message to the default.

Response

{
    "status": "success",
    "updated": {
        "autoResponseActive": true,
        "autoResponseMessage": "Howdy!",
        "autoResponseWaitSeconds": 30
    }
}

Request Examples

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"autoResponseActive": true, "autoResponseWaitSeconds": 30, "autoResponseMessage": "Howdy!"' \
-X POST https://app.ayrshare.com/api/messages/autoresponse