Description

PostPulse n8n Node

Official n8n integration for PostPulse — schedule and publish content to multiple social networks from your n8n workflows.

• Auth: OAuth2 (auto refresh)
• Core actions: Accounts → Media Upload → Schedule Post(s) (+ Telegram Chats lookup)
• Targets today: Instagram, TikTok, YouTube, Threads, LinkedIn, Telegram, X, Bluesky
• Use cases: One-click multi-destination posting, media pipeline, automated campaigns

Table of contents

• Prerequisites
• Install
• Authenticate
• Quick start
• Operations
• Data model
• Platform settings
• Media & text validations
• Rate limits & API keys
• Webhooks
• Examples
• FAQ
• Support
• Versioning & License

Prerequisites

1. Sign up at https://post-pulse.com/login
2. Connect your social accounts in the web app: https://post-pulse.com/app/accounts
3. Create OAuth client: Visit https://developers.post-pulse.com and sign in using the email associated with your PostPulse account. Create a new OAuth client to obtain client_id and client_secret.
4. (Telegram only) Add the official PostPulse bot to your channels you plan to post to.

Use the same email in n8n OAuth as your PostPulse account email.

Install

• From npm (recommended):

  npm install @postpulse/n8n-nodes-postpulse
  

• Restart n8n and enable the node in Settings → Community Nodes if required.

Authenticate

Create Credentials → PostPulse OAuth2 API in n8n:

• OAuth Redirect URL: Use this URL when creating your OAuth client at https://developers.post-pulse.com
• Client ID / Secret: Obtained from the developer portal at https://developers.post-pulse.com

This node extends n8n’s oAuth2Api so tokens are refreshed automatically.

Quick start

1. Accounts → Get Many
   Retrieve your connected accounts. Save the id of targets you’ll post to.
2. Telegram → Get Connected Chats (only if posting to Telegram)
   Input: id from step 1 (platform must be TELEGRAM). Output contains id per channel/chat.
3. Media → Upload (for any media)
   Upload files (even if you have public URLs). Some platforms (e.g., TikTok/Instagram) require media hosted on post-pulse.com. Save the returned path.
4. Posts → Schedule
   Build one PostSchedule with one or more Publications.
   • Set scheduledTime (past/now = queue immediately)
   • For now, prefer isDraft: false (update APIs will come later).

Operations

Accounts: Get Many

• Output: Array of accounts: { id, platform, handle, ... }
• Use: Pick id for each destination.

Telegram: Get Connected Chats

• Input: { id } (must be a Telegram account)
• Output: Array: { id, title } — pass chatId into Telegram posts.

Media: Upload

• Input: File or Public URL
• Output:
  • File upload: { path } — use in attachmentPaths of posts
  • URL import: { id, state } — use id with "Get Upload Status" to monitor progress
• Upload Sources:
  • From File: Upload binary file data (existing functionality)
  • From Public URL: Import media from a public URL (new functionality)

Media: Get Upload Status

• Input: { importId } (from URL import response)
• Output: Complete import status including id, state, sourceUrl, bytesDownloaded, totalBytes, detectedMime, s3Key, errorCode, errorMessage
• Use: Monitor the progress of URL-based media imports

Posts: Schedule

• Input: PostSchedule (see Data model)
• Behavior: Schedules one or multiple publications for the same time.
• Recommended: isDraft: false (until update endpoints are exposed in node).

Data model

PostSchedule

{
  "scheduledTime": "2025-08-17T14:03:00",
  "isDraft": false,
  "publications": [ /* Publication[] */ ]
}

Publication

Represents “one publication in user’s mind” that may map to one or many platform posts.

{
  "socialMediaAccountId": 442,
  "posts": [ /* Post[] */ ],
  "platformSettings": { /* see below */ }
}

• One publication → multiple posts is useful when:
  • Telegram account posts to several channels (one post per channel)
  • Telegram account posts with large text or more than 10 media (one post per message that will be published)
  • Instagram storyline (multiple stories in one conceptual set)

Post

{
  "attachmentPaths": [
    "6354d8d2-e0f1-702b-af6c-62e28e377ec7/c6c2b826-8aca-4eae-8549-515325012ab4.jpeg"
  ],
  "content": "Your caption or description",
  "chatId": "1234567890"   // Telegram only
  /* "thumbnailPath": "..." — coming soon */
}

Note: For YouTube/TikTok, content is used as description (titles are set in platformSettings).

Platform settings

Each Publication must include platformSettings with a required discriminator: type.

{ "type": "INSTAGRAM", "publicationType": "REELS" }

Supported shapes:

Instagram

{
  "type": "INSTAGRAM",
  "publicationType": "FEED" | "REELS" | "STORY"
}

LinkedIn

{
  "type": "LINKEDIN",
  "visibility": "PUBLIC" | "CONNECTIONS" | "GROUP"
}

Threads

{
  "type": "THREADS",
  "topicTag": "your-topic-tag"
}

TikTok

{
  "type": "TIK_TOK",
  "title": "My video title",
  "privacyLevel": "PUBLIC_TO_EVERYONE" | "FOLLOWER_OF_CREATOR" | "MUTUAL_FOLLOW_FRIENDS" | "SELF_ONLY",
  "disableDuet": false,
  "disableComments": false,
  "disableStitch": false,
  "brandContent": false,
  "brandOrganic": true,
  "hasUsageConfirmation": true
}

YouTube

