App Launch and Enablement

App Registration

You must register your app on Talkdesk® by accessing Partner Project and creating a new app project.

There are three main stages for executing a partner app:

  • Installing and launching the app via My Apps/Talkdesk AppConnect™ (details on the video below).

App Installation, Updates Setting and Uninstallation

Using the app.installed, app.updated, app.uninstalled events, you get credentials to access the app installation/updates setting and uninstallation. With this, you can initiate the Client Credentials authentication flow to retrieve an account-level access token.

You receive a unique Talkdesk ID for each customer installation, to provision a new account in their environment. Using the new access token, you can leverage Accounts API to get the information to automatically create the account in the partner app.

Apps API can also be leveraged. This gives you a unique Talkdesk ID tied to the installation/updates setting/uninstallation instance, as well as to the users that got a license for this app. Talkdesk recommends creating a corresponding user, and storing the user mappings in your system during this step.

🚧

When a Talkdesk user installs/uninstalls an app from a partner listing on AppConnect or updates the subscription option for the partner’s service (i.e. from trial to paid), Talkdesk makes an API call to the service at the event's callback URL the partner provided when the app was registered.

❗️

Installation/Update/Uninstallation Timeouts

The customer has seven days to confirm the installation/update/uninstallation before the process times out in Talkdesk. At this point, the user will be provided with the ability to repeat the process.
Talkdesk doesn't recommend a manual response to this process.

❗️

Events API Retry

If there is an error, Talkdesk will attempt a retry to the partner’s service after five minutes, and then again after 10 minutes, if necessary.

1924

Figure 1 - App Enablement

📘

Submitting an App Version

All information about creating and managing app versions is here.

🚧

Accessing Installation Data

When accessing data from a specific installation, you must use an access token generated from the OAuth client provided on the app.installed event. You can only change data associated with the resource (e.g.: approving or rejecting an installation request) via that token. When generating this access token, you must specify the scopes you want to include (see the examples below).

🚧

Installing Status

After the app.installed event is fired, the new app is set to the installing status. To approve the completion of the installation, specify the apps:write scope in your access token, making a POST request to /apps/{app_id}/installations/{id}/state.

This must be done as soon as the app is ready to be used by the customer.
The completion of the installation request can be rejected.

Talkdesk recommends that this installation process runs as synchronous and instantaneous as possible. The app must give the user a useful experience immediately, in the form of sample dashboards, tutorials, etc.

🚧

Updating Status

After the app.updated event is fired, the app is set to the updating status.
To approve the completion of the settings update, specify the apps:write scope in your access token, making a POST request to /apps/{app_id}/installations/{id}/state.

🚧

Uninstalling Status

After the app.uninstalledevent is fired, the app is set to the uninstalled status.

To approve the completion of the settings update, specify the apps:write scope in your access token, making a POST request to /apps/{app_id}/installations/{id}/state.

❗️

Uninstallation/Reinstallation

The partner app can’t be uninstalled without your approval via the API call.

You must allow for uninstallations and reinstallations of the same app within the same Talkdesk account.

For the best user experience, Talkdesk recommends storing any metadata or settings for the user account, if the user decides to reinstall the app later.

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.