Skip to main content
When you open a linking page in a popup, your own page can listen for what happens in it: your user connected Reddit, they backed out, the connection failed. You get an event per outcome, so your UI updates the moment it happens rather than on a timer. Set 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 checks event.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 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 hears connect: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 get success 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.