Team Notifications API

The Team Notifications API provides read-only access to agent action logs and team notifications. This API allows you to track what actions your AI agents took to resolve customer queries, including emails sent, Slack messages, API calls, tool usage, and other automated actions performed by agents during query resolution.

Authentication

All endpoints require API key authentication via the x-api-key header.

curl -H "x-api-key: YOUR_API_KEY" https://api.aloochat.ai/team-notifications

Base URL

https://api.aloochat.ai/team-notifications

Endpoints

List Agent Action Notifications

Retrieve a paginated list of agent action notifications showing what actions agents took to resolve customer queries.

Endpoint: GET /team-notifications

Query Parameters:

skip (integer, optional): Number of notifications to skip (default: 0)
limit (integer, optional): Maximum number of notifications to return (default: 50, max: 100)
notification_type (string, optional): Filter by notification type (agent_action, email_sent, slack_message, api_call, tool_usage, system)
agent_id (string, optional): Filter by specific agent ID
query_id (string, optional): Filter by customer support query ID
priority (string, optional): Filter by priority (low, medium, high, urgent)
status (string, optional): Filter by status (unread, read, archived)
sender_id (string, optional): Filter by sender user ID
start_date (string, optional): Filter notifications created after this date (ISO 8601 format)
end_date (string, optional): Filter notifications created before this date (ISO 8601 format)

curl -X GET "https://api.aloochat.ai/team-notifications?limit=10&notification_type=agent_action" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://api.aloochat.ai/team-notifications?limit=10&notification_type=agent_action', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const notifications = await response.json();
console.log(notifications);

import requests
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
params = {
    'limit': 10,
    'notification_type': 'agent_action'
}
 
response = requests.get(
    'https://api.aloochat.ai/team-notifications',
    headers=headers,
    params=params
)
 
notifications = response.json()
print(notifications)

Response:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "company_id": "123e4567-e89b-12d3-a456-426614174001",
      "sender_id": "123e4567-e89b-12d3-a456-426614174002",
      "notification_type": "email_sent",
      "priority": "medium",
      "status": "unread",
      "title": "Agent sent email to customer",
      "message": "Support Agent sent follow-up email to customer regarding billing inquiry #12345",
      "metadata": {
        "agent_id": "123e4567-e89b-12d3-a456-426614174008",
        "query_id": "123e4567-e89b-12d3-a456-426614174009",
        "action_type": "email_sent",
        "recipient_email": "customer@example.com",
        "email_subject": "Follow-up on your billing inquiry",
        "tool_used": "email_tool",
        "execution_time": "2.3s"
      },
      "action_url": "https://app.aloochat.ai/queries/123e4567-e89b-12d3-a456-426614174009",
      "expires_at": "2024-01-15T06:00:00Z",
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "sender": {
        "id": "123e4567-e89b-12d3-a456-426614174008",
        "email": "agent@aloochat.ai",
        "name": "Support Agent"
      },
      "recipients": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174003",
          "notification_id": "123e4567-e89b-12d3-a456-426614174000",
          "user_id": "123e4567-e89b-12d3-a456-426614174004",
          "status": "unread",
          "read_at": null,
          "user": {
            "id": "123e4567-e89b-12d3-a456-426614174004",
            "email": "user@example.com",
            "name": "John Doe"
          }
        }
      ]
    }
  ],
  "total": 25,
  "skip": 0,
  "limit": 10
}

Get Notification Details

Retrieve detailed information about a specific notification.

Endpoint: GET /team-notifications/{notification_id}

curl -X GET "https://api.aloochat.ai/team-notifications/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: YOUR_API_KEY"

const notificationId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.aloochat.ai/team-notifications/${notificationId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const notification = await response.json();
console.log(notification);

import requests
 
notification_id = '123e4567-e89b-12d3-a456-426614174000'
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    f'https://api.aloochat.ai/team-notifications/{notification_id}',
    headers=headers
)
 
notification = response.json()
print(notification)

Get User Notifications

Retrieve notifications for a specific user with their read status.

Endpoint: GET /team-notifications/users/{user_id}

Query Parameters:

skip (integer, optional): Number of notifications to skip (default: 0)
limit (integer, optional): Maximum number of notifications to return (default: 50, max: 100)
status (string, optional): Filter by user’s read status (unread, read, archived)
notification_type (string, optional): Filter by notification type
priority (string, optional): Filter by priority

curl -X GET "https://api.aloochat.ai/team-notifications/users/123e4567-e89b-12d3-a456-426614174004?status=unread" \
  -H "x-api-key: YOUR_API_KEY"

const userId = '123e4567-e89b-12d3-a456-426614174004';
const response = await fetch(`https://api.aloochat.ai/team-notifications/users/${userId}?status=unread`, {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const userNotifications = await response.json();
console.log(userNotifications);

import requests
 
user_id = '123e4567-e89b-12d3-a456-426614174004'
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
params = {'status': 'unread'}
 
response = requests.get(
    f'https://api.aloochat.ai/team-notifications/users/{user_id}',
    headers=headers,
    params=params
)
 
user_notifications = response.json()
print(user_notifications)

Update User Notification Status

Update the read status of a notification for a specific user.

Endpoint: PATCH /team-notifications/{notification_id}/users/{user_id}/status

Request Body:

{
  "status": "read"
}

curl -X PATCH "https://api.aloochat.ai/team-notifications/123e4567-e89b-12d3-a456-426614174000/users/123e4567-e89b-12d3-a456-426614174004/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "read"}'

const notificationId = '123e4567-e89b-12d3-a456-426614174000';
const userId = '123e4567-e89b-12d3-a456-426614174004';
 
const response = await fetch(`https://api.aloochat.ai/team-notifications/${notificationId}/users/${userId}/status`, {
  method: 'PATCH',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'read'
  })
});
 
