docs
/
AI skills

Social posts and the social inbox

The business's social accounts connected by the owner, posts drafted per platform with their picture, sent or scheduled by a person, and the DMs and comments that come back answered from Social Media › Conversations, with the AI paused when a person takes over.

A social post is a message record whose deliveryType is the platform (facebook, instagram, twitter, linkedin, tiktok, pinterest, youtube, gbp). It goes out through the same send pipeline as an email or a text. One message per platform. The accounts it goes to are in data.to.

What comes back (DMs, comments, reactions) is saved as social_activity records and shown as threads in Social Media › Conversations.

Everything posted is public, and every reply reaches a real person. The AI drafts; a person sends.

For the picture, see Social post graphic. For Facebook lead ads, see Inbound lead channels.

What works where

PlatformPostDMs inComments inReply from Appmint
Facebook pagetext, pictureslive, once set up (step 1)liveDMs and comments
Instagram business accountcaption with a picture or videolive, once set upliveDMs and comments
Xtext, one pictureneeds DM access the connection doesn't ask forreplies (not always delivered)replies; DMs as above
TikToka video with captionnoneyescomment replies only
LinkedIn company pagetext, picturesnonebrought in, AI not toldno
Pinteresta pin: picture and titlenonebrought in, AI not toldno
YouTubea video with titlenonenoneno
Google Business Profiletext updatenonenoneno

Messages are also fetched every 5 minutes, and posts, comments, reactions and followers every 30 minutes, from each connected account (Social messages sync, Social posts and comments sync).

Ask first

  • Which platforms and accounts? The page, profile or channel, by name.
  • Are they connected? If not, the person connects them (step 1). The AI can't.
  • What to say, per platform, and the picture or video for each. Never invent offers, prices or dates.
  • When? Now, at a set time, or repeating.
  • For the inbox: who answers (people, an AI assistant, or both), and what the AI may and may not say.

Steps

1. Social Media: the accounts (the person does this)

Connecting is a sign-in to each platform that the owner does in their own browser, granting Appmint access to their page or account. The AI never asks for a password or token. Open Social Media › Accounts (/social-manager?tab=accounts) and ask the person to connect each one there. After the sign-in, the platform sends them back to Studio with oauth=success.

Which accounts are connected is shown by call_appengine GET /sync/social-activities/platforms.

For Facebook and Instagram DMs and comments to arrive the moment they are sent, the page must also be subscribed: the Receiving DMs & comments panel shows each page's state. If it isn't set up, the person presses Set up (it becomes Re-subscribe when everything is connected). Other platforms rely on the timed syncs.

Hands on: the platforms and accounts that are connected. Check: the Accounts tab shows each as connected.

Google Business Profile and YouTube don't finish connecting yet. The sign-in for Google Business returns to an address the engine doesn't handle, and the YouTube sign-in is saved where YouTube posting doesn't read it. Don't plan posts for either; tell the person.

2. Creative Studio: the picture (if needed)

