SocialHub for Developers

SocialHub for Developers

  • Help

›General APIs

Get Started

  • Overview
  • Integration
  • REST
  • WebHooks

General APIs

  • Manifest
  • Channel

Inbox APIs

  • Ticket

Resources

  • API Changelog
  • Signature Code Examples
Edit

Manifest API

The SocialHub Manifest API allows the manipulation of Channel Manifests. Manifests are automatically created for Custom Channels and define a Network's capabilities and configures communication with its Integration. A Custom Channel will start off with an empty default Manifest which should be adjusted as needed by the Integration.

Once a Manifest has been promoted to being "Reusable" it will appear as an available Network to Customers allowing the creation of additional Channels using the same configuration.

Updating Manifests

Manifests can be partially updated using the REST API route PATCH /manifest.

The Manifest that should be updated is identified by looking up the Channel specified in the JWT. Note that once a Manifest has been promoted, it is currently no longer possible to update it without contacting the SocialHub Team.

Also take a look at the Swagger API Reference.

Example

Example Manifest manipulation request made with the unix tool cURL:

curl -X PATCH "https://api.socialhub.io/manifest?accesstoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SWQiOiI1YzliNmIyYTU4YTg1NTA3NGQxZDI3OGYiLCJjaGFubmVsSWQiOiI1YzljMDE5NTJiZGZkNzE4MzA3YTBhNTMiLCJpYXQiOjE1NTQxMzQ1NDF9.mXomId0-stW1l4QQQkjeBflo74ZIHzd0-Xj_71VyncA" -d '
{
  "webhook": {
    "url": "https://socialhub.example.com/webhook",
    "secret": "random_32_or_more_chars_long_string"
  },
  "inbox": {
    "ticketActions": [{
      "type": "reply",
      "id": "reply-as-comment",
      "label": {
        "en": "Reply",
        "de": "Reply"
      }
    }],
    "rightSidebar": [{
       "id": "sidebar-id",
       "label": {
          "en": "sidebar-label",
          "de": "sidebar-label"
       },
       "treeBuilder": "flatListWithoutRoot"
    }]
  }
}
' -H "Content-Type: application/json"

Request

FieldDescription
nameRead only. Manifests of normal Custom Channels do not have a name. Manifests that have a name have been promoted to being reusable. The name is what will be shown as Network name on the Channel Settings page.
brandingOptional Network branding such as icons and color schemes
webhookWebHook specific configuration. A test request will be made whenever this is updated!
inboxInbox product specific configuration.
callbacksRedirect URLs for Channel management.

branding

