{"id":12284,"library":"unipile-node-sdk","title":"Unipile Node.js SDK","description":"The Unipile Node.js SDK (version 1.9.3) provides a unified interface for integrating with multiple communication platforms, including LinkedIn, WhatsApp, Instagram, Telegram, and a generic Email API. It allows developers to programmatically manage social connections, send and receive messages (including LinkedIn InMail), retrieve user and company profiles, handle invitations, manage posts, and control email communications. This SDK is particularly useful for applications requiring multi-channel outreach, unified inboxes, or automation across various professional and messaging platforms, abstracting the complexities and individual APIs of each service. The SDK is actively maintained with regular updates reflecting new features and API changes across its supported providers.","status":"active","version":"1.9.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install unipile-node-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add unipile-node-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add unipile-node-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The Unipile SDK is designed for ESM, though CJS support was added in previous versions. For new projects, ESM `import` is recommended.","wrong":"const UnipileClient = require('unipile-node-sdk')","symbol":"UnipileClient","correct":"import { UnipileClient } from 'unipile-node-sdk'"},{"note":"While not explicitly shown in the README, SDKs often export a custom error class for handling API-specific exceptions like authentication failures or rate limits, which typically inherit from `Error`.","symbol":"UnipileError","correct":"import { UnipileError } from 'unipile-node-sdk'"},{"note":"Type imports are crucial for TypeScript projects to ensure correct parameter structures for API calls, like connecting a LinkedIn account.","symbol":"AccountConnectLinkedinInput","correct":"import type { AccountConnectLinkedinInput } from 'unipile-node-sdk'"}],"quickstart":{"code":"import { UnipileClient } from 'unipile-node-sdk';\n\n// Initialize the Unipile client with your DSN and Access Token.\n// Always use environment variables for sensitive credentials in production.\nconst client = new UnipileClient(\n  process.env.UNIPIL_DSN ?? 'https://api.unipile.com', // Default or example DSN\n  process.env.UNIPIL_ACCESS_TOKEN ?? '' // Your Unipile API Access Token\n);\n\nasync function runUnipileExample() {\n  try {\n    console.log('Attempting to generate a Hosted Auth Link...');\n    // Generates a link for users to connect their social accounts securely.\n    const authLinkResponse = await client.account.createHostedAuthLink({\n      type: 'create', // 'create' for new accounts, 'reconnect' for existing\n      expiresOn: new Date(Date.now() + 3600 * 1000).toISOString(), // Link valid for 1 hour\n      api_url: process.env.UNIPIL_API_URL ?? 'https://api.unipile.com', // Your Unipile API URL\n      providers: '*', // '*' for all providers, or an array like ['LINKEDIN', 'WHATSAPP']\n      success_redirect_url: 'https://your-app.com/auth-success', // Where to redirect after successful connection\n      metadata: { userId: 'user-123', integrationType: 'onboarding' } // Optional metadata\n    });\n    console.log('Hosted Auth Link Generated:', authLinkResponse.url); \n\n    // Example: Retrieve a LinkedIn company profile (requires a connected LinkedIn account_id).\n    // This account_id would typically be stored after a user successfully connects via the auth link.\n    const linkedinAccountId = process.env.LINKEDIN_ACCOUNT_ID; // Example: 'acc_xyz123'\n    if (linkedinAccountId) {\n      console.log(`\\nRetrieving LinkedIn company profile for account ${linkedinAccountId}...`);\n      const companyProfile = await client.users.getCompanyProfile({\n        account_id: linkedinAccountId,\n        identifier: 'Unipile', // The company's name or LinkedIn ID\n      });\n      console.log('Retrieved Company Profile:', companyProfile);\n    } else {\n      console.warn('\\nWarning: LINKEDIN_ACCOUNT_ID environment variable not set. Skipping company profile example.');\n    }\n\n  } catch (error) {\n    console.error('\\nAn error occurred during Unipile SDK operation:');\n    if (error instanceof Error) {\n      console.error('Error message:', error.message);\n      // Log the full error object for debugging in development\n      if (process.env.NODE_ENV !== 'production') {\n        console.error(error);\n      }\n    } else {\n      console.error(error);\n    }\n  }\n}\n\nrunUnipileExample();","lang":"typescript","description":"This quickstart demonstrates how to initialize the Unipile client, generate a hosted authentication link for account connection, and retrieve a LinkedIn company profile using environment variables for secure credential management."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 18 or later.","message":"The Unipile Node.js SDK requires Node.js version 18 or higher. Applications running on older Node.js versions will encounter compatibility issues or fail to run.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Store Unipile DSN and Access Tokens securely as environment variables (e.g., `process.env.UNIPIL_DSN`, `process.env.UNIPIL_ACCESS_TOKEN`) and access them only on the server-side.","message":"API Access Tokens and DSN (Data Source Name) are sensitive credentials. Exposing them in client-side code or committing them directly to version control poses a significant security risk.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement robust rate-limiting and back-off strategies in your application. Monitor API usage and adhere to Unipile's and the underlying platforms' recommendations. Use real accounts, avoid suspicious behavior, and inform users about automated actions.","message":"Interacting with social media APIs (LinkedIn, WhatsApp, Instagram) is subject to strict rate limits and terms of service. Excessive or automated activity can lead to temporary blocks or permanent account suspension.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully follow the Unipile documentation for each provider's authentication method. For automated methods (e.g., username/password), ensure robust error handling for 2FA/OTP challenges.","message":"Authentication processes for platforms like LinkedIn can be complex, involving hosted auth flows or direct username/password methods which may require handling 2FA/OTP checkpoints. Incorrect implementation can lead to connection failures or account lockouts.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly update the `unipile-node-sdk` to the latest version. Monitor Unipile's changelog and documentation for updates regarding provider API changes.","message":"The underlying APIs (LinkedIn, WhatsApp, etc.) frequently update, which may introduce breaking changes not immediately reflected in the SDK. This can lead to unexpected errors or outdated functionality.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify your `UNIPIL_DSN` configuration. Check network connectivity and Unipile's service status page. Ensure your firewall isn't blocking outgoing connections.","cause":"The Unipile API endpoint (DSN) is unreachable, possibly due to a network issue, incorrect DSN, or Unipile service outage.","error":"Error: connect ECONNREFUSED"},{"fix":"Ensure your `UNIPIL_ACCESS_TOKEN` is correct and current. If an account is disconnected, prompt the user to re-authenticate via the hosted authentication flow.","cause":"The provided `UNIPIL_ACCESS_TOKEN` is missing, expired, or invalid, or the connected account is disconnected from the provider.","error":"Error: Unauthorized"},{"fix":"Implement exponential back-off and retry logic for API calls. Review and adjust your application's usage patterns to stay within documented rate limits.","cause":"Your application has exceeded the API rate limits imposed by Unipile or the underlying social media platform (e.g., LinkedIn).","error":"Error: Too Many Requests"},{"fix":"Ensure you are using `import { UnipileClient } from 'unipile-node-sdk';` and that your `package.json` specifies `\"type\": \"module\"` or your file uses `.mjs` extension for ESM. Verify the client is initialized before calling methods.","cause":"This typically occurs when `unipile-node-sdk` is imported using CommonJS `require()` syntax in an environment expecting ESM, or if the client object is not correctly initialized.","error":"TypeError: client.users.getCompanyProfile is not a function"},{"fix":"Verify that the `account_id` used in the API call is valid and corresponds to an actively connected account for the specific provider (e.g., LinkedIn for `getCompanyProfile`). Double-check stored `account_id` values.","cause":"The `account_id` provided for an operation is incorrect, not found, or not associated with the requested feature or provider.","error":"Error: Invalid account"}],"ecosystem":"npm"}