Instagram, TikTok, Pinterest and YouTube posts need media: a picture for Instagram and Pinterest, a video for TikTok and YouTube. Make or find it with Social post graphic and take its hosted url (from Files, not a link from someone else's website).

Hands on: the media url for each post.

3. Social Media: the drafts

One draft per platform: marketing_draft_social_post { platform, text, imageUrl?, campaignId? }. Platforms: facebook, instagram, linkedin, twitter, tiktok, pinterest. It saves a message with status: "draft", the picture in files, a subject from the first 80 characters, and no account chosen (to: []). A draft is never sent. A missing platform or text is refused (Platform must be one of: …, The post needs text).

Write each platform's text to fit it. The composer counts against these limits; the send doesn't check them, the platform does:

PlatformText limitNeeds
Facebook63,206text
Instagram2,200text and a picture or video
X280text
LinkedIn3,000text
TikTok2,200a video
Pinterest500a picture and a title (subject)
YouTube5,000 (description)a video and a title
Google Business1,500text

Plain text only. Hashtags at the end. No links shortened through a public shortener.

Hands on: each draft's sk. Check: each draft is in Social Media › Posts (/social-manager?tab=posts), under draft, with its platform and picture.

Stop: send or schedule

Posting is public. Show the person each post's platform, account, text and picture, and when it goes. Then the person opens the draft (Posts › Open), picks the account under Post to account (one or more), and presses:

  • Send to post now; or
  • turns on Schedule for later, sets Run at (or a Repeat), and presses Schedule.

Create Post in the Social Media header opens the same composer for a new one.

If they say "post it" in chat, repeat the platform, account, words and time, and act only after a clear yes. Sending is call_appengine POST /crm/inbox/update?send=true with the message, its deliveryType, text, files and to set to the account values the composer offers. A schedule is a schedule record owned by the message. At its time it sets the message pending, and the send runs.

4. Social Media: did it go?

Read the message back (get_record on message):

data.statusMeaning
draftnot sent
scheduledwaiting for its time
pendingbeing sent; a failure that can be retried is tried again, up to 3 times
sentposted. data.reference holds the platform's post id (on X tweet:<id>)
failednot posted; data.statusHistory says why

Common reasons, as saved:

ReasonFix
Pinterest requires an image. notification not sentadd a picture
YouTube requires a video file. notification not sentadd a video
Tiktok text and video not defined. notification not sentadd a video and a caption
Twitter text, subject not defined. notification not sentadd the text
No recipients provided. Message cannot be sent.pick an account under Post to account
message not sent after 3 triesread the earlier entries in statusHistory; often an expired connection (step 1)

Check: Posts shows it under sent with a link to the live post. Open the link.

5. Conversations: DMs and comments

Social Media › Conversations (/social-manager?tab=conversations) shows DMs and comments as threads, one per platform, account and customer, and per post for comments. Behind it:

  • GET /sync/social-activities/conversations?account=<id>&page=0&pageSize=30: the threads.
  • GET /sync/social-activities/conversation-thread?platform=<p>&customer=<id>&postId=<id>: one thread, oldest first, with reactions attached.

Each item is a social_activity with platform, sourceType (e.g. facebook-message, instagram-comment), content, authorName, authorUsername, accountId, direction (inbound / outbound), postId and parentId. The Refresh control pulls fresh DMs and comments now.

Hands on: the activity's sk for the message being answered.

Stop: reply

A comment reply is public, under the business's post. A DM reaches the person at once. Show the reply and where it goes, then wait for yes. Then call_appengine POST /sync/social-activities/reply with:

{ "activityId": "<social_activity sk>", "message": "Thanks Ada — we're open till 9 tonight." }

Given activityId, the server works out the platform, the page and whether it is a DM or a comment. It is saved as an outbound item by the person signed in. It answers { success, sentFrom, error }:

errorMeaning
Replying on linkedin is not supported yet (and the same for other platforms)answer on the platform itself
No connected Facebook/Instagram page to reply fromthe page isn't connected (step 1)
TikTok replies are comment-only and need a comment idTikTok has no DMs here
Twitter rejected the direct message (403)…the X connection can't send DMs

6. The AI on social (optional)

An AI assistant or AI employee can answer DMs and comments on Facebook, Instagram, X and TikTok. Set it up with AI assistant for the website chat or a phone line (a trigger on message.received) or Give an AI employee a standing job. It answers with reply_to_conversation on the customer's own channel.

When a person takes over a thread, pause the AI on it: call_appengine POST /sync/social-activities/ai-hold with { platform, customerId, hold: true, reason }. GET /sync/social-activities/ai-hold?platform=…&customerId=… reads it. The pause stays until someone sets hold: false. It doesn't lift by itself.

When it's done

Tell the person:

  • which accounts are connected, and which bring in DMs and comments live;
  • each draft, its platform and account, and that it is waiting in Posts;
  • what was sent or scheduled, and the link to each live post;
  • the replies sent, and any thread where the AI is paused;
  • what's waiting for them: connecting an account, Set up, pressing Send or Schedule.

What it can't do yet

  • No assigning or closing social threads. Conversations can be read and answered, not assigned to a person or marked done.
  • LinkedIn, Pinterest, YouTube, Google Business, Threads and Mastodon replies aren't possible from Appmint. LinkedIn and Pinterest comments are brought in, but the AI isn't told about them.
  • X DMs aren't read or sent with the permissions the X connection asks for. X posts carry one picture.
  • Deleting a post from the platform: Instagram can't be deleted from Appmint, and TikTok's delete does nothing.
  • Google Business Profile and YouTube can't be connected yet (step 1).
  • The 24-hour rule for Facebook and Instagram DMs isn't checked before a reply. A reply to someone who last wrote days ago is refused by the platform.

Don'ts

  • Don't connect accounts, paste tokens or change a connection. The person does it.
  • Don't send, schedule or reply without a yes, and don't turn a draft's status into pending yourself.
  • Don't create social_post records. Nothing publishes them. A post is a message.
  • Don't post the same text to every platform. Fit each one.
  • Don't use pictures from websites the business doesn't own.
  • Don't promise a post or reply on a platform the table above says doesn't work.