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	No	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

Examples

Shell

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

Python

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",
        "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
}

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
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

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

Python

from vysion import client

c = client.Client(api_key=API_KEY)

result = c.get_im_chat(
    "Telegram",
    "-1001018336281",
    gte="2024-05-16T10:57:58.632466",
    lte="2024-05-16T23:00:00"
)

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"
      }
    ]
  },
  "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

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

Python

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"],
        "detectionDate": "2024-05-16T15:30:22Z",
        "profilePhoto": ["https://example.com/photo.jpg"]
      }
    ]
  },
  "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

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

Python

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"
      }
    ]
  },
  "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

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

Python

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"]
      }
    ]
  },
  "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

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

Python

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

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

Python

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

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

Python

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