Instant Messaging API

The Instant Messaging API provides access to data from messaging platforms like Telegram and Discord, including chat messages, user profiles, channel information, and server details.

Search for IM messages

GET/api/v2/im/search

Search through the IM messages database using various filters.

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search query string
`gte`	string	No	Date filter (≥). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
`lte`	string	No	Date filter (≤). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Results per page (default: 10)
`platform`	string	No	Filter by messaging platform
`username`	string	No	Filter by username
`topic`	string	No	Filter by topic
`channelId`	string	No	Filter by channelId

curl "https://api.vysion.ai/api/v2/im/search?q=malware" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)

result = c.search_im(
    q="Malware",
    gte="2024-05-16T10:57:58.632466",
    lte="2024-05-16T23:00:00"
)

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "userId": "1234567891011121314",
        "username": null,
        "channelId": "1234567891011121314",
        "messageId": "1234567891011121314_1234567891011121314",
        "message": "Message hit",
        "channelTitle": "txt",
        "topicId": null,
        "topicTitle": null,
        "replyToMessageId": null,
        "isForumTopic": false,
        "languages": [
          {
            "language": "en",
            "probability": 0.857141655897461
          },
          {
            "language": "so",
            "probability": 0.14285741760106124
          }
        ],
        "sha1sum": null,
        "sha256sum": null,
        "media": null,
        "detectionDate": "2025-01-01T00:00:00.000000",
        "serverId": "1234567891011121314",
        "serverTitle": "Discord server",
        "platform": "discord"
      }
    ]
  },
  "error": null
}

Search for IM profiles

GET/api/v2/im/search/profiles

Search through the IM profiles database using various filters.

Parameters

Name	Type	Required	Description
`q`	string	yes	Search query string
`gte`	string	No	Date filter (≥). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
`lte`	string	No	Date filter (≤). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Results per page (default: 10)
`platform`	string	No	Filter by messaging platform
`username`	string	No	Filter by username
`topic`	string	No	Filter by topic
`channelId`	string	No	Filter by channelId

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/search/profiles?q=shadow" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)

result = c.search_im_profiles(
    q="Malware",
    gte="2024-09-01T00:00.00",
    lte="2024-09-02T00:00:00"
)

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "userId": 0123456789,
        "usernames": [
          "shadow123"
        ],
        "firstName": [
          "shadow"
        ],
        "lastName": [
          "shadow2"
        ],
        "detectionDate": "2025-09-01T08:41:10.802Z",
        "profilePhoto": [
          "https://profilePhoto.com/profile_photo"
        ],
        "bot": false,
        "discordLink": [
          "string"
        ],
        "discriminator": [
          0
        ],
        "platform": "Telegram",
        "email": [
          {
            "value": "shadow@email.com"
          }
        ],
        "paste": [
          {
            "value": "pastebin.com/abc1234"
          }
        ],
        "skype": [
          {
            "value": "live:shadow.trader88"
          }
        ],
        "telegram": [
          {
            "value": "t.me/crypto_shadow"
          }
        ],
        "whatsapp": [
          {
            "value": "+12345678"
          }
        ],
        "bitcoin_address": [
          {
            "value": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
          }
        ],
        "polkadot_address": [
          {
            "value": "13kcBHst4jMvJFWzTUfTQrjS5pQf3WTVpc6ZPnSz3gQiTMrQ"
          }
        ],
        "ethereum_address": [
          {
            "value": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
          }
        ],
        "monero_address": [
          {
            "value": "44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A"
          }
        ],
        "ripple_address": [
          {
            "value": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
          }
        ],
        "zcash_address": [
          {
            "value": "t1XatQGQjjZepGNUNE34NBYUOWxUGB4ub1c"
          }
        ]
      }
    ]
  },
  "error": {
    "code": 400,
    "message": "string"
  }
}

Search for IM channels

GET/api/v2/im/search/channels

Search through the IM channels database using various filters.

Parameters

Name	Type	Required	Description
`q`	string	yes	Search query string
`gte`	string	No	Date filter (≥). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
`lte`	string	No	Date filter (≤). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Results per page (default: 10)
`platform`	string	No	Filter by messaging platform
`username`	string	No	Filter by username
`topic`	string	No	Filter by topic
`channelId`	string	No	Filter by channelId

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/search/channels?q=fast leaks" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)

result = c.search_im_channels(
    q="fast leaks",
    platform="discord"
)

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "channelId": 11111122222233333,
        "channelTitles": [
          "# chat"
        ],
        "detectionDate": "2025-09-01T09:10:04.377Z",
        "creationDate": "2025-09-01T09:10:04.377Z",
        "channelPhoto": [
          "https://cdn.discordapp.com/icons/1094527631829504050/a_8f5e9c7d3f6bd4f2e0fe81c9d6f24c9a.jpg"
        ],
        "serverId": 4444445555555666666,
        "serverTitle": [
          "FastLeaks2025"
        ],
        "platform": "discord"
      }
    ]
  },
  "error": {
    "code": 400,
    "message": "string"
  }
}

