In the first tutorial, "Submit Your First Message," you have learned how to submit a message to a topic.
In this tutorial, you will learn how to query the Hedera Mirror Node API to retrieve and filter messages.
Prerequisites
We recommend that you complete the "Submit Your First Message" tutorial here to get a basic understanding of the Hedera Consensus Service. This example does not build upon the previous examples.
1. Create a topic and submit three messages
For this tutorial, create a new topic and submit three messages to this topic on testnet. You will use the retrieved topic ID to query for messages via the Hedera Mirror Node API.
Copy and execute the following code. Make sure to write down your topic ID. The topic ID will be in 0.0.topicId format (ex: 0.0.1234).
// Create a new topicTransactionResponse txResponse =newTopicCreateTransaction().setSubmitKey(myPrivateKey.getPublicKey()).execute(client);// Get the receiptTransactionReceipt receipt =txResponse.getReceipt(client);// Get the topic IDTopicId topicId =receipt.topicId;// Log the topic IDSystem.out.println("Your topic ID is: "+topicId);// Submit messagesTransactionResponse submitMessage1 =newTopicMessageSubmitTransaction().setTopicId(topicId).setMessage("Message 1").execute(client);TransactionResponse submitMessage2 =newTopicMessageSubmitTransaction().setTopicId(topicId).setMessage("Message 2").execute(client);TransactionResponse submitMessage3 =newTopicMessageSubmitTransaction().setTopicId(topicId).setMessage("Message 3").execute(client);
// Create a new public topiclet txResponse =awaitnewTopicCreateTransaction().execute(client);// Grab the newly generated topic IDlet receipt =awaittxResponse.getReceipt(client);let topicId =receipt.topicId;console.log(`Your topic ID is: ${topicId}`);// Submit messagesawaitnewTopicMessageSubmitTransaction({ topicId: topicId, message:"Message 1",}).execute(client);awaitnewTopicMessageSubmitTransaction({ topicId: topicId, message:"Message 2",}).execute(client);awaitnewTopicMessageSubmitTransaction({ topicId: topicId, message:"Message 3",}).execute(client);
// Create a new topictransactionResponse, err := hedera.NewTopicCreateTransaction().SetSubmitKey(myPrivateKey.PublicKey()).Execute(client)if err !=nil {println(err.Error(), ": error creating topic")return}// Get the topic create transaction receipttransactionReceipt, err := transactionResponse.GetReceipt(client)if err !=nil {println(err.Error(), ": error getting topic create receipt")return}// Get the topic ID from the transaction receipttopicID :=*transactionReceipt.TopicID// Log the topic ID to the consolefmt.Printf("Your topic ID is: %v\n", topicID)// Submit messagessubmitMessage1, err := hedera.NewTopicMessageSubmitTransaction().SetMessage([]byte("Message 1")).SetTopicID(topicID).Execute(client)if err !=nil {println(err.Error(), ": error submitting to topic")return}submitMessage2, err := hedera.NewTopicMessageSubmitTransaction().SetMessage([]byte("Message 2")).SetTopicID(topicID).Execute(client)if err !=nil {println(err.Error(), ": error submitting to topic")return}submitMessage3, err := hedera.NewTopicMessageSubmitTransaction().SetMessage([]byte("Message 3")).SetTopicID(topicID).Execute(client)if err !=nil {println(err.Error(), ": error submitting to topic")return}
The output in your console should look like this after executing the above setup code:
Your topic ID is: 0.0.<4603900>
Next, let's query the mirror node to retrieve data.
2. Query the Hedera Mirror Node API
Now all three messages have been submitted to your topic ID on testnet, let's query the mirror node. Let's use the testnet endpoint for the Hedera Mirror Node API to query for all messages for your topic ID. Make sure to replace the topic ID with the topic ID you've written down and execute the request in your browser or tool of choice.
// Replace <topicId>
https://testnet.mirrornode.hedera.com/api/v1/topics/<topicID>/messages
// Example
https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.4603900/messages
The result should look similar to the API result below, with three messages being returned. The actual message contents are base64 encoded. If you want to verify the message contents, you can use this decoder website or decode it using code yourself.
In this section, you'll learn how to query messages by a sequence number. Each message you submit to a topic receives a sequence number starting from 1.
If you take a look at the REST API docs for Topics, you'll find the first query /api/v1/topics/{topicId}/messages. If you expand this section, you'll find all query parameters.
Execute the below request to retrieve the message with sequence number 2.
// Replace <topicId>
https://testnet.mirrornode.hedera.com/api/v1/topics/<topicID>/messages?sequencenumber=2
// Example
https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.4603900/messages?sequencenumber=2
✅ API result
Only message two is returned by the Hedera Mirror Node.
This section explores advanced filtering methods using query modifiers. The OpenAPI specification for the Hedera Mirror Node REST API shows all details for query parameters (e.g. timestampQueryParam).
Possible query modifiers are:
Greater than (gt) / greater than or equal (gte)
Lower than (lt) / lower than or equal (lte)
Equal to (eq)
Not equal to (ne)
You can use these modifiers for query parameters like sequencenumber and timestamp (consensus timestamp).
In this step, let's query all messages with a sequence number greater than or equal to 2. To do so, let's use the gte query parameter modifier and assign it the value 2, like this: sequencenumber=gte:2.
// Replace <topicId>
https://testnet.mirrornode.hedera.com/api/v1/topics/<topicID>/messages?sequencenumber=gte:2
// Example
https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.4603900/messages?sequencenumber=gte:2
✅ API result
Only message two is returned by the Hedera Mirror Node.
