Managing threads

Listing threads

Retrieve threads with filtering and pagination:

const { data } = await client.get("/threads", {
  params: {
    limit: 20,
    inbox: "default",
  },
});

console.log(`Found ${data.threads.length} threads`);
data.threads.forEach((thread) => {
  console.log(`${thread.id} — @${thread.prospect.username}`);
});

curl "https://inboxapp.com/api/v1/threads?inbox=default&limit=20" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

Response:

{
  "threads": [
    {
      "id": "l44e15irdq4db30i77cgphhx",
      "platform": "twitter",
      "done": false,
      "assigneeId": null,
      "lastMessageTimestamp": "2025-01-15T15:30:00.000Z",
      "computedSortTimestamp": "2025-01-15T15:30:00.000Z",
      "createdAt": "2025-01-10T10:00:00.000Z",
      "status": "active",
      "accountLinkId": "df6jbw4h36qm5d9iu2sgn7kx",
      "isSyncing": false,
      "isRequest": false,
      "lastMessage": {
        "id": "p8rvk2m5j0xn4wq7ybftcael",
        "content": "Sounds great, let's schedule a call!",
        "authorId": "hzcai5t59nn9vsck3rbuepyg",
        "createdAt": "2025-01-15T15:30:00.000Z",
        "userId": null,
        "campaignId": null
      },
      "prospect": {
        "platform": "twitter",
        "platformId": "1876543210987654321",
        "displayName": "Jordan Rivera",
        "username": "jordanrivera",
        "handle": "@jordanrivera",
        "image": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "bio": "Head of Growth at TechCo",
        "followerCount": 12400,
        "verified": "none",
        "context": {
          "tags": [],
          "statusId": null,
          "valuation": null,
          "notes": null
        },
        "..."
      }
    }
  ],
  "nextCursor": {
    "id": "l44e15irdq4db30i77cgphhx",
    "timestamp": "2025-01-15T15:30:00.000Z"
  }
}

The default page size is 20 (max 100). Use nextCursor to paginate.

Looking up threads by username

Find all threads for a prospect by their exact platform username:

const { data: threads } = await client.get("/threads/lookup-by-username", {
  params: {
    username: "jordanrivera",
  },
});

threads.forEach((thread) => {
  console.log(`${thread.id} — ${thread.accountLinkId}`);
});

curl "https://inboxapp.com/api/v1/threads/lookup-by-username?username=jordanrivera" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

Returns a flat array of Thread objects — one per account link that has a conversation with that prospect. No pagination; all matching threads are returned.

Filter by account link

Scope results to specific connected accounts:

const { data: threads } = await client.get("/threads/lookup-by-username", {
  params: {
    username: "jordanrivera",
    "accountLinkIds[0]": "df6jbw4h36qm5d9iu2sgn7kx",
  },
});

The username must be an exact match (case-insensitive, without the @ prefix). For lookup by platform ID, use GET /threads/lookup instead.

Filtering threads

By Inbox view

The inbox parameter filters by thread state:

// Active conversations
const active = await client.get("/threads", { params: { inbox: "default" } });

// Prospect sent the last message — you need to reply
const noReply = await client.get("/threads", { params: { inbox: "no-reply" } });

// New message requests
const requests = await client.get("/threads", {
  params: { inbox: "requests" },
});

// Archived (done)
const archived = await client.get("/threads", {
  params: { inbox: "archived" },
});

By account link

Filter threads to specific connected accounts. Pass an array of IDs via accountLinkIds:

const { data } = await client.get("/threads", {
  params: {
    "accountLinkIds[0]": "df6jbw4h36qm5d9iu2sgn7kx",
  },
});

By tags

// Prospects with ANY of these tags
const { data } = await client.get("/threads", {
  params: {
    "filters[tags][selectedIds][0]": "t8rvk2m5j0xn4wq7ybftcael",
    "filters[tags][selectedIds][1]": "u9swl3n6k1yo5xr8zcgudbfm",
  },
});

// Prospects with NO tags
const { data: untagged } = await client.get("/threads", {
  params: {
    "filters[tags][noTags]": true,
  },
});

By status

// Threads with prospects in specific statuses
const { data } = await client.get("/threads", {
  params: {
    "filters[statuses][selectedIds][0]": "s3km7xj9wq5p2bvnhfdteoly",
  },
});

