Installation

Open Claude Code and run this command:

/plugin install hootsuite-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

What It Does

Gives Claude Code deep knowledge of Hootsuite's REST API v1 for social media publishing, analytics, and management. Skills cover OAuth 2.0 authentication, message scheduling with media upload, URL shortening with Ow.ly, and cross-platform post management.

Skills (18)

hootsuite-ci-integration SKILL.md View full skill →

'Configure Hootsuite CI/CD integration with GitHub Actions and testing.

ReadWriteEditBash(gh:*)

Hootsuite CI Integration

Overview

Set up CI/CD for Hootsuite social media management integrations: run unit tests with mocked post scheduling and analytics responses on every PR, validate live API connectivity for social profile queries on merge to main. Hootsuite's API handles scheduled posts, social analytics, and multi-network publishing, so CI pipelines verify scheduling logic, content validation rules, and analytics data aggregation.

GitHub Actions Workflow


# .github/workflows/hootsuite-ci.yml
name: Hootsuite CI
on:
  pull_request:
    paths: ['src/hootsuite/**', 'tests/**']
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --reporter=verbose

  integration-tests:
    if: github.ref == 'refs/heads/main'
    needs: unit-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:integration
        env:
          HOOTSUITE_CLIENT_ID: ${{ secrets.HOOTSUITE_CLIENT_ID }}
          HOOTSUITE_CLIENT_SECRET: ${{ secrets.HOOTSUITE_CLIENT_SECRET }}
          HOOTSUITE_REFRESH_TOKEN: ${{ secrets.HOOTSUITE_REFRESH_TOKEN }}

Mock-Based Unit Tests


// tests/hootsuite-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { schedulePost, getPostAnalytics } from '../src/hootsuite-service';

vi.mock('../src/hootsuite-client', () => ({
  HootsuiteClient: vi.fn().mockImplementation(() => ({
    createMessage: vi.fn().mockResolvedValue({
      id: 'msg_abc123',
      state: 'SCHEDULED',
      scheduledSendTime: '2026-04-07T14:00:00Z',
      socialProfileIds: ['sp_twitter', 'sp_linkedin'],
    }),
    getAnalytics: vi.fn().mockResolvedValue({
      postId: 'msg_abc123',
      metrics: { impressions: 1200, clicks: 85, engagement_rate: 0.071 },
    }),
    listSocialProfiles: vi.fn().mockResolvedValue({
      profiles: [
        { id: 'sp_twitter', type: 'TWITTER', name: '@company' },
        { id: 'sp_linkedin', type: 'LINKEDIN', name: 'Company Page' },
      ],
    }),
  })),
}));

describe('Hootsuite Service', () => {
  it('schedules a multi-network post', async () => {
    const result = await schedulePost('Launch day!', {
      profiles: ['sp_twitter', 'sp_linkedin'],
      scheduledTime: '2026-04-07T14:00:00Z',
    });
    expect(result.state).toBe('SCHEDULED');
    expect(result.socialProfileIds).toHaveLength(2);
  });

  it('retrieves post analytics', async () => {


                
                  
                  
                  hootsuite-common-errors
                  SKILL.md
                  View full skill →
                
                
                  'Diagnose and fix Hootsuite common errors and exceptions.
                  
                      ReadGrepBash(curl:*)
                    
                
                
                  Hootsuite Common Errors
Error Reference
401 Unauthorized
Cause: Access token expired (tokens last ~1 hour).
Fix: Refresh token via OAuth:

curl -X POST https://platform.hootsuite.com/oauth2/token \
  -u "$HOOTSUITE_CLIENT_ID:$HOOTSUITE_CLIENT_SECRET" \
  -d "grant_type=refresh_token&refresh_token=$HOOTSUITE_REFRESH_TOKEN"

403 Forbidden
Cause: App lacks required permissions or user doesn't own the resource.
Fix: Check app scopes in developer portal. Ensure user has access to the social profile.
422 Unprocessable Entity — scheduledSendTime
Cause: Scheduled time is in the past or invalid ISO 8601 format.
Fix: Always use future dates in ISO 8601: new Date(Date.now() + 3600000).toISOString()
422 — socialProfileIds
Cause: Profile ID invalid or disconnected.
Fix: List profiles first: GET /v1/socialProfiles and verify IDs.
429 Too Many Requests
Cause: Rate limit exceeded.
Fix: Implement exponential backoff. See hootsuite-rate-limits.
Media Upload — State REJECTED
Cause: File too large, wrong format, or exceeds platform limits.
Fix: Check per-platform limits: Twitter images 5MB, Facebook 10MB, video varies.
invalid_grant — Token Exchange
Cause: Authorization code expired (30 second lifetime) or already used.
Fix: Re-initiate OAuth flow — codes are single-use and expire in 30s.
redirecturimismatch
Cause: Redirect URI doesn't exactly match app registration.
Fix: Must match character-for-character, including trailing slash.
Quick Diagnostics

# Test token validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/me

# List profiles (verifies full API access)
curl -s -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/socialProfiles | python3 -m json.tool

Resources

Hootsuite API FAQ
REST API Reference

Next Steps
For debugging tools, see hootsuite-debug-bundle.


                
                  
                  
                  hootsuite-core-workflow-a
                  SKILL.md
                  View full skill →
                
                
                  'Execute Hootsuite primary workflow: Core Workflow A.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Hootsuite Publishing — Schedule Posts with Media
Overview
Schedule social media posts with images and videos using the Hootsuite REST API. The publishing workflow involves: uploading media to get a media ID, then scheduling a message referencing that media.
Prerequisites

Completed hootsuite-install-auth setup
Social profiles connected in Hootsuite
Media files (images/videos) for upload

Instructions
Step 1: Upload Media

// publishing.ts
import 'dotenv/config';
import fs from 'fs';

const TOKEN = process.env.HOOTSUITE_ACCESS_TOKEN!;
const BASE = 'https://platform.hootsuite.com/v1';

// Step 1a: Create upload URL
async function createMediaUpload(sizeBytes: number, mimeType: string) {
  const response = await fetch(`${BASE}/media`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sizeBytes, mimeType }),
  });
  const { data } = await response.json();
  console.log('Upload URL:', data.uploadUrl);
  console.log('Media ID:', data.id);
  return data; // { id, uploadUrl, uploadUrlDurationSeconds }
}

// Step 1b: Upload file to the S3 URL
async function uploadFile(uploadUrl: string, filePath: string, mimeType: string) {
  const fileBuffer = fs.readFileSync(filePath);
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': mimeType },
    body: fileBuffer,
  });
  if (response.status !== 200) throw new Error(`Upload failed: ${response.status}`);
  console.log('File uploaded successfully');
}

