Accessing User Data (Telegram)

This tutorial will walk through how to use Verida API's to access user data, with a focus on accessing Telegram data.

Getting started

If you haven't already, register a Verida Account, sign into the Developer Console and obtain an Auth token so you can make API requests.

Making an API requests

Once you have an auth token, you must include it in your API requests.

Here are some examples of API requests to the AI agent endpoint.

Command line (via curl):

curl -X POST -H "Authorization: Bearer <authToken>" "https://api.verida.ai/api/rest/v1/llm/agent" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js:

const axios = require('axios');

axios({
  method: 'POST',
  url: 'https://api.verida.ai/api/rest/v1/llm/agent',
  data: {},
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <authToken>'
  }
})
.then(res => {
  console.log(res.data)
})
.catch(err => {
  console.error(err)
})

Useful resources:

1. Make example requests with the Developer Console Sandbox
2. API requests documentation
3. Overview of all API endpoints
4. API Reference Documentation

Fetching Telegram Data

When a user connects their Telegram account, their groups and messages are syncronized and the data is normalized into common data types. See Data Types to learn more.

Telegram populates two data schemas:

• Social Chat Group (view data schema)
• Social Chat Message (view data schema)

We need to query these schemas using the 4. Query a Datastore API endpoint.

List the user's Telegram groups

Let's start with an example to fetch all the Telegram chat groups a user is in. We need to make an API request to the /ds/queryendpoint (https://api.verida.ai/api/rest/v1/ds/query/).

This endpoint takes a schema, in our case we want the social chat group schema (https://common.schemas.verida.io/social/chat/group/v0.1.0/schema.json), however we don't send the actual schema URL, we base64 encoded it.

Node.js example:

const axios = require('axios');

const schemaUrl = 'https://common.schemas.verida.io/social/chat/group/v0.1.0/schema.json';
const schemaUrlEncoded = bvoa(schemaUrl);

axios({
  method: 'POST',
  url: `https://api.verida.ai/api/rest/v1/ds/query/${schemaUrlEncoded}`,
  data: {
  "options": {
    "sort": [
      {
        "_id": "desc"
      }
    ],
    "limit": 20
  }
},
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <authToken>'
  }
})
.then(res => {
  console.log(res.data)
})
.catch(err => {
  console.error(err)
})

View the example JSON response of a chat group.

List the user's Telegram messages

Let's now fetch all of a user's Telegram messages. Instead of querying the Chat Group datastore, we need to query the Chat Message datastore.

We also want to fetch only telegram messages, so apply a filter:

const axios = require('axios');

const schemaUrl = 'https://common.schemas.verida.io/social/chat/message/v0.1.0/schema.json';
const schemaUrlEncoded = bvoa(schemaUrl);

axios({
  method: 'POST',
  url: `https://api.verida.ai/api/rest/v1/ds/query/${schemaUrlEncoded}`,
  data: {
  "query": {
    "sourceApplication": "https://telegram.com"
  },
  "options": {
    "sort": [
      {
        "_id": "desc"
      }
    ],
    "limit": 20
  }
},
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <authToken>'
  }
})
.then(res => {
  console.log(res.data)
})
.catch(err => {
  console.error(err)
})

View the example JSON response for a chat message.

We can update the queryto restrict to only include results from:

• A particular group

• Messages sent by me

• Messages sent after Jan 1st 2025

{
    "sourceApplication": "https://telegram.com",
    "groupId": "telegram-456049390--579961374",
    "type": "send",
    "sentAt": {
        "$gte": "2025-01-01"
    }
}

Counting messages or groups

You may want to make requests such as:

1. How many messages sent by a user?

2. How many groups is a user part of?

It is possible to use the /query API endpoint and loop through all the pages of data to count, but that is highly inefficient.

This functionality will be coming very shortly with a new /count endpoint.

User information

You may want to learn more about a user's profile on Telegram, for example:

1. Is the account verified?

2. Phone number

3. Username

4. Profile pic

This data is currently syncronized, but not available via the API.

This functionality will be coming very shortly with a new /profile endpoint