# Connect Links

## Prerequisites

In order to use Connect Links, you will need:

- A project with Connect enabled (reach out to [support@gigs.com][gigs-support] or your Gigs point of contact for assistance)

## What Connect Links are

Connect Links are permanent, reusable URLs that launch Connect in a pre-configured state for a specific [intent][about-connect-sessions] — for example, purchasing a new subscription or viewing eSIM installation instructions. Unlike a [Connect Session][about-connect-sessions], a Connect Link is not tied to a single user and is not created through an API call per user. It can be configured once in the Dashboard, and the resulting URL can be shared with as many users as you like.

This makes Connect Links well suited to cases where you want to send users into Connect without your backend generating a session for each one — such as a link in an email campaign, a support macro, or a QR code.

| | Connect Session | Connect Link |
| --- | --- | --- |
| Lifetime | Single-use, expires | Permanent and reusable |
| User binding | Tied to a specific user | Not tied to a user; identity is collected at open time |
| Created via | `POST /connectSessions` API call | Gigs Dashboard |
| Sharing | One session URL per user | One URL shared with many users |

## The Connect Link URL

A published Connect Link has the following structure:

```
https://<your-connect-domain>/link/<linkId>
```

`<your-connect-domain>` is your project's configured Connect domain, and `<linkId>` is the ID of the link. For example:

```
https://connect.example.com/link/lnk_abc123?plan=pln_5gb
```

## Available intents

Connect Links support the following intents:

| Intent | Use case |
| ------ | -------- |
| [checkoutNewSubscription][intent-checkoutnewsubscription] | How do I let a user purchase a new plan? |
| [checkoutAddon][intent-checkoutaddon] | How do I let a user buy an add-on for their subscription? |
| [viewSubscriptions][intent-viewsubscriptions] | How do I show a user all their subscriptions? |
| [changeSubscription][intent-changesubscription] | How do I let a user upgrade or change their plan? |
| [viewEsimInstallation][intent-viewesiminstallation] | How do I show a user their eSIM installation instructions? |
| requestSupport | How do I let a user reach support for a subscription? |

## Required parameters

Required parameters can be supplied as query strings when someone opens the link (e.g. `?plan=pln_…`). This lets you reuse one link for different plans, devices, or subscriptions by changing the URL instead of creating separate links. The link will show an error if any required parameter is missing. Required parameters can be information such as the plan or device.

When a user opens the link, Connect checks that:

1. The link exists.
2. The link's status is `valid`.
3. Every required parameter is present in the URL.
4. Each parameter value has a valid format.

If any of these checks fail, the user is shown an error page instead of the Connect flow. Make sure every required parameter is included in the URLs you share.

## Signing in

Because a Connect Link is not tied to a specific user, users identify themselves when they open the link. New users are asked for their email address and verify it with a one-time code before continuing; returning users with an active session can continue with a single click.

## Disabling a link

Connect Links can be disabled by making the status `invalid`. Please ask your Gigs point of contact to disable a link for you.

## Where to go from here

- Read about [Connect Sessions][about-connect-sessions] and how they compare
- Read about [Creating Connect Sessions][create-connect-sessions]
- Reach out to [support@gigs.com][gigs-support] for assistance

[gigs-support]: mailto:support@gigs.com
[about-connect-sessions]: /docs/connect/connect-sessions/about
[create-connect-sessions]: /docs/connect/connect-sessions/creating-connect-sessions
[intent-checkoutnewsubscription]: /docs/connect/connect-sessions/intent-checkoutnewsubscription
[intent-checkoutaddon]: /docs/connect/connect-sessions/intent-checkoutaddon
[intent-viewsubscriptions]: /docs/connect/connect-sessions/intent-viewsubscriptions
[intent-changesubscription]: /docs/connect/connect-sessions/intent-changesubscription
[intent-viewesiminstallation]: /docs/connect/connect-sessions/intent-viewesiminstallation