Deep Links

Overview

Trigger recording actions in the Rilla mobile app directly from your own app or CRM using the com.rillavoice:// URL scheme. No API key required.

URL Scheme

com.rillavoice://

Actions

Start, stop, pause, and resume recordings.

Callbacks

Receive status callbacks in your app after an action.

Errors

Handle errors returned in deep link callbacks.

How it works

Construct the URL with the action and optional parameters, then open it with your platform's URL-opening API (e.g. Linking.openURL on React Native, openURL on Swift).

The Rilla app opens or comes to the foreground and immediately performs the recording action (start, stop, pause, or resume).

If you included a deep_link parameter, Rilla appends c__status and optional error fields to that URL, then opens it — returning the user to your app.

Actions

All recording actions share the same base path: com.rillavoice://recording. The action is determined by which boolean parameter you set to true.

Start

com.rillavoice://recording?start=true&event_id={event_id}&title={title}&deep_link={deep_link}

Parameter	Type	Required	Description
`start`	boolean	Yes	Must be `true`.
`event_id`	string	No	ID of the appointment to link this recording to.
`title`	string	No	Title displayed in Rilla during recording.
`deep_link`	string	No	Callback URL after the recording starts.

event_id and title must be passed together — neither works without the other.

Stop

com.rillavoice://recording?stop=true&deep_link={deep_link}

Parameter	Type	Required	Description
`stop`	boolean	Yes	Must be `true`.
`deep_link`	string	No	Callback URL after the recording stops.

Pause

com.rillavoice://recording?pause=true&deep_link={deep_link}

Parameter	Type	Required	Description
`pause`	boolean	Yes	Must be `true`.
`deep_link`	string	No	Callback URL after the recording pauses.

Resume

com.rillavoice://recording?resume=true&deep_link={deep_link}

Parameter	Type	Required	Description
`resume`	boolean	Yes	Must be `true`.
`deep_link`	string	No	Callback URL after the recording resumes.

Callbacks

When you include a deep_link parameter in any action URL, Rilla appends status information to that URL and opens it after the action completes.

How it works

URL-encode it when embedding it in the deep link URL.

Start, stop, pause, or resume — whichever was requested.

c__status=success on success; c__status=error plus error details on failure.

Parse the callback URL parameters to determine what happened.

Success callback

yourapp://home?c__status=success

Error callback

yourapp://home?c__status=error&c__errorType=MicrophoneAccessError&c__errorMessage=Microphone+Access+Denied&c__action=start

Callback Parameters

Parameter	Description
`c__status`	`success` or `error`.
`c__errorType`	Machine-readable error type. Only present when `c__status` is `error`.
`c__errorMessage`	Human-readable error description. Only present when `c__status` is `error`.
`c__action`	The action attempted: `start`, `stop`, `pause`, or `resume`.

Parameters are prefixed with c__ for Salesforce Lightning compatibility — Lightning only recognises custom URL parameters with this prefix.

Full Example

1. Open this deep link to start a recording:

com.rillavoice://recording?start=true&event_id=appt-1234&title=Home+Estimate+-+Jane+Smith&deep_link=yourapp%3A%2F%2Fhome

2. Rilla starts the recording, then opens:

yourapp://home?c__status=success&c__action=start

3. On error:

yourapp://home?c__status=error&c__errorType=MicrophoneAccessError&c__errorMessage=Microphone+Access+Denied&c__action=start

When a deep link action fails, Rilla returns c__status=error in the callback URL along with c__errorType and c__errorMessage. Use c__errorType for programmatic handling — it is stable and will not change.

Error Type	Message	Description	Fix
`MicrophoneAccessError`	Microphone Access Denied	The user has not granted Rilla microphone permission.	Direct the user to device settings to enable microphone access.
`ActiveRecordingError`	Recording already in progress	A start action was triggered but a recording is already running.	Stop or pause the existing recording before starting a new one.
`UnableToPrepareRecorderError`	Another app may be using the microphone	The audio session could not be activated.	Ask the user to close other apps using audio.
`NotificationsDisabledError`	Notifications are not enabled for Rilla	On Android, Rilla requires notification permission for the foreground service.	Direct the user to device settings to enable notifications.
`NoActiveRecordingError`	No active recording	A stop, pause, or resume was triggered but no recording is active.	Verify recording state before sending stop/pause/resume.
`RecordingTooShortError`	Recording is too short	The recording was stopped before the minimum required duration.	No action needed — the recording was discarded.
`RecordingInterruptedError`	Unable to perform action due to recording being interrupted	The recording was interrupted by an external event (e.g. phone call).	The user should start a new recording.
`OtherError`	Unable to perform action	An unexpected error occurred.	Check `c__errorMessage` for detail. Contact support@rilla.com if it persists.