Hootsuite

Hootsuite Connection

Put Hootsuite to Work with @Human Automations and @Human Agents

The Hootsuite Connection documents all Triggers, Actions and Query Operations available for creating automations via the Hootsuite API.

What can you do with the Hootsuite Connection?

• Connect to the Hootsuite API in a few clicks

• Use the related Hootsuite Operations (see below) in @Human Automations or @Human Agents

Related Operations

Trigger Operations

Message Scheduled

Triggers on: hootsuite/messages/messages.scheduled

Triggered when a social media message is successfully scheduled in Hootsuite.

Message Published

Triggers on: hootsuite/messages/messages.published

Triggered when a scheduled social media message is successfully published.

Message Failed

Triggers on: hootsuite/messages/messages.failed

Triggered when a social media message fails to be published.

Media Upload Success

Triggers on: hootsuite/media/media.upload.success

Triggered when a media file is successfully uploaded for use in messages.

Media Upload Error

Triggers on: hootsuite/media/media.upload.error

Triggered when an error occurs during a media file upload process.

Suggestion Created

Triggers on: hootsuite/suggestions/suggestions.created

Triggered when a new amplify content suggestion is created.

Action Operations

Action: Create Media Upload Job

Action: Get Media Upload Status

Action: Schedule Message

Action: Suggest Content to Amplify

Query Operations

Example link

Related Automations

Example link

Obtaining Access Credentials

To obtain a Personal Access Token (PAT) for Hootsuite, follow these steps:

Prerequisites

1. A Hootsuite Business/Enterprise account (PATs are not available for Free/Professional plans).

2. Admin/Super Admin permissions to generate tokens.

Steps

1. Log in to your Hootsuite account at https://hootsuite.com.

2. Navigate to User Settings:

   • Click your profile icon (top-right) → "Account & Settings".

3. Go to "My Profile" → "Developer" tab.

4. Under "Personal Access Tokens", click "Create New Token".

5. Provide a name for the token (e.g., "API Integration").

6. Select the required permissions (scopes) for your use case.

7. Click "Create Token".

8. Copy the token immediately (it will not be shown again).

Scopes (Permissions)

Ensure you select the correct scopes, such as:

• offline (for long-lived access)

• manage:social-profiles (if interacting with social accounts)

• publish (for posting content)

Configuring Webhooks

1. Log in to your Hootsuite Developer account at https://developer.hootsuite.com.

2. Navigate to "My Apps" in the top navigation menu.

3. Select the application you want to configure webhooks for, or click "Create App" if you haven't created one yet.

4. Click on "Webhooks" in the left-hand sidebar menu.

5. Click the "Add Webhook" button.

6. Enter your Destination URL in the provided field (this is the endpoint where Hootsuite will send event notifications).

7. Select the Event Topics you wish to subscribe to (e.g., Inbox 2.0 Events, Message Events).

8. Click "Save Webhook" to activate the subscription.

9. Note the Secret Key provided for verifying the X-Hootsuite-Signature header in incoming requests.

Code (Apache v2.0): Service Connectivity and Metadata

{
  "handle": "hootsuite",
  "status": "active",
  "meta": {
    "short": "Hootsuite",
    "description": "A connector for interacting with Hootsuite's API to manage social media content and scheduling.",
    "icon": "hootsuite",
    "tags": ["social media", "scheduling", "content management"]
  },
  "service": {
    "baseURL": {
      "value": "https://api.hootsuite.com/v1"
    },
    "protocol": "https",
    "contentType": "application/json",
    "headers": {
      "Accept": {
        "value": "application/json"
      }
    },
    "auth": {
      "method": "system_to_system",
      "params": {}
    }
  }
}

Code (Apache v2.0): List of External Resources and Internal Mapping

