> For the complete documentation index, see [llms.txt](https://docs.indicio.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.indicio.tech/developer/mobile-solutions/mobile-sdk/connections.md).

# Connections

## Creating a Connection

All connections are made through the Out of Band protocol using the Out of Band module on the Agent.

First you have to get an Out of Band invitation. This is done using one of two methods: either through a QR code that resolves to a URL (most common), or from a JSON object in the form of a string.

## Parsing the invitation

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// The url commonly comes from the result of scanning a QR code.
val invitation = OutOfBandInvitationMessage.fromUrl(url)
// Or if you have the message in json already
val invitation = OutOfBandInvitationMessage.fromJsonString(str)
```

{% endtab %}

{% tab title="React Native" %}

```typescript
// parses the URL to a json string
const invitation: string = agent.outOfBand.parseInvitation(invitationUrl)
```

{% endtab %}
{% endtabs %}

Once you have the Out of Band invitation you will have the Agent accept the invitation. The receiveInvitation function has many options but to automatically make a connection with the provided invitation you can supply just the invitation like the examples below.

## Receiving and waiting for a completed connection

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// Completed connection status may or may not be done after this call
val records = agent.outOfBand.receiveInvitation(invitation)

// Waits for the record to be in the completed state
agent.events.getDidExchangeEvents?.events?.first { event ->
    if (records.didExchangeRecord.id != event.didExchangeRecord.id) {
        event.didExchangeRecord.state == DidExchangeState.Completed
    }
}
```

{% endtab %}

{% tab title="React Native" %}

```typescript
// Takes the json formatted string for the invitation
const records = await agent.outOfBand.receiveInvitation(invitation)

const removeListener = agent?.events.registerDidExchangeHandler((event) => {
  if (event.didExchangeRecord.id === records.didExchangeRecord.id && event.didExchangeRecord.isReady) {
    console.log("Connection complete")
    removeListener()
  }
})
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
While it is not recommended to disable auto acceptance, manually accepting a connection is also an option.
{% endhint %}

## Manually accepting a connection (autoAcceptConnection = false)

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// returns references to records needed to complete connection
val records = agent.outOfBand.receiveInvitation(invitation, autoAcceptConnection = false)

// Connection guaranteed to be completed after this call
val exchangeRecord = agent.didExchange.requestConnection(records.didExchangeRecord!!.id, records.outOfBandRecord.id)
```

{% endtab %}

{% tab title="React Native" %}

```typescript
const record = await agent.outOfBand.receiveInvitation(invitation, false)

const exchangeRecord = await agent.didExchange.requestConnection(records.didExchangeRecord!!.id, records.outOfBandRecord.id)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
NOTE: In the above example you technically have two instances of the didExchange record, one in the `records` variable and one in the `exchangeRecord` variable. Since `records` can be updated asynchronously, always use the most recently returned value or fetch the record by ID if any operations have been done that could affect the Agent's records.
{% endhint %}

## Retrieving and using the didExchange records

Once a connection has been made through the DidExchange protocol the agent will keep a record which holds information about the established connection. A list of all connections can be retrieved and used to create a "contact list".

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// This is a suspend function in Kotlin
val contacts: List<DidExchangeRecord> = agent.didExchange.getAll()
```

{% endtab %}

{% tab title="React Native" %}

```typescript
const contacts = await agent.didExchange.getAll()
```

{% endtab %}
{% endtabs %}

The DidExchange record itself has several properties derived when making a connection based on information provided from the agent that you are connecting to. Some commonly used properties: `did`, `state`, `role`, `theirDid`, `theirLabel`, `createdAt`, `updatedAt`, `alias`, `threadId`, `mediatorId`, `outOfBandId`, `invitationDid`, and `autoAccept`.

Some properties (like `createdAt`, `updatedAt`, and `id`) are present on all records. With DidExchangeRecords you would likely use `theirLabel` or `alias` to create a contact card item for displaying the connection. Other properties like `role` and `state` can be used to filter connections to find a specific connection or locate ones that failed or still need to be accepted after processing the invitation.

## Removing a connection

If you no longer want to have a connection with another agent you can delete the DidExchangeRecord. If you need to reconnect you will have to receive another invitation from the agent, or in some instances invitations can be reused (NOTE: single-use invitations can only be used by one agent while multi-use invitations can be used by multiple).

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val contacts = agent.didExchange.getAll()
// Deleting the first contact in the list
agent.didExchange.deleteById(contacts[0].id)
```

{% endtab %}

{% tab title="React Native" %}

```typescript
const contacts = await agent.didExchange.getAll()

await agent.didExchange.deleteById(contacts[0].id)
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.indicio.tech/developer/mobile-solutions/mobile-sdk/connections.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.