FieldDescription
iconHTTPS URL to Network icon (eg. Twitter Bird)
fallbackHTTPS URL to fallback icon (eg. shown for ticket interactors without avatar)
colorHTML Hex color code for Network branding (eg. Facebook blue #3b5998 for Ticket borders)

webhook

FieldDescription
urlHTTPS URL of the Integration's WebHook.
secretSecret used for request signing. Should be a long random string with at least 32 characters.

inbox

FieldDescription
ticketActionsConfigures the actions available on Tickets within the Inbox.
rightSidebarConfigures the tabs available in the right sidebar after clicking on a Ticket within the Inbox.

inbox.ticketActions[]

FieldDescription
typeType of the Ticket Action. At the moment we support reply, template_reply and button actions. There may be multiple actions of the same type.
idIdentifier of the Action. Each Action within a manifest must have a different identifier. Pattern regular expression: ^[a-zA-Z0-9-_]{1,256}$
labelButton labels for different locales. Locale is selected depending on user settings.
configConfiguration options for this Ticket Action.
attachmentsIf set ({}) for Ticket Actions of type reply, it's possible to attach files for the reply. At a later point you'll be able to specify a file schema to control what kind of attachments are allowed – for now there is no restriction an all checks should happen on the Integration's end.
optionsArray of dropdown options for the action. At the moment supported for the reply action. If options are set for an action, the user will have to choose one from the dropdown before creating the reply.

inbox.ticketActions[].label

FieldDescription
enHuman-readable label for English locale.
deHuman-readable label for German locale.

inbox.ticketActions[].config

FieldDescription
approvalProcessBoolean (default is true) controlling whether the Approval Process feature should be applied for this Ticket Action. Only supported for reply and template_reply at this moment
templates.urlURL to fetch templates for the template_reply action from. Required for the template_reply action.
timeoutAction timeout configuration options.
forceTaggingBoolean (default is true) controlling whether the feature forcing the user to add tag(s) to the ticket should be applied for this Ticket Action.

inbox.ticketActions[].config.timeout

FieldDescription
durationTime after which the action is no longer available. Uses juration for parsing.
afterField the timeout is counted from. Currently only networkCreationTime is supported, which bases the timeout on the ticket.interaction.createdTime field.

inbox.ticketActions[].attachments

FieldDescription
noTextBoolean (default is false). If set to true then there is no additional text allowed when an attachment was added to the reply.

inbox.ticketActions[].options[]

FieldDescription
idUnique id of the option which will be sent to the integration in the reply payload.
labelButton labels for different locales. Locale is selected depending on user settings.
descriptionOptional description of the option which will be shown to the user below the reply editor once an option has been selected.
inbox.ticketActions[].options[].label
FieldDescription
enHuman-readable dropdown label for English locale.
deHuman-readable dropdown label for German locale.

inbox.rightSidebar[]

FieldDescription
idString identifier for this sidebar Tab.
labelSidebar Tab labels for different locales. Locale is selected depending on user settings.
treeBuilderThe tree-builder algorithm to use. Currently only flatListWithoutRoot and flatListWithRoot are supported.

The flatListWithoutRoot tree builder simply displays all Tickets in the right sidebar that share the same Root-Ticket excluding the Root-Ticket itself.

flatListWithRoot tree builder displays all Tickets with the same Root-Ticket including the Root-Ticket. Root-Ticket in the sidebar will have some additional actions like Show unread Tickets in the Inbox.

inbox.rightSidebar[].label

FieldDescription
enHuman-readable label for English locale.
deHuman-readable label for German locale.

callbacks

FieldDescription
channelCreationHTTPS URL of an Integration website the Customer should be redirected to in order to add new Channels for a Reusable Manifest.
channelReactivationHTTPS URL of an Integration website the Customer should be redirected to in order to reactivate an existing Channel belonging to a Reusable Manifest.

Responses

The following error responses should the handled by the Integration's client:

HTTP 200 OK

Returns the successfully updated Manifest object.

If the request body was empty ({}) nothing was updated and the current Manifest is simply returned in full.

HTTP 422 Unprocessable Entity

{
  "code": "WebhookValidationError",
  "message": "Error: An error occurred while attempting to validate the WebHook",
  "data": "Error: getaddrinfo ENOTFOUND socialhub.example.com socialhub.example.com:443"
}

Is returned whenever the WebHook URL specified in the Manifest is not reachable by the HTTPS test request. The data value is the internal error that occurred when the test was attempted and should help debugging the issue.

It's also possible that we were able to execute the HTTPS request but the response did not contain a valid challenge response header:

{
  "code": "WebhookValidationError",
  "message": "Error: The WebHook failed to solve the challenge"
}

Or that the SSL certificate the WebHook is hosted with is no longer valid:

{
  "code": "WebhookValidationError",
  "message": "Error: An error occurred while attempting to validate the WebHook",
  "data": "Error: certificate has expired"
}

Callbacks

Channel Creation

Is required to be set for Reusable Manifests in callbacks.channelCreation. SocialHub will redirect users clicking on the "Add Channel" Button of a Reusable Manifest Network to this URL with a special temporary JWT (as ?token= query parameter) that can only be used for the Channel creation route.

This JWT has the following payload:

{
  "accountId": "5c9b6b2a58a855074d1d278f",  // Id of the Account the token belongs to
  "manifestId": "5e73f56c5a45da10b6e614dd", // Id of the Manifest the User wants to create channels for
  "userId": "5e73f5255a45da10b6e614da",     // Id of the User wanting to create channels
  "origin": "https://app.socialhub.io",     // URL of the SocialHub platform to redirect back to
  "teamIds": ["635519489f8e665f0d2cfacb"],  // An optional list of Ids of teams to which the channel will be automatically assigned
  "iat": 1554134541,                        // Timestamp in seconds of the token issuing date
  "exp": 1554136341                         // Timestamp in seconds of the token expiration date (30 mins)
}

Channel Reactivation

May be set for Reusable Manifests in callbacks.channelReactivation. SocialHub will redirect users wanting to reactivate a disabled Channel belonging the Integration's Reusable Manifest to this URL with a special temporary JWT (as ?token= query parameter) that can only be used for the Channel creation route (which is also used for reactivating Channels).

This JWT has the following payload:

{
  "accountId": "5c9b6b2a58a855074d1d278f",  // Id of the Account the token belongs to
  "manifestId": "5e73f56c5a45da10b6e614dd", // Id of the Manifest the User wants to create channels for
  "userId": "5e73f5255a45da10b6e614da",     // Id of the User wanting to create channels
  "origin": "https://app.socialhub.io",     // URL of the SocialHub platform to redirect back to
  "channelId": "5c9c01952bdfd718307a0a53",  // Id of the Channel that should be reactivated
  "uniqueName": "test",                     // Unique name of the Channel
  "networkId": "39272404",                  // Unique network ID of the Channel (optional)
  "iat": 1554134541,                        // Timestamp in seconds of the token issuing date
  "exp": 1554136341                         // Timestamp in seconds of the token expiration date (30 mins)
}

Templates

Ticket Actions of type template_reply require a callback URL to be set (inbox.ticketActions[].config.templates.url) from where a list of available templates are fetched from.

The ID of the Channel the templates are requested for will be passed as ?channelId= query parameter. For additional security the request will be signed the same way a WebHook request would be.

This callback URL should return templates and their variables following this example:

[{
  // Human readable name of the template to display to the SocialHub user.
  "name": "Test Greeting",
  // Machine identifier of the template.
  "networkId": "test_greeting",
  // Variables the user may fill out for this template (json schema format).
  "variables": {
    "firstName": {
      "type": "string",
      "minLength": 2,
      "maxLength": 12
    }
  },
  // Text templates used for previewing message (handlebars format).
  "text": {
    "en": "Hello {{firstName}}",
    "de": "Hallo {{firstName}}",
    "fr": "Bienvenue {{firstName}}"
  }
}]

The networkId of the Template the user selected and the values the variables have been filled with, will be sent as part of the ticket_action event payload once the template_reply Action has been submitted.

← WebHooksChannel →
  • Updating Manifests
    • Example
    • Request
    • Responses
  • Callbacks
    • Channel Creation
    • Channel Reactivation
    • Templates
SocialHub for Developers
Resources
GitHubZendesk User ManualYouTube Channel
Community
Stack OverflowFacebook UsergroupFeature Community
SocialHub
WebsiteImprint (int)Impressum (de)
SocialHub
Copyright © 2023 SocialHub