// Step 1c: Check media status
async function getMediaStatus(mediaId: string) {
  const response = await fetch(`${BASE}/media/${mediaId}`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  console.log('Media state:', data.state); // PENDING, READY, REJECTED
  return data;
}

Step 2: Schedule Post with Media

async function scheduleWithMedia(config: {
  profileIds: string[];
  text: string;
  mediaIds: string[];
  scheduledAt: Date;
}) {
  const response = await fetch(`${BASE}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: config.text,
      socialProfileIds: config.profileIds,
      scheduledSendTime: config.scheduledAt.toISOString(),
      mediaUrls: config.mediaIds.map(id => ({ id })),
      emailNotification: false,
    }),
  });

  const result = await response.json();
  for (const msg of result.data) {
    console.log(`Message ${msg.id}: ${msg.state} → ${msg.scheduledSendTime}`);
  }
  return result;
}

                

              

                
                  
                  
                  hootsuite-core-workflow-b
                  SKILL.md
                  View full skill →
                
                
                  'Execute Hootsuite secondary workflow: Core Workflow B.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Hootsuite Analytics & URL Shortening
Overview
Retrieve social media analytics and use Ow.ly URL shortening via the Hootsuite API. Track post performance, engagement metrics, and click-through rates.
Prerequisites

Completed hootsuite-install-auth setup
Published posts with engagement data

Instructions
Step 1: Get Organization Analytics

import 'dotenv/config';
const TOKEN = process.env.HOOTSUITE_ACCESS_TOKEN!;
const BASE = 'https://platform.hootsuite.com/v1';

async function getOrganization() {
  const response = await fetch(`${BASE}/me/organizations`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  return data[0]; // Primary organization
}

Step 2: Shorten URLs with Ow.ly

async function shortenUrl(fullUrl: string) {
  const response = await fetch(`${BASE}/shorteners/owly`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: fullUrl }),
  });
  const { data } = await response.json();
  console.log(`${fullUrl} → ${data.shortUrl}`);
  return data;
}

// Shorten multiple URLs
async function shortenBatch(urls: string[]) {
  return Promise.all(urls.map(url => shortenUrl(url)));
}

Step 3: Retrieve Message Analytics

async function getMessageAnalytics(messageId: string) {
  const response = await fetch(`${BASE}/messages/${messageId}`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  console.log(`Message: ${data.text?.substring(0, 50)}...`);
  console.log(`State: ${data.state}`);
  console.log(`Sent: ${data.sentAt}`);
  return data;
}

// List sent messages and their performance
async function getSentMessages(profileId: string) {
  const response = await fetch(
    `${BASE}/messages?socialProfileIds=${profileId}&state=SENT&limit=20`,
    { headers: { 'Authorization': `Bearer ${TOKEN}` } },
  );
  const { data } = await response.json();
  for (const msg of data) {
    console.log(`[${msg.sentAt}] ${msg.text?.substring(0, 60)}`);
  }
  return data;
}

Step 4: Social Profile Metrics

async function getProfileDetails(profileId: string) {
  const response = await fetch(`${BASE}/socialProfiles/${profileId}`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  console.log(`Profile: @${data.socialNetworkUsername}`);
  console.log(`Network: ${data.type}`);
  console.log(`ID: ${data.id}`);
  return data;
}

Output

Organization analytics retrieved
URLs shortened via Ow.ly
                
              

                
                  
                  
                  hootsuite-cost-tuning
                  SKILL.md
                  View full skill →
                
                
                  'Optimize Hootsuite costs through tier selection, sampling, and usage.
                  
                      ReadGrep
                    
                
                
                  Hootsuite Cost Tuning
Hootsuite Plans

Plan
Price
Profiles
Users
API Access


Professional
$99/mo
10
1
REST API


Team
$249/mo
20
3
REST API


Business
$739/mo
35
5+
Full API + webhooks


Enterprise
Custom
50+
Unlimited
Full API + SCIM


Cost Optimization
Step 1: Minimize API Calls

// Cache profile lists (don't refetch every request)
// Batch schedule posts (one session, many messages)
// Use bulk endpoints where available

Step 2: Right-Size Your Plan

// Audit actual profile usage
async function auditUsage() {
  const profiles = await getCachedProfiles();
  console.log(`Active profiles: ${profiles.length}`);
  console.log(`Networks: ${[...new Set(profiles.map(p => p.type))].join(', ')}`);
  // If using < 10 profiles, Professional plan may suffice
}

Step 3: Track API Usage

let apiCallCount = 0;
const originalFetch = fetch;
globalThis.fetch = async (...args) => {
  if (String(args[0]).includes('hootsuite.com')) apiCallCount++;
  return originalFetch(...args);
};
// Log periodically
setInterval(() => { console.log(`Hootsuite API calls: ${apiCallCount}`); apiCallCount = 0; }, 3600000);

Resources

Hootsuite Pricing

Next Steps
For architecture, see hootsuite-reference-architecture.
                
              

                
                  
                  
                  hootsuite-debug-bundle
                  SKILL.md
                  View full skill →
                
                
                  'Collect Hootsuite debug evidence for support tickets and troubleshooting.
                  
                      ReadBash(grep:*)Bash(curl:*)Bash(tar:*)Grep
                    
                
                
                  Hootsuite Debug Bundle
Overview
Collect Hootsuite API connectivity status, social profile health, scheduled post state, and OAuth token validity into a single diagnostic archive. This bundle helps troubleshoot failed post scheduling, disconnected social accounts, media upload errors, and API authentication problems.
Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-hootsuite-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Hootsuite Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "HOOTSUITE_API_KEY: ${HOOTSUITE_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"
echo "HOOTSUITE_ACCESS_TOKEN: ${HOOTSUITE_ACCESS_TOKEN:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity — user profile endpoint
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  https://platform.hootsuite.com/v1/me 2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# User profile and social profiles
curl -s -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  https://platform.hootsuite.com/v1/me > "$BUNDLE/me.json" 2>&1 || true
curl -s -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  https://platform.hootsuite.com/v1/socialProfiles > "$BUNDLE/profiles.json" 2>&1 || true

# Scheduled posts and rate limit headers
curl -s -D "$BUNDLE/rate-headers.txt" -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  "https://platform.hootsuite.com/v1/messages?limit=10&state=SCHEDULED" > "$BUNDLE/scheduled-posts.json" 2>&1 || true

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-hootsuite-*.tar.gz
cat debug-hootsuite-*/summary.txt                  # Auth + connectivity
jq '.data[] | {id, type, socialNetworkId}' debug-hootsuite-*/profiles.json  # Connected accounts
jq '.data[] | {id, state, scheduledSendTime}' debug-hootsuite-*/scheduled-posts.json
grep -i "ratelimit\|retry" debug-hootsuite-*/rate-headers.txt

Common Issues

Symptom
Check in Bundle
Fix


API returns 401
summary.txt shows HTTP 401
OAuth token expired; re-authorize via Hootsuite app OAuth flow


Social profile disconnected
profiles.json shows missing or error-state profile
Re-connect the social account in Hoots
                
              
                
                  
                  
                  hootsuite-deploy-integration
                  SKILL.md
                  View full skill →
                
                
                  'Deploy Hootsuite integrations to Vercel, Fly.
                  
                      ReadWriteEditBash(vercel:*)Bash(fly:*)Bash(gcloud:*)
                    
                
                
                  Hootsuite Deploy Integration
Overview
Deploy Hootsuite social media management backends. Key consideration: OAuth refresh tokens must persist across deployments — use a database or key-value store, not environment variables.
Instructions
Step 1: Vercel Deployment

// api/schedule.ts — Vercel serverless
import type { VercelRequest, VercelResponse } from '@vercel/node';

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  // Get token from persistent store (not env var — tokens rotate)
  const token = await getStoredToken();

  const response = await fetch('https://platform.hootsuite.com/v1/messages', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(req.body),
  });

  const result = await response.json();
  res.json(result);
}


vercel env add HOOTSUITE_CLIENT_ID production
vercel env add HOOTSUITE_CLIENT_SECRET production
vercel --prod

Step 2: Token Persistence

// Use Redis, database, or KV store for token persistence
// Tokens refresh every ~1 hour and refresh_token changes each time
import { kv } from '@vercel/kv';

async function getStoredToken(): Promise<string> {
  let token = await kv.get('hootsuite:access_token');
  const expiresAt = await kv.get('hootsuite:expires_at') as number;

  if (!token || Date.now() > expiresAt - 60000) {
    const refreshToken = await kv.get('hootsuite:refresh_token') as string;
    const newTokens = await refreshHootsuiteToken(refreshToken);
    await kv.set('hootsuite:access_token', newTokens.access_token);
    await kv.set('hootsuite:refresh_token', newTokens.refresh_token);
    await kv.set('hootsuite:expires_at', Date.now() + newTokens.expires_in * 1000);
    token = newTokens.access_token;
  }
  return token as string;
}

Resources

Vercel KV
Hootsuite OAuth

Next Steps
For webhooks, see hootsuite-webhooks-events.
                
              

                
                  
                  
                  hootsuite-hello-world
                  SKILL.md
                  View full skill →
                
                
                  'Create a minimal working Hootsuite example.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)
                    
                
                
                  Hootsuite Hello World
Overview
List your social media profiles and schedule a post using the Hootsuite REST API. The API base URL is https://platform.hootsuite.com/v1/.
Prerequisites

Completed hootsuite-install-auth setup
Valid access token
At least one social profile connected in Hootsuite

Instructions
Step 1: List Social Profiles

// hello-hootsuite.ts
import 'dotenv/config';

const TOKEN = process.env.HOOTSUITE_ACCESS_TOKEN!;
const BASE = 'https://platform.hootsuite.com/v1';

async function listProfiles() {
  const response = await fetch(`${BASE}/socialProfiles`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();

  for (const profile of data) {
    console.log(`${profile.type}: @${profile.socialNetworkUsername} (ID: ${profile.id})`);
  }
  return data;
}

listProfiles().catch(console.error);

Step 2: Schedule a Post

async function schedulePost(socialProfileId: string, text: string, scheduledAt: Date) {
  const response = await fetch(`${BASE}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text,
      socialProfileIds: [socialProfileId],
      scheduledSendTime: scheduledAt.toISOString(),
      emailNotification: false,
    }),
  });

  const result = await response.json();
  console.log('Scheduled message ID:', result.data[0]?.id);
  console.log('State:', result.data[0]?.state);
  console.log('Scheduled for:', result.data[0]?.scheduledSendTime);
  return result;
}

