Launch Explorer API Studio

📔Primary Inbox

Learn how to build a primary inbox that only includes messages from known senders.

The Primary Inbox should contain all the users that a given user certainly knows.

Some criteria that can be checked for a user to be included in the primary inbox are:

  • Senders is followed by the user on Lens

  • Senders is followed by the user on Farcaster

  • The user has sent tokens to the Sender

If the sender meets none of the listed criteria, they should be removed from the primary inbox and then checked to see if they belong in the General Inbox.

Additionally, you can use XMTP Consent to check if a sender has given consent (has an Allowed consent value) to the sender before including them in the primary inbox. By default, you should place all senders that have been given consent directly into the Primary Inbox.

As demonstrated below, your app's interface can also feature user-friendly options for users to apply consent or deny consent.

Table Of Contents

In this guide, you will learn how to use Airstack to build an XMTP primary inbox by:

Pre-requisites

  • An Airstack account

  • Basic knowledge of GraphQL

  • Basic knowledge of XMTP

Get Started

JavaScript/TypeScript/Python

If you are using JavaScript/TypeScript or Python, Install the Airstack SDK:

React

npm install @airstack/airstack-react

Node

npm install @airstack/node

Then, add the following snippets to your code:

import { init, useQuery } from "@airstack/airstack-react";

init("YOUR_AIRSTACK_API_KEY");

const query = `YOUR_QUERY`; // Replace with GraphQL Query

const Component = () => {
  const { data, loading, error } = useQuery(query);

  if (data) {
    return <p>Data: {JSON.stringify(data)}</p>;
  }

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }
};

Other Programming Languages

To access the Airstack APIs in other languages, you can use https://api.airstack.xyz/gql as your GraphQL endpoint.

🤖 AI Natural Language​

Airstack provides an AI solution for you to build GraphQL queries to fulfill your use case easily. You can find the AI prompt of each query in the demo's caption or title for yourself to try.

Best Practice

While choosing a specific criteria will significantly decrease the number of spam appearing on your user's XMTP inbox, It is best practice that you combine the multiple criterion given here to build your Primary Inbox.

This is done to provide multiple layers of filtration that will make it nearly impossible for spammers to have their messages slide into your users' XMTP inbox.

Check If A Given User Is Following Senders on Lens

You can check if a given user is following senders on Lens by providing an array of senders' 0x addresses to the $senders variable and the main user to the $mainUser variable using the Wallet API:

You can use this query to filter senders on the fly with a maximum of 200 wallet inputs to the $senders variable per API call.

Try Demo

Code

query isFollowing($mainUser: Identity!, $senders: [Identity!]) {
  Wallet(input: { identity: $mainUser, blockchain: ethereum }) {
    socialFollowers(
      input: {
        filter: { dappName: { _eq: lens }, identity: { _in: $senders } }
      }
    ) {
      Follower {
        dappName
        followingAddress {
          addresses
        }
      }
    }
  }
}

Check If A Given User Is Following Senders on Farcaster

You can check if a given user is following senders on Farcaster by providing an array of senders' 0x addresses to the $senders variable and the main user to the $mainUser variable using the Wallet API:

You can use this query to filter senders on the fly with a maximum of 200 wallet inputs to the $senders variable per API call.

Try Demo

Code

query isFollowing($mainUser: Identity!, $senders: [Identity!]) {
  Wallet(input: { identity: $mainUser, blockchain: ethereum }) {
    socialFollowers(
      input: {
        filter: { dappName: { _eq: farcaster }, identity: { _in: $senders } }
      }
    ) {
      Follower {
        dappName
        followingAddress {
          addresses
        }
      }
    }
  }
}

Check If A Given User Has Sent Tokens To Senders

You can check if a given user has sent any tokens to the senders on either Ethereum, Polygon, Base, or Zora by providing an array of senders' 0x addresses to the $senders variable and the main user to the $mainUser variable using the TokenTransfers API:

Try Demo

Code

You can use this query to filter senders on the fly with a maximum of 200 wallet inputs to the $senders variable per API call.

query GetTokenTransfers(
  $mainUser: Identity!,
  $senders: [Identity!]
) {
  # Check Ethereum token transfers
  ethereum: TokenTransfers(
    input: {
      filter: {
        from: {_eq: $mainUser},
        to: {_in: $senders}
      },
      blockchain: ethereum
    }
  ) {
    TokenTransfer {
      to {
        addresses
      }
    }
  }
  # Check Polygon token transfers
  polygon: TokenTransfers(
    input: {
      filter: {
        from: {_eq: $mainUser},
        to: {_in: $senders}
      },
      blockchain: polygon
    }
  ) {
    TokenTransfer {
      to {
        addresses
      }
    }
  }
  # Check Base token transfers
  base: TokenTransfers(
    input: {
      filter: {
        from: {_eq: $mainUser},
        to: {_in: $senders}
      },
      blockchain: base
    }
  ) {
    TokenTransfer {
      to {
        addresses
      }
    }
  }
  # Check Zora token transfers
  zora: TokenTransfers(
    input: {
      filter: {
        from: {_eq: $mainUser},
        to: {_in: $senders}
      },
      blockchain: zora
    }
  ) {
    TokenTransfer {
      to {
        addresses
      }
    }
  }
}

Developer Support

If you have any questions or need help regarding creating a primary inbox for your XMTP messaging app, please join our Airstack's Telegram group.

More Resources

PreviousSpam FiltersNextGeneral Inbox

Last updated

Was this helpful?