Skip to main content

Writing Follows to Your Graph

Follows represent a follow relationship between two users. Creating follows is easy. Simply pass in the id or the username of the user creating the follow (i.e. the follower) into the startId field, and id or the username of the follow recipient (i.e. the followee) into the endId field. Use the same id you used when creating the profile.

You can use either the socialfi package (recommended for easier integration) or call the API directly.

We recommend using the socialfi package as it simplifies API interactions:

npm install socialfi
import { SocialFi } from 'socialfi';

const API_URL = 'https://api.usetapestry.dev/v1/'; // tapestry prod URL
// const API_URL = 'https://api.dev.usetapestry.dev/v1/'; // tapestry dev URL

const API_KEY = process.env.TAPESTRY_API_KEY; // Get your API key from https://app.usetapestry.dev/

const client = new SocialFi({
  baseURL: API_URL,
  apiKey: API_KEY,
});

Here's an example command that makes user marcus follow user nehemiah.

Using the Socialfi Package​

// Make 'marcus' follow 'nehemiah'
try {
  const followResult = await client.followers.postFollowers(
    { 
      apiKey: API_KEY 
    },
    {
      startId: 'marcus',
      endId: 'nehemiah',
      blockchain: 'SOLANA',
      execution: 'FAST_UNCONFIRMED'
    }
  );
  console.log('Follow created successfully:', followResult);
} catch (error) {
  console.error('Error creating follow:', error);
}

Using the API Directly​

// Make 'marcus' follow 'nehemiah'
try {
  const response = await fetch('https://api.usetapestry.dev/v1/followers?apiKey=YOUR_API_KEY', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      startId: 'marcus',
      endId: 'nehemiah',
      blockchain: 'SOLANA',
      execution: 'FAST_UNCONFIRMED'
    }),
  });
  
  const followResult = await response.json();
  console.log('Follow created successfully:', followResult);
} catch (error) {
  console.error('Error creating follow:', error);
}

Checking Follow Status​

To check if the follow succeeded, you can GET the followers count of the user who received the follow. In this example, we'll ask for nehemiah's followers count:

Using the Socialfi Package​

// Get nehemiah's follower count
try {
  const followerCountData = await client.followers.getFollowersCount(
    {
      apiKey: API_KEY,
      profileId: 'nehemiah'
    }
  );
  console.log(`nehemiah has ${followerCountData.count} followers`);
} catch (error) {
  console.error('Error fetching follower count:', error);
}

Using the API Directly​

// Get nehemiah's follower count
try {
  const response = await fetch(
    'https://api.usetapestry.dev/v1/profiles/followers/nehemiah/count?apiKey=YOUR_API_KEY'
  );
  const followerCountData = await response.json();
  console.log(`nehemiah has ${followerCountData.count} followers`);
} catch (error) {
  console.error('Error fetching follower count:', error);
}

and you can also check the following count of the user who performed the follow. In this example, we'll ask for marcus's following count:

Using the Socialfi Package​

// Get marcus's following count
try {
  const followingCountData = await client.followers.getFollowingCount(
    {
      apiKey: API_KEY,
      profileId: 'marcus'
    }
  );
  console.log(`marcus is following ${followingCountData.count} users`);
} catch (error) {
  console.error('Error fetching following count:', error);
}

Using the API Directly​

// Get marcus's following count
try {
  const response = await fetch(
    'https://api.usetapestry.dev/v1/profiles/following/marcus/count?apiKey=YOUR_API_KEY'
  );
  const followingCountData = await response.json();
  console.log(`marcus is following ${followingCountData.count} users`);
} catch (error) {
  console.error('Error fetching following count:', error);
}

Unfollowing Users​

To unfollow a user, you can use the unfollow endpoint:

Using the Socialfi Package​

// Make 'marcus' unfollow 'nehemiah'
try {
  const unfollowResult = await client.followers.deleteFollower(
    { 
      apiKey: API_KEY 
    },
    {
      startId: 'marcus',
      endId: 'nehemiah',
      blockchain: 'SOLANA',
      execution: 'FAST_UNCONFIRMED'
    }
  );
  console.log('Unfollow successful:', unfollowResult);
} catch (error) {
  console.error('Error unfollowing user:', error);
}

Using the API Directly​

// Make 'marcus' unfollow 'nehemiah'
try {
  const response = await fetch('https://api.usetapestry.dev/v1/followers?apiKey=YOUR_API_KEY', {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      startId: 'marcus',
      endId: 'nehemiah',
      blockchain: 'SOLANA',
      execution: 'FAST_UNCONFIRMED'
    }),
  });
  
  const unfollowResult = await response.json();
  console.log('Unfollow successful:', unfollowResult);
} catch (error) {
  console.error('Error unfollowing user:', error);
}

