App installation settings

When your app is installed you may want the user to submit some data to your app such as their instance id of your service. You can either instruct Outreach to show a dialog to enter the data into Outreach during installation or redirect to your server to collect the required data at your own URL. You can set up both variants in the "App installation settings" feature.

Collecting app configuration inside Outreach

To collect configuration values through Outreach dialog press the "Add config key" button and specify properties for this configuration field. This will create a field in the Outreach installation process. You can add as many fields as necessary. Be sure to check the "Mandatory" checkbox if your application cannot continue without receiving value for this particular key.

You can read the provided configuration data from the config field of the OutreachContext object.

Please be aware that all values will be readable in plain text at app runtime. Do not use this feature for sensitive values like private API keys.

External configuration setup URL

Outreach can also redirect the user to your server where they can provide configuration values directly to your service. To use this method, specify the external configuration setup URL where the user should be redirected. Note that if you have also configured S2S API access Outreach will append a installSetupToken query parameter to the URL you have specified.

The installSetupToken is valid for 15 minutes. Use the token value to validate the request has originated from Outreach by calling Outreach API with it and get the app installation object as well as information about the organization installing your app in return.

You may persist this information on your servers and attach any user-specified settings to it in your local database. Subsequent webhook requests from this organization will carry the same INSTALL_ID.

User may choose to return to this page later in order to reconfigure the application.

Validating external configuration

The external configuration page is accessible via a button on the management page of each installed application (Administration - Integrations - Installed Apps - - Configuration Tab).

If you have enabled SETUP event type on the App lifecycle webhooks page, we will call your webhook endpoint with install.statusCheck meta.eventName and you can return information about the state of information on your side.

Timeout or non 2xx HTTP response will be reported to the user as a failure to query the state.

If the integration is not properly setup (and you need the user to visit your configuration page) return a JSON like

{
  "meta": {
    "message": "Missing authorization.",
    "status": "error"
  }
}

message is optional, if you do not provide it we will display a generic error message.