Channels

Conversations happen on Telegram, Instagram (Direct) and Facebook (Messenger). All three share one inbox, one AI Seller and one case analysis; what differs is how an account is connected and the platform rules a reply must obey. Instagram and Facebook add Meta's messaging windows, and those windows decide what the AI may send.

What each channel is#

Channel	Direct messages	Content and comments	Connecting
Telegram	Yes	Via your own Telegram accounts — see Telegram accounts.	An account signs in inside Oqim.
Instagram	Yes	Yes: posts, reels, comments and metrics	Instagram Login, no Facebook Page needed.
Facebook	Yes, on a Page	Yes: posts, comments and metrics	Facebook Login for Business; every Page you grant is connected.
YouTube	No: it has no direct messages	Yes: videos, comments, statistics	A channel link or @handle; the owner signs in for private analytics.

A conversation carries its channel (TELEGRAM, INSTAGRAM or FACEBOOK), so the inbox can filter by it and every insight board has a view per channel plus one for all channels. Social content is analysed separately, under Business insights.

Connect Instagram#

Instagram connects with Instagram Login, which needs no Facebook Page — the usual case for a business that only has an Instagram account.

In the console, Channels → Instagram → Connect, or POST /channels/instagram/connect. The answer holds the authorize URL; the request is signed state, valid for ten minutes and single-use.
You sign in at Instagram and grant the messaging permissions. Oqim exchanges the code for a long-lived token (60 days), reads the profile, and creates the account with the capabilities the granted permissions allow.
The account is subscribed to Meta's webhooks (messages, postbacks, reactions, seen, comments, mentions) and its history import starts by itself.
The browser returns to the console with ?connected=, or with ?error= and one of denied, state_invalid, already_connected_elsewhere, missing_permissions or provider_error.

Connect Facebook Pages#

Facebook connects with Facebook Login for Business. You grant the Pages you want, and every Page in the grant is connected with its own Page token and its own webhooks (messages, postbacks, feed) — the console reports them as ?connected=<id,id>.

Account status, capabilities and tokens#

Status	Meaning
`CONNECTED`	Ready, with tokens Oqim can use.
`PUBLIC`	Read-only public data at work: a YouTube channel without its owner's sign-in.
`AUTH_REQUIRED`	The token stopped working, or the owner revoked access. The console asks the owner to reconnect.
`ERROR`	The last operation failed for another reason; the account page shows why.
`DISCONNECTED`	Removed. Webhooks are unsubscribed and tokens dropped; conversations and history stay.

Capabilities come from the permissions actually granted: MESSAGING (read and answer direct messages), COMMENTS (read comments, reply, send private replies), CONTENT (read posts and videos) and INSIGHTS (reach, views and audience metrics). Turning the AI on for an account needs the messaging capability and a business assigned to it.

Instagram tokens are refreshed before they expire by a daily task. A token Meta rejects as invalid sets the account to AUTH_REQUIRED with a reason. A YouTube owner's refresh token being refused does the same, and a public channel keeps syncing with the platform key meanwhile.

Meta's messaging windows#

Meta decides when a business may write to a person, and Oqim enforces it in the reply gate — before a message is queued, not after it fails.

Window	Who may send	Length
Standard window	Anyone, including the AI	24 hours after the person's last message
Human agent window	A person, with the `HUMAN_AGENT` tag — never the AI	7 days after the person's last message
Private reply to a comment	One direct message per comment, on your own post or reel	7 days after the comment

The AI replies only inside 24 hours. Outside that window it does not write, whatever its autonomy level.
The human agent window needs the Human Agent permission, approved in App Review; the platform setting META_HUMAN_AGENT says whether the app has it. Where it does, a reply sent between 24 hours and 7 days carries the tag so Meta accepts it.
Your business's reply window setting can shorten the 24 hours, never lengthen it. The gate uses the earlier of the two.
Follow-ups after a private reply are allowed only once the person answers — and then the 24-hour window applies as usual.
A private reply goes over the wire with the comment it answers, so it can never be repeated for the same comment.

