Delivery Approval v2

Validate recipients in your 3rd party system before content gets sent

Purpose

Delivery approval enables an app to validate content and external recipients to be send out via LiveSend from the Seismic web application.

App prerequisites

  • Your app must be configured with a signing secret

How it works

High Level Flow

  • When this extension point is enabled on a tenant, when a user attempts a LiveSend, the 'Send' button is replaced with a 'Validate' button.
  • The user clicks 'Validate' and Seismic sends out the details of the livesends to your external service
  • Your service responds and lets the user know if they are allowed to send content to the user, or it can provide a warning

When it's triggered

  • When a user clicks 'Validate' from the Share Content window

🚧

Delivery approval requests must be acknowledged within 3 seconds

The provider must respond within 3 seconds with one of the following responses:

  • 200 response: A 200 that conforms to the approved response payload documented below.
  • non-200 response: indicates a failure of some kind.

❗️

Downtime

If the provider point goes down, for any reason, users will be unable to make LiveSend distributions.

How to configure

Configure the Delivery Approval Extension Point

  • Add the Delivery Approval V2 extension to your application as described here
  • Fill out the fields
    • Extension Instance Name - A Name that references this usage of this extension point within your app
    • The URL of the Delivery Approval Consent Provider - The URL that we will post the payload to
    • Click Save Changes
    • Make sure to enable the extension point and click Save Changes

Security & Authentication

It is recommended that you validate the Signing Secret in the POST request that Seismic is making to your URL.

📘

v2 Changelog

The v1 Delivery Approval extension supported a custom header and basic auth modes. These have been retired in favor of the Signing Secret auth pattern

Payloads

Outbound payload from Seismic to your endpoint

{
    "appId": "aaa07df8-9ebb-487a-98b8-471ececc5f46"  
    "extensionPoint": "delivery-approval-v2",
    "tenantName": "jurassicpark",
    "tenant": "2438562c-da5f-4b58-b724-d9d7e22cfbf2",
    "occurredAt": "2018-02-04T01:23:17Z",
    "data": {
       "user": {
            "id": "57a0479900-504cb3ab4a1f-626d174d2d"
       },
       "delivery": {
            "type": "email",
            "details": {
                // these will be different based on delivery type
                "containsAttachments": false,
            },
            "formInformation": {
               // anything
            },
            "recipients": [{
                "id": "309ee150-d8ce-40a6-986a-e5efbc109728",
                "firstName": "Joe",
                "lastName": "Demo",
                "emailAddress": "[email protected]",
                 // context that only applies to this recipient
                 "context": [{
                    "systemType": "salesforce",
                    "systemId": null, // this always null for now
                    "contextType": "opportunity",
                    "contextName": "my opportunity",
                    "contextId": "some identifier",
                    "fields": {
                      // flat list of key values configured for this tenant, delivery type, and context type
                    }
                  }]
            }],
            "content": [{
                "repository": "doccenter",
                "type": "file",
                "name": "Brand Values",
                "libraryContent": {
                    "teamsiteId": "b9d85988-17f4-4994-82db-1ea46886046a",
                    "id": "3c3ffbb2-86ad-44d7-b692-b32c9b743ec7",
                    "versionId": "94bb9bd9-4e5e-4ee2-99f0-749a9ce422d2"
                },
                "contentProfileId": "b9d85988-17f4-4994-82db-1ea46886046a",
                "contentProfilePath": ["by Industry", "Non-Profit"]
            }, {
                "repository": "library",
                "type": "template",
                "name": "Brand Values",
                "teamsiteId": "b9d85988-17f4-4994-82db-1ea46886046a",
                "id": "b9d85988-17f4-4994-82db-1ea46886046a",
                "versionId": "b9d85988-17f4-4994-82db-1ea46886046a"
            }, {
                "repository": "workspace",
                "type": "file",
                "name": "Brand Values",
                "id": "b9d85988-17f4-4994-82db-1ea46886046a",
                "versionId": "b9d85988-17f4-4994-82db-1ea46886046a"
            }],
            // context that applies to the whole interaction
            "context": [{
                "systemType": "salesforce",
                "systemId": null, // this always null for now
                "contextType": "opportunity",
                "contextName": "my opportunity",
                "contextId": "some identifier",
                "fields": {
                  // flat list of key values configured for this tenant, delivery type, and context type
                }
          }]
       },
        "clientDetails": {
            "sessionId": "",
            "ipAddress": "74.62.18.18",
            "productArea": "doccenter",
            "deviceType": "pc",
            "browser": "chrome",
            "browserVersion": "",
            "operatingSystem": "windows",
            "operatingSystemVersion": "",
            "locale": ""
        }
    }
}

❗️

Content Properties

Content selected through the 'Paper Airplane' icon does not include content properties in the payload, whereas content that is added from the "+Add" button does have content properties in the payload. We are currently investigating a path forward.
Until this is addressed your app should not rely on Content Properties at this time

Inbound Response from your system to Seismic

{
  "deliveryApproval": {
    // optional. Defaults to approval
    "global": {
      "status": "warn", // global approve/forbid/warn
      "message": "This warning applies to the entire use of the engagement"
    },
    // can be empty. defaults to approving all
    "recipients": [{
        "recipient": {
          "id": "309ee150-d8ce-40a6-986a-e5efbc109728"
        },
 
        // can you deliver to this recipient? Optional, defaults to approve
        "recipientStatus": {
          "status": "forbid",
          "message": "Contact not approved" // optional, used on per-recipient details
        },
 
        // which content are you allowed to send? Optional (defaults to approving all the content)
        "contentStatus": [
          {
            "status": "forbid", // can also be warn.
            "message": "State restriction",
 
            // the content objects that failed the check, echoed back.
            "content": [
              {
                "repository": "doccenter",
                "name": "Brand Values",
                "type": "file",
                "libraryContent": {
                  "teamsiteId": "b9d85988-17f4-4994-82db-1ea46886046a",
                  "id": "b9d85988-17f4-4994-82db-1ea46886046a",
                  "versionId": "b9d85988-17f4-4994-82db-1ea46886046a"
                },
                "contentProfileId": "b9d85988-17f4-4994-82db-1ea46886046a",
                "contentProfilePath": [
                  "by Industry",
                  "Non-Profit"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Rich text formatting

The message objects support a very basic subset of rich-text formatting outlined in the following table.

Style

Syntax

Example

Result

Bold

** **

This text is **bold**

This text is bold

Italic

_ _

This text is _italic_

This text is italic

Bold Italic

**_ _**

This text is **_bold italic_**

This text is bold italic

Link

[] display name () link itself

[Seismic Software](http://seismic.com)

Seismic Software