Skip to main content

​
Overview

Account links represent X (Twitter) accounts connected to your Inbox team. Each account link enables you to send and receive DMs through that account.

​
Data Model

interface AccountLink {
  id: string;              // Inbox account link ID
  platformId: string;      // X user ID
  platform: 'x';           // Platform type
  platformUsername: string;// @handle
  name: string;            // Display name
  profileImageUrl?: string;// Avatar URL
  createdAt: string;
}
Retrieve all connected accounts: 
const { data } = await client.get('/account-links');

console.log(`${data.accountLinks.length} connected account(s)`);

data.accountLinks.forEach(account => {
  console.log(`@${account.platformUsername} (${account.id})`);
});
Response: 
{
  "accountLinks": [
    {
      "id": "acc_abc123",
      "platformId": "123456789",
      "platform": "x",
      "platformUsername": "acmecorp",
      "name": "Acme Corp",
      "profileImageUrl": "https://pbs.twimg.com/profile_images/...",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "acc_def456",
      "platformId": "987654321",
      "platform": "x",
      "platformUsername": "acmesupport",
      "name": "Acme Support",
      "profileImageUrl": "https://pbs.twimg.com/profile_images/...",
      "createdAt": "2024-02-01T09:00:00.000Z"
    }
  ]
}

​
Send Messages from Specific Accounts

Specify which account to send from: 
// Find the account to use
const { data: accountsData } = await client.get('/account-links');
const salesAccount = accountsData.accountLinks.find(
  (a: any) => a.platformUsername === 'acmecorp'
);

// Send message using that account
await client.post('/threads/messages', {
  prospectPlatformId: '555555555',
  accountLinkId: salesAccount.id,
  text: 'Hi! Reaching out from our sales team.'
});

​
Filter Threads by Account

View conversations for a specific account: 
// Get threads for a specific account
const { data } = await client.get('/threads', {
  params: {
    accountLinkId: 'acc_abc123'
  }
});

console.log(`${data.threads.length} threads for this account`);

​
Lookup Threads by Account

Check if a thread exists for a specific account-prospect pair: 
const { data } = await client.get('/threads/lookup', {
  params: {
    prospectPlatformId: '555555555',
    accountLinkId: 'acc_abc123'
  }
});

if (data.thread) {
  console.log('Thread exists:', data.thread.id);
} else {
  console.log('No existing thread');
}

​
Multi-Account Patterns

​
Account Selection Logic

Choose the appropriate account based on context: 
interface AccountSelector {
  accountLinkId: string;
  condition: (prospect: any) => boolean;
}

const accountRules: AccountSelector[] = [
  {
    // High-value prospects get personal outreach
    accountLinkId: 'acc_founder',
    condition: (prospect) => prospect.followersCount >= 100000
  },
  {
    // Support issues go to support account
    accountLinkId: 'acc_support',
    condition: (prospect) => prospect.tags?.some((t: any) => t.name === 'Support')
  },
  {
    // Default to main account
    accountLinkId: 'acc_main',
    condition: () => true
  }
];

function selectAccount(prospect: any): string {
  for (const rule of accountRules) {
    if (rule.condition(prospect)) {
      return rule.accountLinkId;
    }
  }
  return accountRules[accountRules.length - 1].accountLinkId;
}

​
Aggregate Metrics Across Accounts

Get total conversation counts: 
async function getAggregateMetrics() {
  const { data: accountsData } = await client.get('/account-links');
  const metrics: Record<string, any> = {};

  for (const account of accountsData.accountLinks) {
    const { data: threadsData } = await client.get('/threads', {
      params: {
        accountLinkId: account.id,
        inboxView: 'default'
      }
    });

    metrics[account.platformUsername] = {
      activeThreads: threadsData.threads.length,
      accountId: account.id
    };

    await new Promise(r => setTimeout(r, 100));
  }

  return metrics;
}

const metrics = await getAggregateMetrics();
console.log('Active threads by account:', metrics);

​
Cross-Account Thread Check

Check if you have any existing thread with a prospect: 
async function findAnyThread(prospectPlatformId: string) {
  const { data: accountsData } = await client.get('/account-links');

  for (const account of accountsData.accountLinks) {
    const { data } = await client.get('/threads/lookup', {
      params: {
        prospectPlatformId,
        accountLinkId: account.id
      }
    });

    if (data.thread) {
      return {
        thread: data.thread,
        accountLink: account
      };
    }
  }

  return null;
}

const existing = await findAnyThread('555555555');
if (existing) {
  console.log(`Found thread via @${existing.accountLink.platformUsername}`);
}

​
Account-Specific Workflows

​
Sales vs Support Routing

const SALES_ACCOUNT_ID = 'acc_sales';
const SUPPORT_ACCOUNT_ID = 'acc_support';

async function routeIncomingMessage(thread: any, message: any) {
  const text = message.text.toLowerCase();

  // Determine if this is a support or sales conversation
  const supportKeywords = ['help', 'issue', 'problem', 'not working', 'bug'];
  const isSupport = supportKeywords.some(k => text.includes(k));

  // If message came to sales account but is support issue
  if (thread.accountLinkId === SALES_ACCOUNT_ID && isSupport) {
    // Notify support team via their account
    await client.post('/threads/messages', {
      prospectPlatformId: thread.prospect.platformId,
      accountLinkId: SUPPORT_ACCOUNT_ID,
      text: "Hi! I'm from the support team. Let me help you with this issue."
    });
  }
}

​
Brand Voice by Account

Maintain different tones for different accounts: 
const brandVoices: Record<string, string> = {
  'acc_founder': 'personal, casual, founder-to-founder',
  'acc_sales': 'professional, helpful, solution-focused',
  'acc_support': 'empathetic, patient, technical when needed'
};

function getSystemPrompt(accountLinkId: string): string {
  const voice = brandVoices[accountLinkId] || 'professional and helpful';
  return `You are responding on behalf of this account. Maintain a ${voice} tone.`;
}

​
ID Types

Account links have two ID types. Use the correct one:
PropertyExampleUse For
id (Inbox ID)acc_abc123All API operations
platformId (X ID)123456789Reference only
// Correct: Use Inbox ID
await client.get('/threads', {
  params: { accountLinkId: account.id }
});

// Wrong: Using platform ID
await client.get('/threads', {
  params: { accountLinkId: account.platformId }
});

​
Connecting New Accounts

Account links are connected through the Inbox dashboard, not the API. To add a new X account:
  1. Go to inboxapp.com
  2. Navigate to Settings → Connected Accounts
  3. Click Connect X Account
  4. Authorize the connection
The new account will then appear in API responses.

​
Best Practices

Choose X handles that make account purpose clear:
  • @acmecorp - Main brand account
  • @acme_support - Support inquiries
  • @acme_sales - Sales outreach
Keep a record of which account is used for what purpose so your team uses them consistently.
Regularly check all connected accounts for new messages, not just your primary one.
Message sending limits apply per account. Spread outreach across accounts if needed.

List Account Links

GET /account-links

List Threads

Filter by accountLinkId

Lookup Thread

Find thread by account + prospect

Quick Send

Send from specific account

​
Next Steps

Team Setup

Configure team members

Managing Threads

Work with conversations

Working with Messages

Send and receive messages

Quick Start

Send your first message