What the gate records

Each conversation on Instagram or Facebook carries the window's end (the person's last message plus 24 hours), the human window's end where the app has the permission, and the basis a message may be sent on: REPLY_WINDOW for anyone inside 24 hours, HUMAN_AGENT for a person between 24 hours and 7 days.

Refusal	What it means
`window_closed`	The 24-hour window passed and the sender is not a person inside the human window. The message is not sent.
`account_auth_required`	The account's token is no longer valid; the account moves to AUTH_REQUIRED.
`recipient_unavailable`	The person blocked the account or cannot receive messages.
rate limits	Retried with backoff. Sends are capped per second and per hour, by Meta and by Oqim.

What cannot be done#

No cold outreach, ever. Nothing is sent to people who never wrote to the account. A campaign on Instagram or Facebook reaches only the people whose window is open; the rest are skipped with a reason, and the audience preview says who can be reached now and why.
No marketing messages. Messenger's marketing messages exist in Meta's documentation but are a paid ad-account API, which Oqim does not drive — launching such a campaign is refused with a clear error. Instagram has no marketing messages at all. Oqim does record a Page's opt-ins and show the topics and their subscribers.
History is limited. Meta's Conversations API returns only the last 20 messages of a thread, so older history cannot be fetched; the console says so plainly. Every new message is stored in full from the moment the account is connected.
Groups and channels are not covered. Oqim handles private chats only.
Text limits and rate limits differ per channel. Oqim uses the channel's own limit for a reply and shows it to the console, rather than assuming one number everywhere.
Meta's terms win. What Oqim may do on Instagram and Facebook is bounded by Meta's platform rules and by the permissions and reviews your app actually has.

Comment-to-DM automation#

When a comment on one of the account's posts or reels matches an automation, the Seller sends one private reply to that commenter, within Meta's 7-day window. A comment matches when it contains one of the automation's keywords, or when JEV judges it a buying or pricing question above the automation's confidence threshold. Automation rules are per account: which posts (all or selected), the keywords, the threshold, and either a message template per language or the Seller's own reply.

One private reply per comment, ever. Webhook replays and periodic syncs never produce a duplicate.
Every reply is logged per comment, audited, and rate-limited twice: by the automation's own hourly cap (100 by default, at most 750) and by Meta's 750 an hour per account.
Public replies to comments are optional and are human-approved drafts by default.

App review, before you can connect#

Until Meta grants advanced access — which needs business verification and App Review for the messaging, comment and insights permissions — only people with a role on your Meta app can connect an account. The console says so when the provider reports review_pending, and connecting is refused rather than half-working. The Human Agent permission is a separate review.

Meta callbacks#

Meta requires two callbacks, both signed. On a deauthorize or a data deletion request Oqim drops that account's tokens and marks it disconnected; for a data deletion it also deletes that person's messages and profile data, and answers with a confirmation code and a status URL.

Where to manage this#

Channels in the console lists every account by platform with its status, capabilities, the business it answers for, whether the AI answers DMs there, open conversations and the last sync.
The account page shows the status and its reason, lets you reconnect, check or disconnect, explains in plain words what the 24-hour rule means for AI replies, and holds the history and content imports.
Live changes arrive as channels.account.updated, channels.history.imported, channels.private_reply.sent, channels.private_reply.failed, channels.marketing_subscription.updated, ai.social.synced and ai.social.narrative_ready — see Webhooks.

Endpoints#

All under /api/v1. Viewing takes accounts:read; connecting, changing or disconnecting takes accounts:manage. Callbacks and webhooks are public but verified. See the API reference for bodies and responses.