// Prospects with no status
const { data: noStatus } = await client.get("/threads", {
  params: {
    "filters[statuses][noStatus]": true,
  },
});

By assignee

// Assigned to specific member
const { data } = await client.get("/threads", {
  params: {
    "filters[assignees][selectedIds][0]": "r3km7xj9wq5p2bvnhfdteoly",
  },
});

// Unassigned threads
const { data: unassigned } = await client.get("/threads", {
  params: {
    "filters[assignees][noAssignee]": true,
  },
});

By campaign

// Threads from specific campaigns
const { data } = await client.get("/threads", {
  params: {
    "filters[campaigns][selectedIds][0]": "c5nwp8r2j3ym6at0xbkqhfvg",
  },
});

// Threads not from any campaign
const { data: noCampaign } = await client.get("/threads", {
  params: {
    "filters[campaigns][noCampaign]": true,
  },
});

Sort order

const { data } = await client.get("/threads", {
  params: {
    "filters[sortOrder]": "desc", // or 'asc'
  },
});

Combined filters

Filters combine with AND logic:

// Active threads, qualified status, assigned to a specific member
const { data } = await client.get("/threads", {
  params: {
    inbox: "default",
    "accountLinkIds[0]": "df6jbw4h36qm5d9iu2sgn7kx",
    "filters[statuses][selectedIds][0]": "s3km7xj9wq5p2bvnhfdteoly",
    "filters[assignees][selectedIds][0]": "r3km7xj9wq5p2bvnhfdteoly",
    limit: 20,
  },
});

Filter helper

A utility to build filter params:

function buildFilters(opts: {
  tagIds?: string[];
  statusIds?: string[];
  assigneeIds?: string[];
  campaignIds?: string[];
  noTags?: boolean;
  noStatus?: boolean;
  noAssignee?: boolean;
  noCampaign?: boolean;
  sortOrder?: "asc" | "desc";
}) {
  const params: Record<string, string | boolean> = {};

  opts.tagIds?.forEach((id, i) => {
    params[`filters[tags][selectedIds][${i}]`] = id;
  });
  opts.statusIds?.forEach((id, i) => {
    params[`filters[statuses][selectedIds][${i}]`] = id;
  });
  opts.assigneeIds?.forEach((id, i) => {
    params[`filters[assignees][selectedIds][${i}]`] = id;
  });
  opts.campaignIds?.forEach((id, i) => {
    params[`filters[campaigns][selectedIds][${i}]`] = id;
  });

  if (opts.noTags) params["filters[tags][noTags]"] = true;
  if (opts.noStatus) params["filters[statuses][noStatus]"] = true;
  if (opts.noAssignee) params["filters[assignees][noAssignee]"] = true;
  if (opts.noCampaign) params["filters[campaigns][noCampaign]"] = true;
  if (opts.sortOrder) params["filters[sortOrder]"] = opts.sortOrder;

  return params;
}

const { data } = await client.get("/threads", {
  params: {
    inbox: "default",
    ...buildFilters({ tagIds: ["t8rvk2m5j0xn4wq7ybftcael"], noAssignee: true }),
    limit: 50,
  },
});

Pagination

Use cursorId and cursorTimestamp to paginate through all threads:

async function getAllThreads() {
  const allThreads: any[] = [];
  let cursorId: string | undefined;
  let cursorTimestamp: string | undefined;

  do {
    const { data } = await client.get("/threads", {
      params: {
        limit: 100,
        ...(cursorId && { cursorId, cursorTimestamp }),
      },
    });

    allThreads.push(...data.threads);
    cursorId = data.nextCursor?.id;
    cursorTimestamp = data.nextCursor?.timestamp;
  } while (cursorId);

  return allThreads;
}

See Pagination for streaming patterns and error handling.

Looking up a thread

Find an existing thread between an account and a prospect:

const { data: thread } = await client.get("/threads/lookup", {
  params: {
    externalPlatformId: "1876543210987654321",
    accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
  },
});

if (thread) {
  console.log("Found thread:", thread.id);
} else {
  console.log("No thread exists yet");
}

curl "https://inboxapp.com/api/v1/threads/lookup?externalPlatformId=1876543210987654321&accountLinkId=df6jbw4h36qm5d9iu2sgn7kx" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

