origin when you create the link, open the
returned url in a popup, and listen. Nothing else is required, and nothing changes for
links created without origin — they behave exactly as they always have.
Using the embedded widget? This is already wired up for you.
The script receives these events and hands them to
connect.on("success", …) with the
connect: prefix stripped — no message listener, no origin check, no popup.closed poll to
write. This page is the wire protocol underneath, and what you build against when you own the
window: direct mode, or a popup you open yourself.Events are sent only to the exact
origin you set on the link, and only to the window
that opened the popup. Always check event.origin in your listener anyway: any page can
post a message to your window, and the origin is the only part of a message that cannot
be faked.The Events
Every message posted to your page is an object shaped{ source: "ayrshare", version: 1, event, ... }, and carries network whenever the event is
about one. Two events are not: a connect:closed from the hosted linking page, where it means your
user pressed Done rather than that one connection ended, and the widget’s connect:ready (see
below). The outcomes your own code synthesizes — a blocked popup, or a window your user closed — do
not come from us and carry only what you give them.
The embedded widget differs on one event. Its
ready announces
that a slot is up rather than anything about a network, so it carries no network — whereas the
popup’s ready names the network it was opened for. If you handle both surfaces from one
listener, read network defensively on ready.The widget also adds one cancelled reason this surface never sends: superseded, when a second
popup() call replaces an attempt still in flight. Here there is one window and one outcome, so
there is nothing to supersede.
Exactly one of
connect:success, connect:error or connect:cancelled arrives per
connection. connect:closed is not one of them — it follows, to tell you the popup closed
on purpose.
connect:success is sent only after the account has been saved, so a
GET /user immediately after it already shows the connected account.
The popup stays open after
connect:error so your user can read what went wrong. It
closes itself after connect:success and connect:cancelled. Add &autoClose=false to
the URL to keep it open in every case while you are debugging.Listening
Two things this snippet does that are easy to leave out. It checksevent.origin, and it
watches for a popup your user closed by hand — a closed window cannot send anything, so
polling is the only way to notice.
Errors
connect:error carries the same codes as the rest of the API, so a code you see here means
what it means everywhere else. The one specific to this surface:
Anything else is the social network’s own failure, reported with whatever code that
failure already has — for example
322 for an Instagram authorization problem, which
includes an account that is still Personal rather than Professional.
A dead link arrives differently
A link that is expired, revoked or unknown is refused before the page can learn where to send events, so it cannot send one. Your user sees the reason and its code on screen, and your page hearsconnect:cancelled when they close the window.
To tell those apart, poll Get a Link Session: it reports
expired and revoked authoritatively, and returns 502 for a link that does not exist.
If You Would Rather Not Manage a Popup
Two options, and only the second gives up events. Let the widget own the window. The embedded widget opens and watches it for you and delivers every event above to your handlers. You still getsuccess the
moment an account is saved; you just do not write the plumbing. Its frames also mean most networks
never open a popup at all until the network’s own login.
Poll instead. If a popup is genuinely not available — a server-rendered app, or a mobile app
opening the link in the system browser — poll
Get a Link Session. It reports completedAt and
completedNetworks as soon as an account is saved, which is the same moment connect:success
would have been sent. Telegram always finishes this way, since it completes out of band with no
browser callback at all.