Messenger and Instagram DMs
Hermoso reads and answers the direct messages people send your Facebook Page and your Instagram account, in the app's inbox and through list_inbox, read_meta_conversation and reply_to_meta_message. A reply can carry photos, link buttons, a carousel of cards and quick replies. You can also set what people see before they write, hand a conversation to another chat app, label people in the Page inbox, and answer Page reviews and Instagram @mentions.
Replying
Meta lets a business answer a person for 24 hours after that person last wrote. Pass conversationId with a reply and Hermoso checks the window before anything is sent; a closed window is refused for free with the reason. Only the person writing again reopens it. Hermoso sends replies only: never a first message to someone who has not written.
| Part of a reply | Meta's limit |
|---|---|
| Text | 2,000 characters on Messenger; 1,000 bytes on Instagram (an emoji or accented letter counts as more than one) |
buttons | Up to 3 under the text, each a link or a reply tap, titles up to 20 characters. With buttons the text is at most 640 characters. |
cards | Up to 10 in a carousel; title and subtitle up to 80 characters; up to 3 buttons each |
quickReplies | Up to 13 chips, titles up to 20 characters. They disappear after the next message. |
attachments | Photos, a video, a voice note or a PDF, by https link. On Instagram: images PNG or JPEG up to 8 MB, video and audio up to 25 MB, PDF up to 25 MB. |
senderAction | A typing indicator (on or off) or a seen receipt, shown to the person |
Anything over a limit is refused with the limit. Nothing is cut. A file on your computer goes through upload_file first, which gives you a link.
Meta takes one message per request, so a reply with text, two photos and a carousel goes out as three messages, in that order, with quick replies on the last. If Meta refuses one part, the answer says which parts went out and which did not, and the parts that went out are never sent again.
reply_to_meta_message {
"recipientId": "<replyTo from read_meta_conversation>",
"conversationId": "t_...",
"text": "Yes, we ship to Canada.",
"buttons": [{ "type": "url", "title": "Shipping", "url": "https://example.com/shipping" }],
"quickReplies": ["Order now", "Ask a question"]
}
In the app, open Automations, then Inbox. Messenger and Instagram conversations sit beside WhatsApp and LINE, and the reply box has Add photos, buttons or quick replies.
Handing a conversation to another app
If the brand runs another chat app on its Page (a chatbot, a help desk, Meta's own inbox), meta_thread_control says and changes which app answers a conversation. Meta calls this Conversation Routing.
- owner: which app holds the conversation now. Meta only names the holder to the holder itself or to the Page's default app.
- status: whether the Page routes conversations between several apps.
- pass to another app's numeric Meta app id, or to
"Page inbox"or"Instagram inbox"; take it for Hermoso; release it back to the Page's default app; request it from the app that holds it; extend Hermoso's hold for up to 7 days.
Every change is shown to you first and runs only with "confirm": true. Meta refuses take unless the Page has a default app set (Page settings, Advanced messaging, Conversation routing). This works through a Facebook Page; an Instagram account connected on its own has no routing to change. Secondary receivers were part of Meta's older Handover Protocol, which Meta has retired, so they are not offered.
Welcome screen, ice breakers and menu
meta_messenger_profile reads and changes what every person sees before they write:
| Setting | Messenger | |
|---|---|---|
| Get Started button | Yes | No |
| Greeting (up to 160 characters, one per language) | Yes | No |
| Ice breakers (up to 4 questions) | Yes | Yes |
| Persistent menu (up to 20 items, titles up to 30 characters) | Yes, shown only when the Get Started button is on | Yes |
A change is shown as before and after and runs only with "confirm": true. The answer is read back from Meta, and anything Meta did not keep is named. Meta allows 10 changes per 10 minutes for each Page, and a changed menu can take up to a day to show in conversations that are already open. In the app, the Messenger & Instagram section of the inbox has Messenger welcome and Instagram ice breakers.
Labels
meta_conversation_labels manages the Page inbox's labels (VIP, Wholesale, Call back): list them, create one, put one on a person or take it off, and delete one. Labels show in the Page inbox and Meta Business Suite and are never shown to the person. Deleting a label removes it from everyone and needs "confirm": true. Labels are for Messenger conversations only.
Page reviews and Instagram mentions
meta_page_reviews lists the reviews on the brand's Facebook Page: whether the person recommends it, any stars, the words, who wrote it and when. instagram_mentions lists posts and comments by other accounts that @mention the brand's Instagram account. Both also appear in list_inbox beside every other channel, and reply_to_inbox_item answers them.
- A reply is public and runs only with
"confirm": true. It is read back from Meta before it is called posted. - Review replies: Meta documents reading reviews but not replying to them through its API. Hermoso tries, and when Meta refuses, the answer says to reply from the Page on Facebook.
- Mentions are reported as they happen. Meta keeps no list to read back, so Hermoso lists the mentions Meta has told it about recently. A mention in a Story arrives as a direct message instead, a private account sends nothing, and an account connected only directly through Instagram gets its mentions inside comment notifications. When the same account is connected both directly and through a Facebook Page, mentions are read and answered through the Page, and the answer says so.
The tools
| Tool | What it does |
|---|---|
reply_to_meta_message | Reply with text, photos, buttons, cards, quick replies, or a typing / seen indicator |
meta_thread_control | See and change which app answers a conversation |
meta_messenger_profile | The welcome screen, ice breakers and menu |
meta_conversation_labels | Labels on people in the Page inbox |
meta_page_reviews | Read and answer Facebook Page reviews |
instagram_mentions | Read and answer Instagram @mentions |
list_inbox, reply_to_inbox_item | All of it in the one inbox, with every other channel |
All of them are free. An agent finds the ones not in its starting list with find_tools and runs them with call_tool.