{
  "type": "YOUTUBE",
  "title": "My video title",
  "privacyStatus": "PUBLIC" | "UNLISTED" | "PRIVATE",
  "category": "FILM_ANIMATION" | "AUTOS_VEHICLES" | "MUSIC" | "PETS_ANIMALS" | "SPORTS" | "TRAVEL_EVENTS" | "GAMING" | "PEOPLE_BLOGS" | "COMEDY" | "ENTERTAINMENT" | "NEWS_POLITICS" | "HOWTO_STYLE" | "EDUCATION" | "SCIENCE_TECHNOLOGY"
}

Media & text validations

PostPulse Web enforces rich, platform-specific validations.
API clients must currently validate themselves. (Server-side validations for API clients are planned.)

Follow updates at https://post-pulse.com/releases — we’ll announce when API-side validations roll out.

Rate limits & API keys

• Authentication uses OAuth2; tokens are auto-refreshed by n8n.
• PostPulse runs on AWS API Gateway usage plans. Typical plans:
  • Standard: 20 RPS burst, 200 RPS steady, 50k req/month
  • Agency: higher limits on request

Webhooks

PostPulse supports webhooks for real-time notifications instead of polling for status updates. This is especially useful for tracking:

• Post publishing status — Get notified when scheduled posts are published or fail
• Media import progress — Receive updates on URL-based media imports without polling the "Get Upload Status" endpoint

Setting up webhooks

1. Register webhook endpoints at the Developer Portal
2. Configure event types you want to receive notifications for
3. Review webhook models and event types in the developer documentation

Benefits over polling

• Real-time updates — Instant notifications when events occur
• Reduced API calls — No need to repeatedly poll status endpoints
• Better reliability — Guaranteed delivery with retry mechanisms
• Lower latency — Immediate response to status changes

Learn more: Visit https://developers.post-pulse.com for complete webhook documentation, supported event types, and payload schemas.

Examples

Minimal single-destination post (Reel)

{
  "scheduledTime": "2025-08-17T14:03:00",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 442,
      "platformSettings": {
        "type": "INSTAGRAM",
        "publicationType": "REELS"
      },
      "posts": [
        {
          "attachmentPaths": [
            "6354d8d2-e0f1-702b-af6c-62e28e377ec7/c6c2b826-8aca-4eae-8549-515325012ab4.jpeg"
          ],
          "content": "New drop is live! #fashion"
        }
      ]
    }
  ]
}

Telegram to multiple channels in one publication

{
  "scheduledTime": "2025-08-17T14:03:00",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 501,   // Telegram account id
      "platformSettings": { "type": "TELEGRAM" },
      "posts": [
        { "chatId": "-100123", "content": "Hello Channel A", "attachmentPaths": ["u1/p1.jpg"] },
        { "chatId": "-100456", "content": "Hello Channel B", "attachmentPaths": ["u1/p1.jpg"] }
      ]
    }
  ]
}

TikTok with title & privacy

{
  "scheduledTime": "2025-08-17T14:03:00",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 777,
      "platformSettings": {
        "type": "TIK_TOK",
        "title": "Top 5 tips",
        "privacyLevel": "PUBLIC_TO_EVERYONE",
        "hasUsageConfirmation": true
      },
      "posts": [
        { "attachmentPaths": ["u1/v1.mp4"], "content": "Full guide in bio" }
      ]
    }
  ]
}

Media import from URL

{
  "url": "https://example.com/my-video.mp4",
  "filenameHint": "promotional-video.mp4"
}

Response:

{
  "id": 12345,
  "state": "QUEUED"
}

Check media import status

Input: importId: 12345

Response:

{
  "id": 12345,
  "state": "READY",
  "sourceUrl": "https://example.com/my-video.mp4",
  "bytesDownloaded": 15728640,
  "totalBytes": 15728640,
  "detectedMime": "video/mp4",
  "s3Key": "6354d8d2-e0f1-702b-af6c-62e28e377ec7/promotional-video.mp4"
}

Note: Use the s3Key value in attachmentPaths when the state is READY.

FAQ

Do I have to upload media to PostPulse even if I have a public URL?
Not anymore! You can now use the "From Public URL" option in Media → Upload to import media directly from URLs. The system will download and host the media on post-pulse.com for platform compatibility.

How do I import media from a URL?
Use Media → Upload with "From Public URL" option. Provide the URL and optionally a filename hint. The operation returns an import job ID and initial state. Use Media → Get Upload Status to monitor progress until the state becomes "READY".

What are the different import states?

• QUEUED: Import job is waiting to start
• DOWNLOADING: Media is being downloaded from the source URL
• VALIDATING: Downloaded media is being validated
• UPLOADING: Media is being uploaded to PostPulse storage
• READY: Import complete, media ready to use (check s3Key field)
• FAILED_TEMPORARY: Temporary failure, may retry automatically
• FAILED_PERMANENT: Permanent failure, check errorCode and errorMessage

Can I draft then update later via the node?
In v1 of the node, we recommend isDraft: false. Update endpoints will be exposed in a later version.

How do I post to multiple accounts at once?
Create one PostSchedule with multiple Publication objects (one per account).

How do I set YouTube or TikTok titles?
Titles live in platformSettings (see schemas above). content becomes description.

Should I use webhooks or polling for status updates?
Webhooks are recommended for production workflows as they provide real-time notifications without the need to repeatedly call status endpoints. Set up webhooks at https://developers.post-pulse.com to receive instant notifications for post publishing status and media import progress. Use polling (Get Upload Status) only for testing or when webhooks aren't feasible.

Support

• Developer Portal: https://developers.post-pulse.com (for OAuth client setup and documentation)
• Discord Community: PostPulse for Developers (feature requests, community support)
• Email Support: support@post-pulse.com (technical issues and general inquiries)

Versioning & License

• Semantic Versioning: MAJOR.MINOR.PATCH
• License: MIT

Security notes

• Store secrets in n8n Credentials only; don’t hardcode in workflows.