// Schedule a post 1 hour from now
const profiles = await listProfiles();
if (profiles.length > 0) {
  const oneHourLater = new Date(Date.now() + 3600000);
  await schedulePost(profiles[0].id, 'Hello from the Hootsuite API!', oneHourLater);
}

Step 3: List Scheduled Messages

async function listMessages() {
  const response = await fetch(`${BASE}/messages?state=SCHEDULED&limit=10`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  for (const msg of data) {
    console.log(`[${msg.state}] ${msg.text?.substring(0, 60)}... → ${msg.scheduledSendTime}`);
  }
}

Step 4: curl Quick Test

# List profiles
curl -s -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/socialProfiles | python3 -m json.tool

# Get current user
curl -s -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/me | python3 -m json.tool

Output

Listed social media 
                
              

                
                  
                  
                  hootsuite-install-auth
                  SKILL.md
                  View full skill →
                
                
                  'Install and configure Hootsuite SDK/CLI authentication.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Hootsuite Install & Auth
Overview
Configure Hootsuite REST API OAuth 2.0 authentication. Hootsuite uses OAuth 2.0 with Bearer tokens. You register an app in the Hootsuite Developer Portal, get client credentials, and exchange authorization codes for access tokens.
Prerequisites

Hootsuite account (Business plan or higher for API access)
Registered app at https://developer.hootsuite.com
Client ID and Client Secret from your app

Instructions
Step 1: Register Your App

Go to https://developer.hootsuite.com
Create a new app
Note your Client ID and Client Secret
Set redirect URI to https://your-app.com/callback

Step 2: Configure Environment

# .env (NEVER commit)
HOOTSUITE_CLIENT_ID=your_client_id
HOOTSUITE_CLIENT_SECRET=your_client_secret
HOOTSUITE_REDIRECT_URI=https://your-app.com/callback
HOOTSUITE_ACCESS_TOKEN=  # Populated after OAuth flow

# .gitignore
.env
.env.local

Step 3: OAuth 2.0 Authorization Flow

// auth.ts — OAuth 2.0 authorization code flow
import 'dotenv/config';

const { HOOTSUITE_CLIENT_ID, HOOTSUITE_CLIENT_SECRET, HOOTSUITE_REDIRECT_URI } = process.env;

// Step 1: Redirect user to authorize
function getAuthUrl(): string {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: HOOTSUITE_CLIENT_ID!,
    redirect_uri: HOOTSUITE_REDIRECT_URI!,
    scope: 'offline',
  });
  return `https://platform.hootsuite.com/oauth2/auth?${params}`;
}