Endpoint	Permission	What it does
GET/channels/providers	`accounts:read`	Which platforms this Oqim platform can connect: configured (the platform owner set up the Meta app; otherwise connecting is 409 provider_not_configured), review_pending (only accounts with a role on the Meta app can connect yet), human_agent (people may answer up to 7 days after a customer's last message) and history_messages_per_thread (history imports read only this many of a thread's most recent messages: Meta's limit).
POST/channels/instagram/connect	`accounts:manage`	The Instagram Login URL to send the person to.
GET/channels/instagram/callback	`Public`	Where Instagram returns the browser (public; the state is verified and used once, and the browser must carry the console session of the person who started the flow, so nobody can be tricked into connecting their account to another organization).
POST/channels/facebook/connect	`accounts:manage`	The Facebook Login for Business URL (with the platform's login configuration when it has one, else the pages_* permissions).
GET/channels/facebook/callback	`Public`	Where Facebook returns the browser (public; state-verified and bound to the starter's console session, as for Instagram).
GET/channels/accounts	`accounts:read`	Connected accounts (Instagram, Facebook and YouTube), oldest first.
GET/channels/accounts/{id}	`accounts:read`	One connected account, with its stats.
PATCH/channels/accounts/{id}	`accounts:manage`	The business the account serves (business_id; null clears it), whether its AI Seller answers the account's direct messages (ai_enabled: needs a business and the MESSAGING capability, otherwise a 422 on ai_enabled) and settings (an object).
DELETE/channels/accounts/{id}	`accounts:manage`	Disconnect the account: its webhook subscription is removed (best effort), its tokens deleted and its status DISCONNECTED.
POST/channels/accounts/{id}/check	`accounts:manage`	Check the account with Meta now: its profile is read again and its webhook subscription renewed.
POST/channels/accounts/{id}/history/import	`accounts:manage`	Import the account's past direct messages from Meta's Conversations API: threads active since since (a date, at most 365 days back; 90 days by default), and of each only the 20 most recent messages (Meta's limit), paced at 2 calls a second.
GET/channels/accounts/{id}/history	`accounts:read`	The account's latest history import: status IDLE (never ran), RUNNING, DONE, FAILED or CANCELLED, with its counts.
POST/channels/accounts/{id}/history/cancel	`accounts:manage`	Stop a running import; what it stored stays.
GET/channels/automations	`accounts:read`	List comment-to-DM automations.
POST/channels/automations	`accounts:manage`	Create a comment-to-DM automation on one Instagram account or Facebook Page.
GET/channels/automations/{id}	`accounts:read`	One automation, with sent_last_hour: what went out in the last hour, against the cap.
PATCH/channels/automations/{id}	`accounts:manage`	Change the fields the body carries; the same rules as on create apply.
DELETE/channels/automations/{id}	`accounts:manage`	Delete the automation.
GET/channels/accounts/{id}/private-replies	`accounts:read`	The private-reply log of an account: every comment an automation considered and what it did.
GET/channels/accounts/{id}/marketing-topics	`accounts:read`	A Facebook Page's marketing-message topics: who opted in, who is eligible right now (outside Meta's frequency limits), who stopped or whose token expired.
GET/channels/accounts/{id}/marketing-subscriptions	`accounts:read`	The people who opted in to a Page's marketing messages.
GET/channels/meta/webhook	`Public`	Meta's subscription handshake: with hub.mode subscribe and the platform's hub.verify_token, the answer is hub.challenge as plain text; otherwise 403.
POST/channels/meta/webhook	`Public`	Meta's notifications for Instagram (object instagram) and Pages (object page), signed with X-Hub-Signature-256 (401 signature_missing, signature_invalid).
POST/channels/meta/deauthorize	`Public`	Meta's deauthorize callback (form field signed_request, signed with the Meta or Instagram app's secret; 400 invalid_signed_request otherwise): every account the person connected loses its tokens and becomes DISCONNECTED, in every organization.
POST/channels/meta/data-deletion	`Public`	Meta's data-deletion callback (signed_request as above): the person's accounts lose their tokens and profile and become DISCONNECTED, and their conversations and messages are deleted.
GET/channels/meta/data-deletion/{code}	`Public`	The status of a data-deletion request (RECEIVED or COMPLETED).