[
  {
    "handle": "messages",
    "meta": {
      "short": "Messages",
      "description": "Schedule and manage social media messages."
    },
    "endpoint": {
      "value": "/messages",
      "placeholders": []
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "The unique identifier of the message."
        }
      },
      {
        "name": "text",
        "type": "String",
        "selector": ["text"],
        "meta": {
          "description": "The text content of the message."
        }
      },
      {
        "name": "socialNetwork",
        "type": "String",
        "selector": ["socialNetwork"],
        "meta": {
          "description": "The social network the message corresponds to."
        }
      },
      {
        "name": "status",
        "type": "String",
        "selector": ["status"],
        "meta": {
          "description": "The current status of the message."
        }
      },
      {
        "name": "socialNetworkIds",
        "type": "String",
        "selector": ["socialNetworks", 0],
        "multivalue": true,
        "meta": {
          "description": "A list of social network names targeted by this message."
        }
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{messageId}}",
          "placeholders": [
            {
              "name": "messageId",
              "type": "String",
              "description": "The ID of the message to retrieve.",
              "required": true
            }
          ]
        },
        "headers": {},
        "queryParams": {},
        "bodyTemplate": null
      },
      "create": {
        "method": "POST",
        "path": {
          "value": "",
          "placeholders": []
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"message\":{\"text\":\"{{text}}\",\"socialNetworks\":[{{socialNetworks}}],\"scheduledAt\":\"{{scheduledAt}}\",\"timezone\":\"{{timezone}}\"}}",
          "placeholders": [
            {
              "name": "text",
              "type": "String",
              "description": "The content of the message.",
              "required": true
            },
            {
              "name": "socialNetworks",
              "type": "String",
              "description": "A JSON array of targeted social networks.",
              "required": true
            },
            {
              "name": "scheduledAt",
              "type": "String",
              "description": "The scheduled publishing time (ISO 8601).",
              "required": true
            },
            {
              "name": "timezone",
              "type": "String",
              "description": "The timezone for the scheduled time.",
              "required": false
            }
          ]
        }
      }
    },
    "webhooks": [
      {
        "event": "messages.scheduled",
        "path": "/webhooks/hootsuite/messages/scheduled",
        "payload": [
          { "name": "id", "type": "String", "selector": ["data", "id"], "meta": { "description": "The unique identifier of the message." } },
          { "name": "text", "type": "String", "selector": ["data", "text"], "meta": { "description": "The text content of the message." } },
          { "name": "status", "type": "String", "selector": ["data", "status"], "meta": { "description": "The current status of the message." } },
          { "name": "scheduledAt", "type": "String", "selector": ["data", "scheduledAt"], "meta": { "description": "The scheduled publishing time (ISO 8601)." } },
          { "name": "socialNetworks", "type": "String", "selector": ["data", "socialNetworks"], "meta": { "description": "A JSON array of targeted social networks." } }
        ]
      },
      {
        "event": "messages.published",
        "path": "/webhooks/hootsuite/messages/published",
        "payload": [
          { "name": "id", "type": "String", "selector": ["data", "id"], "meta": { "description": "The unique identifier of the message." } },
          { "name": "text", "type": "String", "selector": ["data", "text"], "meta": { "description": "The text content of the message." } },
          { "name": "status", "type": "String", "selector": ["data", "status"], "meta": { "description": "The current status of the message." } },
          { "name": "publishedAt", "type": "String", "selector": ["data", "publishedAt"], "meta": { "description": "The actual publishing time." } }
        ]
      },
      {
        "event": "messages.failed",
        "path": "/webhooks/hootsuite/messages/failed",
        "payload": [
          { "name": "id", "type": "String", "selector": ["data", "id"], "meta": { "description": "The unique identifier of the message." } },
          { "name": "text", "type": "String", "selector": ["data", "text"], "meta": { "description": "The text content of the message." } },
          { "name": "error", "type": "String", "selector": ["data", "errorMessage"], "meta": { "description": "The error message if publishing failed." } }
        ]
      }
    ]
  },
  {
    "handle": "media",
    "meta": {
      "short": "Media",
      "description": "Manage files to attach to messages."
    },
    "endpoint": {
      "value": "/media",
      "placeholders": []
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "The unique ID for the media upload job."
        }
      },
      {
        "name": "status",
        "type": "String",
        "selector": ["status"],
        "meta": {
          "description": "The current status of the upload job."
        }
      }
    ],
    "operations": {
      "upload": {
        "method": "POST",
        "path": {
          "value": "/upload",
          "placeholders": []
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"filePath\":\"{{filePath}}\",\"socialNetwork\":\"{{socialNetwork}}\",\"scheduledTime\":\"{{scheduledTime}}\"}",
          "placeholders": [
            {
              "name": "filePath",
              "type": "String",
              "description": "The path to the file on the local file system.",
              "required": true
            },
            {
              "name": "socialNetwork",
              "type": "String",
              "description": "The specific network targeted.",
              "required": true
            },
            {
              "name": "scheduledTime",
              "type": "String",
              "description": "Optional scheduled time for the post.",
              "required": false
            }
          ]
        }
      },
      "readStatus": {
        "method": "GET",
        "path": {
          "value": "/upload/{{jobId}}",
          "placeholders": [
            {
              "name": "jobId",
              "type": "String",
              "description": "The ID of the upload job.",
              "required": true
            }
          ]
        },
        "headers": {},
        "queryParams": {},
        "bodyTemplate": null
      }
    },
    "webhooks": [
      {
        "event": "media.upload.success",
        "path": "/webhooks/hootsuite/media/upload/success",
        "payload": [
          { "name": "id", "type": "String", "selector": ["data", "id"], "meta": { "description": "The unique ID for the media upload job." } },
          { "name": "status", "type": "String", "selector": ["data", "status"], "meta": { "description": "The current status of the upload job." } }
        ]
      },
      {
        "event": "media.upload.error",
        "path": "/webhooks/hootsuite/media/upload/error",
        "payload": [
          { "name": "id", "type": "String", "selector": ["data", "id"], "meta": { "description": "The unique ID for the media upload job." } },
          { "name": "error", "type": "String", "selector": ["data", "error"], "meta": { "description": "The reason for the upload failure." } }
        ]
      }
    ]
  },
  {
    "handle": "suggestions",
    "meta": {
      "short": "Amplify Suggestions",
      "description": "Retrieve content suggestions that can be amplified."
    },
    "endpoint": {
      "value": "/v2/suggestions",
      "placeholders": []
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "The ID of the suggestion."
        }
      },
      {
        "name": "content",
        "type": "String",
        "selector": ["content"],
        "meta": {
          "description": "The content of the suggestion."
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": "",
          "placeholders": []
        },
        "headers": {},
        "queryParams": {
          "socialProfileIds": "{{socialProfileIds}}",
          "limit": "{{limit}}"
        },
        "bodyTemplate": null
      }
    },
    "webhooks": [
      {
        "event": "suggestions.created",
        "path": "/webhooks/hootsuite/suggestions/created",
        "payload": [
          { "name": "id", "type": "String", "selector": ["data", "id"], "meta": { "description": "The ID of the suggestion." } },
          { "name": "content", "type": "String", "selector": ["data", "content"], "meta": { "description": "The content of the suggestion." } }
        ]
      }
    ]
  }
]