Send and receive direct messages on Facebook, Instagram, and X/Twitter
The Messaging Add-On is required to access the messages endpoints. Only available for Business Plans.
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.
Enable Messaging for Your Account and User Profiles
You must first enable messaging for your overall Ayrshare account. In the Ayrshare dashboard go to the Account page and click to "Learn More" button and then "Enable". At this point you have enabled messaging for your overall account, but have not activate messaging for individual User Profiles.
You can activate messaging for individual User Profiles either in the User Profiles page by clicking "Messaging Active" for each profile or via the profiles endpoint (create or update).
Important Information on Messaging
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, read receipts, or reactions.
Facebook and Instagram mediaUrls must end in a know extension. Having query parameters will cause the media url to fail.
Headers
Name
Value
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key
string
Profile key of a user profile.
Path Parameters
Name
Value
platform*
string
The platform to send the message: facebook, instagram, twitter
Body
Name
Type
Description
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.
Facebook and Instagram support multiple media URLs. Twitter only accepts a single media URL.
Response
{ // single text message"status":"success","recipientId":"72706337063589124","messageId":"aWdfZAG1faXRlbToxOkl","message":"What is up?"}
{ // single text message"action":"messages","status":"error","code":363,"message":"The recipient ID was not found. Please confirm the recipient ID is correct."}
{ // single image"status":"success","recipientId":"761943","messageId":"m_EgvfBrgjaM","type":"image","mediaUrl":"https://img.ayrshare.com/012/gb.jpg"}
{ // 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."
} ]}
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
Name
Value
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key
string
Profile key of a user profile.
Path Parameters
Name
Value
platform*
string
The platform to send the message: facebook, instagram, twitter
Query
Name
Type
Description
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"}
{"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."
}
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
Name
Value
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key
string
Profile key of a user profile.
Path Parameters
Name
Value
platform*
string
The platform for status update: facebook, instagram, twitter
conversationId*
string
The ID of the conversation to archive.
Body
Name
Type
Description
status*
string
Values: active or archived.
Response
{"status":"success"}
{"action":"request","status":"error","code":101, "message": "Missing or incorrect parameters. Please verify with the docs. https://docs.ayrshare.com/rest-api/endpoints"
}
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
Name
Value
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key
string
Profile key of a user profile.
Body
Name
Type
Description
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.
{"action":"request","status":"error","code":101, "message": "Missing or incorrect parameters. Please verify with the docs. https://docs.ayrshare.com/rest-api/endpoints"
}