The lookup endpoint accepts either externalPlatformId (X user ID) or externalId (Inbox external ID). At least one must be provided along with accountLinkId. Returns the Thread object directly, or null if no thread exists.

Creating a thread

Create a new conversation thread:

const { data: thread } = await client.post("/threads", {
  externalPlatformId: "1876543210987654321",
  accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
});

console.log("Created thread:", thread.id);

Creating a thread doesn’t send a message. Use the messages endpoint to send a DM.

If a thread already exists between the account link and prospect, the API will return an error. Use lookup first to check, or use the lookup-or-create pattern below.

Getting thread details

const { data: thread } = await client.get(`/threads/${threadId}`);

console.log("Thread:", thread.id);
console.log("Prospect:", thread.prospect.displayName);
console.log("Last message:", thread.lastMessage?.content);

Returns the Thread object directly — not wrapped in { thread: ... }.

Updating threads

Modify thread assignment and done status:

// Assign thread to a team member
await client.patch(`/threads/${threadId}`, {
  assigneeId: "r3km7xj9wq5p2bvnhfdteoly",
});

// Mark thread as done (archives it)
await client.patch(`/threads/${threadId}`, {
  done: true,
});

// Unassign and reopen
await client.patch(`/threads/${threadId}`, {
  assigneeId: null,
  done: false,
});

Deleting threads

Soft-delete a thread:

await client.delete(`/threads/${threadId}`);

Deletion is permanent and cannot be undone. The thread is also deleted on the X platform. Consider using done: true to archive instead.

Common workflows

Lookup-or-create pattern

async function getOrCreateThread(
  prospectPlatformId: string,
  accountLinkId: string,
) {
  const { data: existing } = await client.get("/threads/lookup", {
    params: { externalPlatformId: prospectPlatformId, accountLinkId },
  });

  if (existing) return existing;

  const { data: created } = await client.post("/threads", {
    externalPlatformId: prospectPlatformId,
    accountLinkId,
  });

  return created;
}

Round-robin assignment

const memberIds = ["r3km7xj9wq5p2bvnhfdteoly", "s4ln8yk0xr6q3cw1behsifup", "t5mo9zl1ys7r4dx2cfitjgvqw"];
let idx = 0;

async function assignRoundRobin(threadId: string) {
  await client.patch(`/threads/${threadId}`, {
    assigneeId: memberIds[idx],
  });
  idx = (idx + 1) % memberIds.length;
}

Get threads needing follow-up

const { data } = await client.get("/threads", {
  params: {
    inbox: "no-reply",
    limit: 50,
  },
});

console.log(`${data.threads.length} threads awaiting your reply`);

List threads

GET /threads

Lookup by username

GET /threads/lookup-by-username

Create thread

POST /threads

Lookup thread

GET /threads/lookup

Update thread

PATCH /threads/

Delete thread

DELETE /threads/

Working with messages

Send and receive messages in threads

Getting started

Fundamentals

Configuration

Listing threads

Looking up threads by username

Filter by account link

Filtering threads

By Inbox view

By account link

By tags

By status

By assignee

By campaign

Sort order

Combined filters

Filter helper

Looking up a thread

Creating a thread

Getting thread details

Updating threads

Deleting threads

Common workflows

Lookup-or-create pattern

Round-robin assignment

Get threads needing follow-up

List threads

Lookup by username

Create thread

Lookup thread

Update thread

Delete thread

Working with messages

​Listing threads

​Looking up threads by username

​Filter by account link

​Filtering threads

​By Inbox view

​By account link

​By tags

​By status

​By assignee

​By campaign

​Sort order

​Combined filters

​Filter helper

​Pagination

​Looking up a thread

​Creating a thread

​Getting thread details

​Updating threads

​Deleting threads

​Common workflows

​Lookup-or-create pattern

​Round-robin assignment

​Get threads needing follow-up

​Related endpoints

List threads

Lookup by username

Create thread

Lookup thread

Update thread

Delete thread

Working with messages

Listing threads

Looking up threads by username

Filter by account link

Filtering threads

By Inbox view

By account link

By tags

By status

By assignee

By campaign

Sort order

Combined filters

Filter helper

Pagination

Looking up a thread

Creating a thread

Getting thread details

Updating threads

Deleting threads

Common workflows

Lookup-or-create pattern

Round-robin assignment

Get threads needing follow-up

Related endpoints