Getting Follow Lists​

You can retrieve lists of followers and following users:

Get Followers List​

Using the Socialfi Package​

try {
  const followers = await client.followers.getFollowers(
    {
      apiKey: API_KEY,
      profileId: 'nehemiah',
      limit: 20,
      offset: 0
    }
  );
  console.log('Nehemiah\'s followers:', followers);
} catch (error) {
  console.error('Error fetching followers:', error);
}

Using the API Directly​

try {
  const response = await fetch(
    'https://api.usetapestry.dev/v1/profiles/followers/nehemiah?apiKey=YOUR_API_KEY&limit=20&offset=0'
  );
  const followers = await response.json();
  console.log('Nehemiah\'s followers:', followers);
} catch (error) {
  console.error('Error fetching followers:', error);
}

Get Following List​

Using the Socialfi Package​

try {
  const following = await client.followers.getFollowing(
    {
      apiKey: API_KEY,
      profileId: 'marcus',
      limit: 20,
      offset: 0
    }
  );
  console.log('Marcus is following:', following);
} catch (error) {
  console.error('Error fetching following list:', error);
}

Using the API Directly​

try {
  const response = await fetch(
    'https://api.usetapestry.dev/v1/profiles/following/marcus?apiKey=YOUR_API_KEY&limit=20&offset=0'
  );
  const following = await response.json();
  console.log('Marcus is following:', following);
} catch (error) {
  console.error('Error fetching following list:', error);
}

Checking Follow Relationships​

To check if one user follows another:

Using the Socialfi Package​

try {
  const followStatus = await client.followers.checkFollowStatus(
    {
      apiKey: API_KEY,
      followerId: 'marcus',
      followeeId: 'nehemiah'
    }
  );
  console.log('Marcus follows Nehemiah:', followStatus.isFollowing);
} catch (error) {
  console.error('Error checking follow status:', error);
}

Using the API Directly​

try {
  const response = await fetch(
    'https://api.usetapestry.dev/v1/followers/check?apiKey=YOUR_API_KEY&followerId=marcus&followeeId=nehemiah'
  );
  const followStatus = await response.json();
  console.log('Marcus follows Nehemiah:', followStatus.isFollowing);
} catch (error) {
  console.error('Error checking follow status:', error);
}

Response Example​

{
  "isFollowing": true,
  "followId": "follow-123456789",
  "followedAt": "2024-01-15T10:30:00Z"
}

Bulk Follow Operations​

For bulk follow operations, you can follow multiple users at once:

Using the Socialfi Package​

try {
  const bulkFollowResult = await client.followers.bulkFollow(
    {
      apiKey: API_KEY,
    },
    {
      startId: 'marcus',
      endIds: ['nehemiah', 'alice', 'bob'],
      blockchain: 'SOLANA',
      execution: 'FAST_UNCONFIRMED'
    }
  );
  console.log('Bulk follow results:', bulkFollowResult);
} catch (error) {
  console.error('Error in bulk follow:', error);
}

Using the API Directly​

try {
  const response = await fetch('https://api.usetapestry.dev/v1/followers/bulk?apiKey=YOUR_API_KEY', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      startId: 'marcus',
      endIds: ['nehemiah', 'alice', 'bob'],
      blockchain: 'SOLANA',
      execution: 'FAST_UNCONFIRMED'
    }),
  });
  
  const bulkFollowResult = await response.json();
  console.log('Bulk follow results:', bulkFollowResult);
} catch (error) {
  console.error('Error in bulk follow:', error);
}

Example Response Structures​

Followers/Following List Response​

{
  "users": [
    {
      "profile": {
        "id": "marcus",
        "username": "marcus",
        "walletAddress": "ABC123...",
        "customProperties": {
          "bio": "Software developer and crypto enthusiast",
          "profileImage": "https://example.com/marcus.jpg"
        }
      },
      "followRelation": {
        "id": "follow-123456789",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      "socialCounts": {
        "followers": 250,
        "following": 180
      }
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Follow Count Response​

{
  "profileId": "nehemiah",
  "count": 25,
  "lastUpdated": "2024-01-15T11:30:00Z"
}

Best Practices​

When implementing follow functionality:

  • Mutual Follows: Consider implementing logic to detect mutual follows for enhanced social features
  • Rate Limiting: Implement rate limiting to prevent spam following
  • Notifications: Send notifications when users gain new followers
  • Privacy Settings: Respect user privacy settings regarding follow visibility
  • Bulk Operations: Use bulk operations when possible to reduce API calls
  • Error Handling: Handle cases where users try to follow themselves or follow the same user multiple times
  • UI Feedback: Provide immediate UI feedback with optimistic updates
  • Follow Suggestions: Use the social graph to suggest new users to follow