Get IM Chat by Channel ID

GET/api/v2/im/{platform}/chat/{channelId}

Get messages from a group given a channel ID. Supports both Telegram channels and Discord channels.

Parameters

Name	Type	Required	Description
`platform`	string	Yes	Platform name (`Telegram` or `Discord`)
`channelId`	string	Yes	Channel identifier
`messageId`	string	No	Message identifier
`cursor`	string	No	Pagination token from a previous response’s prev_cursor / next_cursor. Required if messageId is not provided
`limit`	integer	No	Limit the number of messages

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/Telegram/chat/-1003065442080?messageId=31&limit=30" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)

result = c.get_im_chat(
    "Telegram",
    "-1003065442080",
    messageId="31",
    limit=30
)

print(result)

Response

{
  "data": {
    "total": 25,
    "hits": [
      {
        "userId": 1595126601,
        "username": "user123",
        "channelId": -1002018436281,
        "messageId": "-1002018436281_85",
        "message": "Hello everyone!",
        "channelTitle": "Crypto News",
        "languages": [
          {
            "language": "en",
            "probability": 0.98
          }
        ],
        "sha1sum": "a1b2c3d4e5f6...",
        "sha256sum": "1a2b3c4d5e6f...",
        "media": null,
        "detectionDate": "2024-05-16T15:30:22Z",
        "platform": "telegram"
      }
    ],
    "prev_cursor": null,
    "next_cursor": null
  },
  "error": null
}

Get IM Profile by User ID

GET/api/v2/im/{platform}/profile/{userId}

Get information from a user on the specified platform.

Parameters

Name	Type	Required	Description
`platform`	string	Yes	Platform name (`Telegram` or `Discord`)
`userId`	string	Yes	User identifier

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/Telegram/profile/1595126601" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)
result = c.get_im_profile("Telegram", "1595116601")

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "userId": 1595126601,
        "usernames": ["user123", "oldusername"],
        "firstName": ["John"],
        "lastName": ["Doe"],
        "bot": false,
        "detectionDate": "2024-05-16T15:30:22Z",
        "profilePhoto": ["https://example.com/photo.jpg"],
        "platform": "telegram"
      }
    ]
  },
  "error": null
}

Get IM Message by Message ID

GET/api/v2/im/{platform}/message/{messageId}

Get detailed information of a specific message.

Parameters

Name	Type	Required	Description
`platform`	string	Yes	Platform name (`Telegram` or `Discord`)
`messageId`	string	Yes	Message identifier

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/Telegram/message/-1012018336281_85" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)
result = c.get_im_message("Telegram", "-1002018336281_85")

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "userId": 1595126601,
        "username": "user123",
        "channelId": -1002018436281,
        "messageId": "-1012018336281_85",
        "message": "Check out this crypto wallet: bc1q...",
        "channelTitle": "Crypto Discussion",
        "languages": [
          {
            "language": "en",
            "probability": 0.95
          }
        ],
        "sha1sum": "a1b2c3d4e5f6...",
        "sha256sum": "1a2b3c4d5e6f...",
        "media": "image",
        "detectionDate": "2024-05-16T15:30:22Z",
        "platform": "telegram"
      }
    ]
  },
  "error": null
}

Get Channel Info by Channel ID

GET/api/v2/im/{platform}/channel/{channelId}

Get detailed information of a specific channel (Telegram) or channel (Discord).

Parameters

Name	Type	Required	Description
`platform`	string	Yes	Platform name (`Telegram` or `Discord`)
`channelId`	string	Yes	Channel identifier

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/Telegram/channel/-1012018336281" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)
result = c.get_im_channel("Telegram", "-1012018336281")

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "channelId": -1012018336281,
        "channelTitles": ["Crypto News", "Crypto Updates"],
        "detectionDate": "2024-05-16T15:30:22Z",
        "creationDate": "2023-01-15T10:00:00Z",
        "channelPhoto": ["https://example.com/channel_photo.jpg"],
        "platform": "telegram"
      }
    ]
  },
  "error": null
}

Get Server Info by Server ID (Discord)

GET/api/v2/im/{platform}/server/{serverId}

Get detailed information of a specific Discord server.

Parameters

Name	Type	Required	Description
`platform`	string	Yes	Platform name (typically `discord`)
`serverId`	string	Yes	Server identifier

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/discord/server/1031841869195395175" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)
result = c.get_im_server("discord", "1031841869195395175")

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "serverId": 1031841869195395175,
        "serverTitles": ["Gaming Community", "Game Hub"],
        "detectionDate": "2024-05-16T15:30:22Z",
        "creationDate": "2023-03-10T14:20:00Z",
        "serverPhoto": ["https://example.com/server_icon.jpg"]
      }
    ]
  },
  "error": null
}

Search for Email

GET/api/v2/im/email/{email}

