> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deep Links

> Triggering recordings from your app

## Overview

Sales is hard. Empower your sales team by giving them an automatic recording experience.

The [Siro](https://siro.ai) app accepts deep links to start and stop recordings and then redirects you back to your app. This lets you create an experience for sales reps that starts and ends recordings nearly automatically.

### Best Practices

**Good 👍:** Sales reps don't need to change their current behavior, but suddenly all of their conversations are recorded for them. The experience feels magical.

**Bad 👎:** Making your sales reps tap an extra button to start and stop recordings. This is a tedious experience that feels like more work. Worst of all, reps will sometimes forget to record and lose critical conversation intelligence.

### Link Behavior

* If a recording is already in progress, it will not be interrupted
* Deep links will skip all post-recording debrief screens

<iframe src="https://www.youtube.com/embed/lyCRBdHtP-Y" title="YouTube video player" frameborder="0" width="100%" height="500px" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

# Recording Action Links

## URL Format

```
https://app.siro.ai/record?action={action}&redirectUrl={redirectUrl}
```

## Parameters

### `action` (required)

Can be one of the following: `start`, `stop`, or `restart`

* **`start`** - Starts a new recording, or opens the Siro app and continues a recording if one is paused or already recording
* **`stop`** - Fully stops a recording in progress. This will skip past the paused state and end the recording entirely. This will also skip past any post-recording debrief screens
* **`restart`** - Fully stops a recording and restarts a brand new recording

### `title` (optional)

The `title` parameter accepts a string and will set the recording title. This parameter is only valid for `start` actions.

### `conversationType` (optional)

The `conversationType` parameter pre-selects which conversation type the recording is created with — overriding the rep's default for this one recording only.

The value must be a `conversationType` **UUID** belonging to a conversation configuration in the rep's organization. It is not the display name (e.g. `"Sample Conversation Type"`).

**Behavior:**

* If the UUID matches one of the org's loaded conversation configurations, the recording is created with that type, and the post-recording confirmation screen shows it pre-selected.
* If the UUID is missing, malformed, or doesn't match a configuration in the rep's org, the recording falls back to the rep's default conversation type. No error is shown to the rep.
* The override is **one-shot**: the rep's default conversation type is not changed by the deep link. The next recording (without a deep link) still uses their default.

This parameter is only valid for `start` and `restart` actions.

#### Looking up the `conversationType` UUID

The UUIDs come from your organization's conversation configurations. You can retrieve them via the Siro internal API — see [**GET Conversation Configurations**](/api-references/get-conversation-configurations) for the full reference.

```
GET https://app.siro.ai/api-internalApi/v1/core/conversation-configurations?organizationId={organizationId}
```

**Authentication:** Requires a `SiroAuthToken` whose user is either:

* a member of the organization being queried,
* an organization admin for that organization, or
* a Siro admin.

Any other caller will receive a `403 Forbidden`.

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "exampleOrgId123456789-00000000-0000-0000-0000-000000000001",
      "conversationType": "00000000-0000-0000-0000-000000000001",
      "displayName": "Example Conversation Type A",
      "orgId": "exampleOrgId123456789",
      ...
    },
    {
      "id": "exampleOrgId123456789-00000000-0000-0000-0000-000000000002",
      "conversationType": "00000000-0000-0000-0000-000000000002",
      "displayName": "Example Conversation Type B",
      "orgId": "exampleOrgId123456789",
      ...
    }
  ]
}
```

Use the `conversationType` field (not `id`) as the value for the deep-link parameter. Store the mapping from your own internal conversation labels → Siro `conversationType` UUIDs on your side; the UUIDs are stable per configuration.

#### Example link

```
https://app.siro.ai/record?action=start&conversationType=00000000-0000-0000-0000-000000000002
```

### `redirectUrl` (optional)

An optional encoded URL that the app will use to redirect after the given action is performed.

**Important Notes:**

* All URL parameters in the link need to be URL encoded (e.g., the `/` character becomes `%2F`)
* We recommend backlinking to your app using Universal Links (iOS) and App Links (Android). Otherwise, if you are using an app schema to redirect to your app (example: `yourApp://`), you will need to ask the Siro team to whitelist your app in our next deployment. Please reach out to `vince@siro.ai`. It may take weeks to get your app whitelisted, so plan accordingly.

### `integrationConnectionId` (optional)

An optional connection ID the app will use to identify the CRM integration. Organization admins can create integration connection IDs in the [web app's integrations page](https://siro-console-stg.web.app/#/integrations).

**Important Notes:**

* This is required for the `crmObjects` parameter to be accepted
* This parameter is only valid for `start` and `restart` actions

### `crmObjects` (optional)

A URL-encoded array of CRM objects that relate to the recording.

#### CRM Object Structure

```ts theme={null}
type CRMObject = {
  objectType:
    | "Lead"
    | "Account"
    | "Contact"
    | "Opportunity"
    | "Engagement"
    | "Event"
    | "ServiceAppointment";
  objectId: string;
};
```

#### Object Properties

* **`objectType`** - The recording's relationship to entities in the CRM. Must be one of: `Lead`, `Account`, `Opportunity`, `Engagement`, `Event`, or `ServiceAppointment`
* **Lead** - Analogous to a Salesforce Lead. Pre-opportunity prospect.
* **Account** - Analogous to a Salesforce Account. Customer details.
* **Contact** - Analogous to a Salesforce Contact. More fine-grained optional customer details that can be linked to a broader Account.
* **Opportunity** - Analogous to a Salesforce Opportunity. Represents a potential sale and internally tracked as a Siro Opportunity with amount and disposition.
* **Engagement** - A customer/prospect engagement (ie. a meeting, appointment). Associated with a Siro Engagement internally.
* **Event** - Salesforce Event.
* **ServiceAppointment** - Salesforce Field Service ServiceAppointment.
* **`objectId`** - The ID of the entity in the CRM

#### Full Example:

```ts theme={null}
// Before URL encoding
[
  {
    objectType: "Lead",
    objectId: "lead123"
  },
  {
    objectType: "Opportunity",
    objectId: "opp456"
  }
]

// After URL encoding
[{"objectType"%3A"Lead"%2C"objectId"%3A"lead123"}%2C{"objectType"%3A"Opportunity"%2C"objectId"%3A"opp456"}]
```

**Note:** The array must be URL-encoded to be properly accepted.

* `integrationConnectionId` is required for the `crmObjects` parameter to be accepted
* This parameter is only valid for `start` and `restart` actions. If used with a restart action, the new recording that is started will be linked to that opportunity

### `opportunityId` (optional) (deprecated)

The `opportunityId` parameter accepts a string and will automatically link this recording with the associated opportunity in Siro. Opportunities are deals that can stretch over multiple appointments.

**Important Notes:**

* This parameter is only valid for `start` and `restart` actions
* If used with a restart action, the new recording that is started will be linked to that opportunity

See [**PUT Sync Opportunities**](/api-references/sync-an-opportunity)

**Deprecated:** The `jobId` parameter can also be used. Siro treats this as the `opportunityId`.

**Deprecated:** The `opportunityId` parameter is also being replaced with `integrationConnectionId` and `crmObjects`. New integrations should use these parameters instead.