// Step 2: Exchange authorization code for tokens
async function exchangeCode(code: string) {
  const response = await fetch('https://platform.hootsuite.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${HOOTSUITE_CLIENT_ID}:${HOOTSUITE_CLIENT_SECRET}`).toString('base64')}`,
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: HOOTSUITE_REDIRECT_URI!,
    }),
  });

  const tokens = await response.json();
  console.log('Access Token:', tokens.access_token);
  console.log('Refresh Token:', tokens.refresh_token);
  console.log('Expires In:', tokens.expires_in, 'seconds');
  return tokens;
}

// Step 3: Refresh expired token
async function refreshToken(refreshToken: string) {
  const response = await fetch('https://platform.hootsuite.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${HOOTSUITE_CLIENT_ID}:${HOOTSUITE_CLIENT_SECRET}`).toString('base64')}`,
    },
    body: new URLSearchParams({
      grant_type

                

              

                
                  
                  
                  hootsuite-local-dev-loop
                  SKILL.md
                  View full skill →
                
                
                  'Configure Hootsuite local development with hot reload and testing.
                  
                      ReadWriteEditBash(npm:*)Bash(pnpm:*)Grep
                    
                
                
                  Hootsuite Local Dev Loop
Overview
Set up a development workflow for Hootsuite API integrations with mocked API responses, token management, and testing.
Instructions
Step 1: Project Structure

hootsuite-integration/
├── src/
│   ├── hootsuite/
│   │   ├── client.ts       # API client with token refresh
│   │   ├── auth.ts         # OAuth 2.0 flow
│   │   ├── publishing.ts   # Message scheduling
│   │   └── analytics.ts    # Metrics retrieval
│   └── index.ts
├── tests/
│   ├── fixtures/           # Mock API responses
│   │   ├── profiles.json
│   │   └── messages.json
│   └── publishing.test.ts
├── .env.local
└── package.json

Step 2: API Client with Auto Token Refresh

// src/hootsuite/client.ts
import 'dotenv/config';

class HootsuiteClient {
  private accessToken: string;
  private refreshToken: string;
  private expiresAt: number;
  private base = 'https://platform.hootsuite.com/v1';

  constructor() {
    this.accessToken = process.env.HOOTSUITE_ACCESS_TOKEN!;
    this.refreshToken = process.env.HOOTSUITE_REFRESH_TOKEN!;
    this.expiresAt = Date.now() + 3600000;
  }

  async request(path: string, options: RequestInit = {}) {
    if (Date.now() > this.expiresAt - 60000) await this.refresh();
    const response = await fetch(`${this.base}${path}`, {
      ...options,
      headers: { 'Authorization': `Bearer ${this.accessToken}`, 'Content-Type': 'application/json', ...options.headers },
    });
    if (!response.ok) throw new Error(`Hootsuite API ${response.status}: ${await response.text()}`);
    return response.json();
  }

  private async refresh() {
    const res = await fetch('https://platform.hootsuite.com/oauth2/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Authorization': `Basic ${Buffer.from(`${process.env.HOOTSUITE_CLIENT_ID}:${process.env.HOOTSUITE_CLIENT_SECRET}`).toString('base64')}` },
      body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: this.refreshToken }),
    });
    const tokens = await res.json();
    this.accessToken = tokens.access_token;
    this.refreshToken = tokens.refresh_token;
    this.expiresAt = Date.now() + tokens.expires_in * 1000;
  }
}

