WhatsApp Messaging
Send and receive WhatsApp messages via a self-hosted Waha container. All four tools are automatically hidden when WhatsApp is not configured.
Requires: A running Waha Docker container. See WhatsApp Setup for configuration.
whatsapp_send
Send a text message via WhatsApp.
Requires Confirmation: Yes (configurable)
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient — phone number in E.164 format (e.g. +14155551234) or a phonebook nickname (e.g. alice) |
message | string | Yes | Text message body (max 4096 chars) |
Returns: Confirmation with message ID, or error/block reason
Example:
whatsapp_send(to="alice", message="Meeting moved to 3pm")whatsapp_send_image
Send an image via WhatsApp given a public URL.
Requires Confirmation: Yes (configurable)
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient — phone number or phonebook nickname |
image_url | string | Yes | Public URL of the image (JPEG preferred) |
caption | string | No | Optional caption text |
Returns: Confirmation with message ID, or error/block reason
whatsapp_check
Retrieve recent WhatsApp messages. Optionally filter by a specific contact.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
contact | string | No | All chats | Phone number or phonebook nickname to filter by |
limit | int | No | 10 | Number of recent messages (max 50) |
Returns: Formatted list of recent messages with sender, timestamp, and body
whatsapp_contacts
List the configured phonebook contacts and active filter rules.
Parameters: None
Returns: Phonebook listing with nicknames, phone numbers, and filter mode
Contact Filtering
WhatsApp tools enforce contact restrictions before any message is sent or received:
| Filter Mode | Behavior |
|---|---|
none (default) | All contacts allowed |
allow | Only contacts in the list can send/receive (legacy value whitelist is auto-mapped to allow) |
ignore | Skip listed contacts — no response sent, message kept on the platform |
blacklist | Contacts in the list are blocked (message deleted, chat archived) |
Phonebook nicknames (e.g. "alice") are resolved to E.164 numbers automatically and are case-insensitive.
Rate Limiting
Outbound messages are rate-limited to prevent abuse. Default: 30 messages/hour (configurable, 0 = unlimited). The limit uses an in-memory sliding window that resets on process restart.
Telegram Messaging
Send and receive Telegram messages via a bot created with @BotFather. All four tools are automatically hidden when the bot token is not configured.
Requires: A bot token (COGTRIX_TELEGRAM_TOKEN environment variable or services.telegram.bot_token in config). See Telegram Setup for configuration.
telegram_send
Send a text message via Telegram.
Requires Confirmation: Yes (configurable)
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient — a chat ID (numeric), @username, or a phonebook nickname (e.g. alice) |
message | string | Yes | Text message body (max 4096 chars) |
Returns: Confirmation with message ID, or error/block reason
Example:
telegram_send(to="alice", message="Meeting moved to 3pm")telegram_send_photo
Send a photo via Telegram given a public URL.
Requires Confirmation: Yes (configurable)
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient — a chat ID, @username, or phonebook nickname |
photo_url | string | Yes | Public URL of the photo |
caption | string | No | Optional caption text |
Returns: Confirmation with message ID, or error/block reason
telegram_check
Retrieve recent Telegram messages sent to the bot.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | int | No | 10 | Number of recent messages (max 50) |
Returns: Formatted list of recent messages with sender, timestamp, chat, and body
telegram_contacts
List the configured phonebook contacts and active filter rules.
Parameters: None
Returns: Phonebook listing with nicknames, chat IDs, and filter mode
Contact Filtering
Telegram tools enforce contact restrictions before any message is sent or received:
| Filter Mode | Behavior |
|---|---|
none (default) | All contacts allowed |
allow | Only contacts in the list can send/receive (legacy value whitelist is auto-mapped to allow) |
ignore | Skip listed contacts — no response sent, message kept on the platform |
blacklist | Contacts in the list are blocked (message deleted) |
Phonebook nicknames are resolved to chat IDs automatically and are case-insensitive.
Rate Limiting
Outbound messages are rate-limited to prevent abuse. Default: 30 messages/hour (configurable, 0 = unlimited). The limit uses an in-memory sliding window that resets on process restart.
Email Tools
read_email
Read emails from an IMAP mailbox.
Configuration: Requires services.email.imap_host, services.email.username, and services.email.password in .cogtrix.yml.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
folder | string | No | Mailbox folder (default: INBOX) |
limit | int | No | Maximum messages to return (default: 10) |
unread_only | bool | No | Return only unread messages (default: false) |
sender | string | No | Filter by sender email address |
subject_contains | string | No | Filter by subject keyword |
Returns: List of emails with sender, subject, date, and body preview.
send_email
Send an email via SMTP.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient email address |
subject | string | Yes | Email subject line |
body | string | Yes | Email body text |
cc | string | No | CC recipient(s), comma-separated |
bcc | string | No | BCC recipient(s), comma-separated |
from | string | No | Sender address (default: configured default) |
Returns: Confirmation with message ID on success, or error on failure.
search_email
Search emails by content across the mailbox.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query (matches subject, body, sender) |
folder | string | No | Mailbox folder to search (default: INBOX) |
limit | int | No | Maximum results (default: 20) |
date_after | string | No | Filter messages after this date (ISO 8601) |
date_before | string | No | Filter messages before this date (ISO 8601) |
Returns: Matching emails with sender, subject, date, and relevance snippet.
Slack Messaging
cogtrix_slack_post_message
Post a message to a Slack channel with automatic markdown-to-mrkdwn conversion. Supports bold, tables, and headings.
Configuration: Requires services.slack.bot_token in .cogtrix.yml.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Slack channel ID (e.g., C0123456789) |
text | string | Yes | Message text (supports markdown) |
blocks | array | No | Optional block structure for rich messaging |
Example:
cogtrix_slack_post_message(
channel="C0123456789",
text="**Task Complete!**\n\nThe analysis is ready. See details in the report."
)Returns: Message timestamp and success status