const result = await response.json();
console.log(result);

import requests
 
notification_id = '123e4567-e89b-12d3-a456-426614174000'
user_id = '123e4567-e89b-12d3-a456-426614174004'
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
data = {'status': 'read'}
 
response = requests.patch(
    f'https://api.aloochat.ai/team-notifications/{notification_id}/users/{user_id}/status',
    headers=headers,
    json=data
)
 
result = response.json()
print(result)

Get Notification Statistics

Retrieve statistics about team notifications.

Endpoint: GET /team-notifications/stats

Query Parameters:

start_date (string, optional): Start date for statistics (ISO 8601 format)
end_date (string, optional): End date for statistics (ISO 8601 format)
user_id (string, optional): Get statistics for a specific user

curl -X GET "https://api.aloochat.ai/team-notifications/stats" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://api.aloochat.ai/team-notifications/stats', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const stats = await response.json();
console.log(stats);

import requests
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    'https://api.aloochat.ai/team-notifications/stats',
    headers=headers
)
 
stats = response.json()
print(stats)

Response:

{
  "total_notifications": 150,
  "unread_count": 25,
  "read_count": 100,
  "archived_count": 25,
  "by_type": {
    "system": 50,
    "user": 30,
    "agent": 40,
    "deployment": 20,
    "billing": 5,
    "security": 5
  },
  "by_priority": {
    "low": 60,
    "medium": 70,
    "high": 15,
    "urgent": 5
  }
}

Notification Types

agent_action: General agent actions during query resolution
email_sent: Agent sent an email to customer or team member
slack_message: Agent sent a Slack message
api_call: Agent made an API call to external service
tool_usage: Agent used a specific tool (CRM, ticketing system, etc.)
system: System-wide notifications and announcements

Priority Levels

low: General information, non-urgent updates
medium: Standard notifications requiring attention
high: Important notifications requiring prompt attention
urgent: Critical notifications requiring immediate action

Status Values

unread: Notification has not been read by the user
read: Notification has been read by the user
archived: Notification has been archived by the user

Error Handling

The API returns standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing API key
403 Forbidden: Access denied
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Error responses include details:

{
  "error": "ValidationError",
  "message": "Invalid notification_type parameter",
  "statusCode": 400,
  "timestamp": "2024-01-10T10:00:00Z",
  "path": "/team-notifications"
}

Rate Limiting

API requests are rate-limited to prevent abuse. Current limits:

1000 requests per hour per API key
Burst limit of 100 requests per minute

Best Practices

Pagination: Use skip and limit parameters for large datasets
Filtering: Apply filters to reduce response size and improve performance
Caching: Cache notification data when appropriate to reduce API calls
Error Handling: Implement proper error handling for all API calls
Status Updates: Regularly update notification status to maintain accurate read states

Use Cases

Agent Action Tracking Dashboard

// Fetch recent agent actions for monitoring
async function getRecentAgentActions() {
  const response = await fetch('https://api.aloochat.ai/team-notifications?notification_type=agent_action&limit=50', {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  });
  return response.json();
}
 
// Track actions for specific query
async function getQueryActions(queryId) {
  const response = await fetch(`https://api.aloochat.ai/team-notifications?query_id=${queryId}`, {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  });
  return response.json();
}
 
// Mark notification as read when user reviews action
async function markActionAsReviewed(notificationId, userId) {
  await fetch(`https://api.aloochat.ai/team-notifications/${notificationId}/users/${userId}/status`, {
    method: 'PATCH',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ status: 'read' })
  });
}

Agent Performance Analytics

import requests
from datetime import datetime, timedelta
 
def analyze_agent_actions(agent_id=None):
    """Analyze agent actions and performance"""
    end_date = datetime.now()
    start_date = end_date - timedelta(days=30)
    
    params = {
        'start_date': start_date.isoformat(),
        'end_date': end_date.isoformat(),
        'notification_type': 'agent_action'
    }
    
    if agent_id:
        params['agent_id'] = agent_id
    
    response = requests.get(
        'https://api.aloochat.ai/team-notifications/stats',
        headers={'x-api-key': 'YOUR_API_KEY'},
        params=params
    )
    
    stats = response.json()
    print(f"Agent actions in last 30 days: {stats['total_notifications']}")
    print(f"Actions by type: {stats['by_type']}")
    
    # Get detailed actions
    actions_response = requests.get(
        'https://api.aloochat.ai/team-notifications',
        headers={'x-api-key': 'YOUR_API_KEY'},
        params=params
    )
    
    actions = actions_response.json()
    
    # Analyze tool usage
    tool_usage = {}
    for action in actions['data']:
        tool = action['metadata'].get('tool_used', 'unknown')
        tool_usage[tool] = tool_usage.get(tool, 0) + 1
    
    print(f"Tool usage: {tool_usage}")
    return stats, tool_usage
 
# Track query resolution actions
def track_query_resolution(query_id):
    """Track all actions taken to resolve a specific query"""
    response = requests.get(
        f'https://api.aloochat.ai/team-notifications?query_id={query_id}',
        headers={'x-api-key': 'YOUR_API_KEY'}
    )
    
    actions = response.json()
    
    print(f"Actions taken for query {query_id}:")
    for action in actions['data']:
        print(f"- {action['title']} ({action['notification_type']})")
        print(f"  Tool: {action['metadata'].get('tool_used', 'N/A')}")
        print(f"  Time: {action['created_at']}")
    
    return actions

Customer Support Workflow