export const hootsuite = new HootsuiteClient();

Step 3: Mocked Tests

// tests/publishing.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';

const mockFetch = vi.fn();
vi.stubGlobal('fetch', mockFetch);

describe('Hootsuite Publishing', () => {
  beforeEach(() => vi.clearAllMocks());

  it('should schedule a message', async () => {
    mockFetch.mockResolvedValueOnce({
      ok: true,
      json: async () => ({ data: [{ id: 'msg_123', state: 'SCHEDULED' }

                

              

                
                  
                  
                  hootsuite-performance-tuning
                  SKILL.md
                  View full skill →
                
                
                  'Optimize Hootsuite API performance with caching, batching, and connection.
                  
                      ReadWriteEdit
                    
                
                
                  Hootsuite Performance Tuning
Instructions
Step 1: Cache Social Profiles

import { LRUCache } from 'lru-cache';

const profileCache = new LRUCache<string, any>({ max: 100, ttl: 3600000 });

async function getCachedProfiles(): Promise<any[]> {
  const cached = profileCache.get('profiles');
  if (cached) return cached;

  const response = await fetch('https://platform.hootsuite.com/v1/socialProfiles', {
    headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
  });
  const { data } = await response.json();
  profileCache.set('profiles', data);
  return data;
}

Step 2: Batch Message Scheduling

import PQueue from 'p-queue';

const scheduleQueue = new PQueue({ concurrency: 2, interval: 1000, intervalCap: 2 });

async function batchSchedule(posts: Array<{ text: string; profileId: string; time: Date }>) {
  const results = await Promise.allSettled(
    posts.map(post =>
      scheduleQueue.add(() =>
        fetch('https://platform.hootsuite.com/v1/messages', {
          method: 'POST',
          headers: { 'Authorization': `Bearer ${process.env.HOOTSUITE_ACCESS_TOKEN}`, 'Content-Type': 'application/json' },
          body: JSON.stringify({ text: post.text, socialProfileIds: [post.profileId], scheduledSendTime: post.time.toISOString() }),
        }).then(r => r.json())
      )
    )
  );
  const succeeded = results.filter(r => r.status === 'fulfilled').length;
  console.log(`Scheduled ${succeeded}/${posts.length} posts`);
}

Step 3: Connection Reuse

import { Agent } from 'https';
const agent = new Agent({ keepAlive: true, maxSockets: 5 });
// Pass agent to fetch/axios for connection reuse to platform.hootsuite.com

Resources

Hootsuite API

Next Steps
For cost optimization, see hootsuite-cost-tuning.
                
              

                
                  
                  
                  hootsuite-prod-checklist
                  SKILL.md
                  View full skill →
                
                
                  'Execute Hootsuite production deployment checklist and rollback procedures.
                  
                      ReadBash(curl:*)Grep
                    
                
                
                  Hootsuite Production Checklist
Overview
Hootsuite manages social media publishing, scheduling, and analytics across multiple platforms (Twitter/X, LinkedIn, Facebook, Instagram). A production integration automates post scheduling, monitors engagement, and syncs analytics. Failures mean posts go out at wrong times, media uploads get rejected, or social profile disconnections go undetected, creating gaps in your publishing calendar.
Authentication & Secrets

[ ] HOOTSUITEAPIKEY and OAuth client secret in secrets manager
[ ] OAuth app reviewed and approved in Hootsuite developer portal
[ ] Token refresh logic tested with deliberately expired tokens
[ ] Separate OAuth app for production vs development
[ ] Key rotation schedule documented (before annual app review)

API Integration

[ ] Production base URL configured (https://platform.hootsuite.com/v1)
[ ] Rate limit handling with exponential backoff
[ ] Message scheduling tested with all connected social profiles
[ ] Media upload validated (images, video, carousel per platform)
[ ] Character limits enforced per platform (X: 280, LinkedIn: 3000, FB: 63K)
[ ] Timezone handling verified for scheduled posts across regions
[ ] Social profile health check detects disconnected accounts

Error Handling & Resilience

[ ] Circuit breaker configured for Hootsuite API outages
[ ] Retry with backoff for 429/5xx responses
[ ] REJECTED media states handled with user notification
[ ] Social profile disconnection detected and alerted within 1 hour
[ ] Scheduled post failure queued for retry (not silently dropped)
[ ] Content moderation filter on automated posts (banned words, compliance)

Monitoring & Alerting

[ ] API latency tracked per endpoint (publish, schedule, analytics)
[ ] Error rate alerts set (threshold: >3% over 10 minutes)
[ ] Token refresh failures trigger immediate notification
[ ] Failed post scheduling reported with platform and error detail
[ ] Engagement analytics sync monitored for completeness

Validation Script

async function checkHootsuiteReadiness(): Promise<void> {
  const checks: { name: string; pass: boolean; detail: string }[] = [];
  // API connectivity
  try {
    const res = await fetch('https://platform.hootsuite.com/v1/me', {
      headers: { Authorization: `Bearer ${process.env.HOOTSUITE_API_KEY}` },
    });
    checks.push({ name: 'Hootsuite API', pass: res.ok, detail: res.ok ? 'Connected' : `HTTP ${res.status}` });
  } catch (e: any) { checks.push({ name: 'Hootsuite API', pass: false, detail: e.message }); }
  // Credentials present
  checks.push({ name: 'API Key S

                

              

                
                  
                  
                  hootsuite-rate-limits
                  SKILL.md
                  View full skill →
                
                
                  'Implement Hootsuite rate limiting, backoff, and idempotency patterns.
                  
                      ReadWriteEdit
                    
                
                
                  Hootsuite Rate Limits
Overview
Handle Hootsuite API rate limits. The API returns 429 Too Many Requests with Retry-After headers when limits are exceeded.
Rate Limits

Endpoint
Limit
Window


General API
Varies by plan
Per minute


Message scheduling
~100/hour
Per hour


Media upload
~50/hour
Per hour


Token refresh
~10/hour
Per hour


Instructions
Step 1: Respect Retry-After Header

async function rateLimitedRequest(url: string, options: RequestInit = {}) {
  const response = await fetch(url, {
    ...options,
    headers: { 'Authorization': `Bearer ${process.env.HOOTSUITE_ACCESS_TOKEN}`, ...options.headers },
  });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    console.log(`Rate limited. Retrying in ${retryAfter}s`);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return rateLimitedRequest(url, options); // Retry
  }

  return response;
}

Step 2: Queue-Based Scheduling

import PQueue from 'p-queue';

const hootsuiteQueue = new PQueue({
  concurrency: 1,
  interval: 1000,
  intervalCap: 2, // 2 requests per second
});

async function queuedSchedule(profileId: string, text: string, time: Date) {
  return hootsuiteQueue.add(() =>
    fetch('https://platform.hootsuite.com/v1/messages', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${process.env.HOOTSUITE_ACCESS_TOKEN}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text, socialProfileIds: [profileId], scheduledSendTime: time.toISOString() }),
    })
  );
}

Resources

Hootsuite API FAQ

Next Steps
For security, see hootsuite-security-basics.
                
              

                
                  
                  
                  hootsuite-reference-architecture
                  SKILL.md
                  View full skill →
                
                
                  'Implement Hootsuite reference architecture with best-practice project.
                  
                      ReadGrep
                    
                
                
                  Hootsuite Reference Architecture
Architecture

┌──────────────────────────────────────┐
│         Your Application              │
├──────────────────────────────────────┤
│  Content Manager → Scheduler → Publisher │
├──────────────────────────────────────┤
│      Hootsuite API Client             │
│  (OAuth, Token Refresh, Rate Limit)   │
├──────────────────────────────────────┤
│      Hootsuite REST API v1            │
│  platform.hootsuite.com/v1/           │
└──────────────────────────────────────┘

Project Structure

hootsuite-integration/
├── src/
│   ├── hootsuite/
│   │   ├── client.ts        # API client with token management
│   │   ├── auth.ts          # OAuth 2.0 flow
│   │   ├── publishing.ts    # Message scheduling + media
│   │   ├── analytics.ts     # Metrics + URL shortening
│   │   └── types.ts         # TypeScript interfaces
│   ├── services/
│   │   ├── scheduler.ts     # Content calendar logic
│   │   ├── content.ts       # Post formatting per platform
│   │   └── media.ts         # Media processing + upload
│   ├── api/
│   │   └── schedule.ts      # REST endpoint
│   └── store/
│       └── tokens.ts        # Persistent token storage
├── tests/
│   ├── unit/
│   └── fixtures/
└── .env.example

Key Decisions

Decision
Recommendation
Why


Token storage
Database/KV, not env vars
Refresh tokens change each use


Scheduling
Queue-based, not direct API
Rate limit compliance


Media upload
Pre-process images
Reduce REJECTED media states


Multi-profile
Batch schedule per profile
Separate errors per profile


Resources

Hootsuite Developer Platform
API Overview

Next Steps
Start with hootsuite-install-auth to set up OAuth.
                
              

                
                  
                  
                  hootsuite-sdk-patterns
                  SKILL.md
                  View full skill →
                
                
                  'Apply production-ready Hootsuite SDK patterns for TypeScript and Python.
                  
                      ReadWriteEdit
                    
                
                
                  Hootsuite SDK Patterns
Overview
Production patterns for Hootsuite REST API: typed client, token management, scheduling helpers, and Python integration.
Instructions
Step 1: Typed API Client

// src/hootsuite/types.ts
interface SocialProfile {
  id: string;
  type: 'TWITTER' | 'FACEBOOK' | 'INSTAGRAM' | 'LINKEDIN' | 'PINTEREST' | 'YOUTUBE' | 'TIKTOK';
  socialNetworkUsername: string;
  socialNetworkId: string;
}

interface ScheduledMessage {
  id: string;
  text: string;
  state: 'SCHEDULED' | 'SENT' | 'FAILED' | 'REJECTED';
  socialProfileIds: string[];
  scheduledSendTime: string;
  sentAt?: string;
  mediaUrls?: Array<{ id: string }>;
}

interface HootsuiteResponse<T> {
  data: T;
}

Step 2: Scheduling Helper with Timezone

function scheduleForTimezone(
  hour: number,
  minute: number,
  timezone: string,
  daysFromNow = 0
): Date {
  const date = new Date();
  date.setDate(date.getDate() + daysFromNow);
  const dateStr = date.toISOString().split('T')[0];
  const timeStr = `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}:00`;
  return new Date(`${dateStr}T${timeStr}`);
}

// Schedule posts at optimal times per platform
const OPTIMAL_TIMES = {
  TWITTER: { hour: 9, minute: 0 },
  INSTAGRAM: { hour: 11, minute: 0 },
  LINKEDIN: { hour: 7, minute: 30 },
  FACEBOOK: { hour: 13, minute: 0 },
};

Step 3: Python Client

# hootsuite/client.py
import os, requests, time
from dotenv import load_dotenv

load_dotenv()

class HootsuiteClient:
    BASE = 'https://platform.hootsuite.com/v1'

    def __init__(self):
        self.token = os.environ['HOOTSUITE_ACCESS_TOKEN']
        self.headers = {'Authorization': f'Bearer {self.token}', 'Content-Type': 'application/json'}

    def get_profiles(self):
        r = requests.get(f'{self.BASE}/socialProfiles', headers=self.headers)
        r.raise_for_status()
        return r.json()['data']

    def schedule_message(self, profile_ids, text, scheduled_time):
        r = requests.post(f'{self.BASE}/messages', headers=self.headers, json={
            'text': text,
            'socialProfileIds': profile_ids,
            'scheduledSendTime': scheduled_time.isoformat(),
        })
        r.raise_for_status()
        return r.json()['data']

Step 4: Cross-Platform Post Formatter

function formatPost(text: string, platform: string): string {
  const limits: Record<string, number> = {
    TWITTER: 280, FACEBOOK: 63206, INSTAGRAM: 2200, LINKEDIN: 3000, TIKTOK: 2200,
  };
  const limit = limits[platform] || 2200;
  return text.leng

                

              

                
                  
                  
                  hootsuite-security-basics
                  SKILL.md
                  View full skill →
                
                
                  'Apply Hootsuite security best practices for secrets and access control.
                  
                      ReadWriteGrep
                    
                
                
                  Hootsuite Security Basics
Credential Inventory

Credential
Scope
Rotation


Client ID
App-level
Never (app identifier)


Client Secret
App-level
Rotate if compromised


Access Token
User session
Auto-expires (~1 hour)


Refresh Token
User session
Rotate on each refresh


Instructions
Step 1: Secure Token Storage

# .env (never commit)
HOOTSUITE_CLIENT_ID=app_client_id
HOOTSUITE_CLIENT_SECRET=app_secret
HOOTSUITE_ACCESS_TOKEN=current_token
HOOTSUITE_REFRESH_TOKEN=refresh_token

Step 2: Token Refresh Security

// Always use HTTPS for token exchange
// Store refresh tokens encrypted at rest
// Rotate refresh tokens on each use (Hootsuite returns new ones)
async function secureRefresh(refreshToken: string) {
  const res = await fetch('https://platform.hootsuite.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${process.env.HOOTSUITE_CLIENT_ID}:${process.env.HOOTSUITE_CLIENT_SECRET}`).toString('base64')}`,
    },
    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken }),
  });
  const tokens = await res.json();
  // Store new refresh_token, discard old one
  return tokens;
}

Step 3: Security Checklist

[ ] Client secret in secrets vault, never in code
[ ] Access tokens never logged or exposed
[ ] Refresh tokens stored encrypted
[ ] HTTPS for all OAuth requests
[ ] Pre-commit hook blocks HOOTSUITE_ credential leaks
[ ] Separate OAuth apps for dev/staging/prod

Resources

Hootsuite OAuth 2.0

Next Steps
For production, see hootsuite-prod-checklist.
                
              

                
                  
                  
                  hootsuite-upgrade-migration
                  SKILL.md
                  View full skill →
                
                
                  'Analyze, plan, and execute Hootsuite SDK upgrades with breaking change.
                  
                      ReadWriteEditBash(npm:*)Bash(git:*)
                    
                
                
                  Hootsuite Upgrade & Migration
Overview
Hootsuite REST API is versioned at /v1/. Monitor the developer changelog for deprecations and new endpoints.
Instructions
Step 1: Check Current API Usage

# List all Hootsuite API calls in your codebase
grep -r "platform.hootsuite.com" src/ --include="*.ts" --include="*.py"

Step 2: Migration Patterns

// If Hootsuite introduces v2 endpoints:
// BEFORE
const response = await fetch('https://platform.hootsuite.com/v1/messages', ...);
// AFTER
const API_VERSION = process.env.HOOTSUITE_API_VERSION || 'v1';
const response = await fetch(`https://platform.hootsuite.com/${API_VERSION}/messages`, ...);

Step 3: Social Network Changes
When Hootsuite adds/removes social network support:

const SUPPORTED_NETWORKS = ['TWITTER', 'FACEBOOK', 'INSTAGRAM', 'LINKEDIN', 'PINTEREST', 'YOUTUBE', 'TIKTOK'] as const;
type SocialNetwork = typeof SUPPORTED_NETWORKS[number];

Resources

Hootsuite Developer Changelog
API Guides

Next Steps
For CI, see hootsuite-ci-integration.
                
              

                
                  
                  
                  hootsuite-webhooks-events
                  SKILL.md
                  View full skill →
                
                
                  'Implement Hootsuite webhook signature validation and event handling.
                  
                      ReadWriteEditBash(curl:*)
                    
                
                
                  Hootsuite Webhooks & Events
Overview
Hootsuite provides webhook notifications for social stream events when building Hootsuite App Directory integrations. For API-only integrations, you poll for message state changes or implement your own scheduling system with callbacks.
Instructions
Step 1: Poll for Message Status Changes

// Since Hootsuite REST API doesn't push webhooks for message status,
// poll for changes to scheduled messages
async function pollMessageStatus(messageId: string, intervalMs = 30000) {
  const check = async () => {
    const response = await fetch(`https://platform.hootsuite.com/v1/messages/${messageId}`, {
      headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
    });
    const { data } = await response.json();

    if (data.state === 'SENT') {
      console.log(`Message ${messageId} sent at ${data.sentAt}`);
      return data;
    } else if (data.state === 'FAILED' || data.state === 'REJECTED') {
      console.error(`Message ${messageId} failed: ${data.state}`);
      return data;
    }

    console.log(`Message ${messageId}: ${data.state}, checking again...`);
    await new Promise(r => setTimeout(r, intervalMs));
    return check();
  };

  return check();
}

Step 2: Build Custom Scheduling Webhook

// Your own webhook system to track scheduled post status
import express from 'express';

const app = express();
app.use(express.json());

// Cron job checks scheduled posts and fires webhooks
async function checkScheduledPosts() {
  const response = await fetch('https://platform.hootsuite.com/v1/messages?state=SENT&limit=50', {
    headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
  });
  const { data } = await response.json();

  for (const msg of data) {
    // Notify your systems about sent posts
    await fetch(process.env.INTERNAL_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ event: 'post.sent', messageId: msg.id, sentAt: msg.sentAt, text: msg.text }),
    });
  }
}

Step 3: Hootsuite App Directory Webhooks
For apps listed in the Hootsuite App Directory, you receive stream events:

// Webhook handler for Hootsuite App Directory integration
app.post('/webhooks/hootsuite', async (req, res) => {
  const { type, data } = req.body;
  switch (type) {
    case 'message.sent': console.log('Post sent:', data); break;
    case 'message.failed': console.error('Post failed:', data); break;
    case 'stream.message': console.log('New social message:', data); break;
  }
  res.status(200).json({ received: true });
});

Resources


  Ready to use hootsuite-pack?
  
    
    
  




      
      
          Related Plugins
          
            
                supabase-pack
                Complete Supabase integration skill pack with 30 skills covering authentication, database, storage, realtime, edge functions, and production operations. Flagship+ tier vendor pack.
              
                vercel-pack
                Complete Vercel integration skill pack with 30 skills covering deployments, edge functions, preview environments, performance optimization, and production operations. Flagship+ tier vendor pack.
              
                clay-pack
                Complete Clay integration skill pack with 30 skills covering data enrichment, waterfall workflows, AI agents, and GTM automation. Flagship+ tier vendor pack.
              
                cursor-pack
                Complete Cursor integration skill pack with 30 skills covering AI code editing, composer workflows, codebase indexing, and productivity features. Flagship+ tier vendor pack.
              
                exa-pack
                Complete Exa integration skill pack with 30 skills covering neural search, semantic retrieval, web search API, and AI-powered discovery. Flagship+ tier vendor pack.
              
                firecrawl-pack
                Complete Firecrawl integration skill pack with 30 skills covering web scraping, crawling, markdown conversion, and LLM-ready data extraction. Flagship+ tier vendor pack.
              
          
        

      
      
          Tags
          
            hootsuitesaassdkintegration
          
        
    
  

  

    

    
    
        
            
                Stay in the Loop
                
                    
                    
                    
                
                No spam. Unsubscribe anytime.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Hall of Fame
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
                Tons of Skills by Intent Solutions. Marine. Citadel Grad. 20 years ops → self-taught dev → AI architect.
                © 2026 Tons of Skills | Intent Solutions

Plan	Price	Profiles	Users	API Access
Professional	$99/mo	10	1	REST API
Team	$249/mo	20	3	REST API
Business	$739/mo	35	5+	Full API + webhooks
Enterprise	Custom	50+	Unlimited	Full API + SCIM