Get information about profiles that contain a specific email address found in instant messaging platforms.

Parameters

Name	Type	Required	Description
`email`	string	Yes	Email address to search for
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of results per page
`gte`	string	No	Start date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)
`lte`	string	No	End date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/email/help@coinbase.com" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)
result = c.im_find_email("help@coinbase.com")

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "userId": 1595126601,
        "usernames": ["support_user"],
        "firstName": ["Support"],
        "lastName": null,
        "detectionDate": "2024-09-07T07:36:35.343648",
        "profilePhoto": [],
        "platform": "telegram",
        "email": [
          {
            "value": "help@coinbase.com"
          },
          {
            "value": "no-reply@coinbase.com"
          }
        ],
        "paste": [],
        "skype": [],
        "telegram": [
          {
            "value": "t.me/supportuser"
          }
        ],
        "whatsapp": [],
        "bitcoin_address": [],
        "polkadot_address": [],
        "ethereum_address": [],
        "monero_address": [],
        "ripple_address": [],
        "zcash_address": []
      }
    ]
  },
  "error": null
}

Search for Wallet

GET/api/v2/im/wallet/{chain}/{address}

Get information about profiles that contain a specific cryptocurrency wallet address found in instant messaging platforms.

Parameters

Name	Type	Required	Description
`chain`	string	Yes	Blockchain name (e.g., `BTC`, `ETH`, `XMR`)
`address`	string	Yes	Wallet address to search for
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of results per page
`gte`	string	No	Start date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)
`lte`	string	No	End date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)

Examples

Shell
Python

curl "https://api.vysion.ai/api/v2/im/wallet/BTC/bc1q026rl6hjkdywnsrtva26mq2w0avs9k850ew2d6" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key=API_KEY)
result = c.im_find_wallet("BTC", "bc1q026rl6hjkdywnsrtva26mq2w0avs9k850ew2d6")

print(result)

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "userId": 1595126601,
        "usernames": ["crypto_trader"],
        "firstName": ["Alex"],
        "lastName": ["Smith"],
        "detectionDate": "2024-09-07T07:36:35.343648",
        "profilePhoto": [],
        "platform": "telegram",
        "email": [],
        "paste": [],
        "skype": [],
        "telegram": [],
        "whatsapp": [],
        "bitcoin_address": [
          {
            "value": "bc1qpdq8q5wxtxkkdzjy83gc8e94lcke7pecur2f6w"
          },
          {
            "value": "bc1q026rl6hjkdywnsrtva26mq2w0avs9k850ew2d6"
          }
        ],
        "polkadot_address": [],
        "ethereum_address": [],
        "monero_address": [],
        "ripple_address": [],
        "zcash_address": []
      }
    ]
  },
  "error": null
}

Response Schemas

Message Hit Schema

Field	Type	Description
`userId`	integer/string	User identifier
`username`	string	Username on the platform
`channelId`	integer/string	Channel identifier
`messageId`	string	Unique message identifier
`message`	string	Message content
`channelTitle`	string	Channel or group name
`languages`	array	Detected languages with confidence scores
`sha1sum`	string	SHA1 hash of the message content
`sha256sum`	string	SHA256 hash of the message content
`media`	string	Media type if message contains media
`detectionDate`	string	When the message was detected (ISO 8601)
`serverId`	string	Discord server ID (Discord only)
`serverTitle`	string	Discord server title (Discord only)
`platform`	string	Platform name

Profile Hit Schema

Field	Type	Description
`userId`	integer	User identifier
`usernames`	array	List of known usernames
`firstName`	array	List of known first names
`lastName`	array	List of known last names
`detectionDate`	string	When the profile was detected (ISO 8601)
`profilePhoto`	array	List of profile photo URLs
`platform`	string	Platform name
`email`	array	Associated email addresses
`telegram`	array	Associated Telegram handles
`whatsapp`	array	Associated WhatsApp numbers
`bitcoin_address`	array	Associated Bitcoin addresses
`ethereum_address`	array	Associated Ethereum addresses
`monero_address`	array	Associated Monero addresses
`ripple_address`	array	Associated Ripple addresses
`zcash_address`	array	Associated Zcash addresses
`polkadot_address`	array	Associated Polkadot addresses

Channel/Server Hit Schema

Field	Type	Description
`channelId`/`serverId`	integer	Channel or server identifier
`channelTitles`/`serverTitles`	array	List of known titles/names
`detectionDate`	string	When detected (ISO 8601)
`creationDate`	string	When created (ISO 8601)
`channelPhoto`/`serverPhoto`	array	List of photo/icon URLs

Supported Platforms

Platform	Description	Supported Features
`Telegram`	Telegram messaging platform	Channels, groups, users, messages
`Discord`	Discord chat platform	Servers, channels, users, messages

Error Responses

IM endpoints may return these error codes:

Status	Error Code	Description
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
422	Unprocessable Entity	Invalid parameters
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error