# Agent Messaging & Communication API Documentation

This document provides API documentation for the Messaging & Communication features of the Agent Module.

## Base URL

All endpoints are relative to the base URL of your application.

## Authentication

All endpoints require authentication. Include the authentication token in the request header:

```
Authorization: Bearer {token}
```

## Endpoints

### Messages

#### List Messages (Inbox)

Retrieves a list of received messages.

**URL**: `/api/agent/messages/inbox`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| search    | string | No       | Search term to filter messages by subject or content |
| is_read   | bool   | No       | Filter by read status                            |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "sender": {
        "id": 2,
        "name": "Admin User",
        "role": "admin"
      },
      "subject": "Welcome to the Agent Portal",
      "message_preview": "Welcome to the Agent Portal! We're excited to have you...",
      "is_read": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "sender": {
        "id": 3,
        "name": "Support Team",
        "role": "admin"
      },
      "subject": "New Marketing Materials Available",
      "message_preview": "We've added new marketing materials to the library...",
      "is_read": false,
      "created_at": "2023-01-05T00:00:00Z",
      "updated_at": "2023-01-05T00:00:00Z"
    },
    // More messages...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "/api/agent/messages/inbox",
    "per_page": 10,
    "to": 10,
    "total": 25,
    "unread_count": 5
  }
}
```

#### List Messages (Sent)

Retrieves a list of sent messages.

**URL**: `/api/agent/messages/sent`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| search    | string | No       | Search term to filter messages by subject or content |

**Response**:

```json
{
  "data": [
    {
      "id": 3,
      "recipient": {
        "id": 2,
        "name": "Admin User",
        "role": "admin"
      },
      "subject": "Question about Referrals",
      "message_preview": "I have a question about the referral process...",
      "created_at": "2023-01-10T00:00:00Z",
      "updated_at": "2023-01-10T00:00:00Z"
    },
    {
      "id": 4,
      "recipient": {
        "id": 3,
        "name": "Support Team",
        "role": "admin"
      },
      "subject": "Marketing Material Request",
      "message_preview": "I would like to request a new marketing material...",
      "created_at": "2023-01-15T00:00:00Z",
      "updated_at": "2023-01-15T00:00:00Z"
    },
    // More messages...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "path": "/api/agent/messages/sent",
    "per_page": 10,
    "to": 10,
    "total": 15
  }
}
```

#### Get Message

Retrieves a specific message.

**URL**: `/api/agent/messages/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the message         |

**Response**:

```json
{
  "data": {
    "id": 1,
    "sender": {
      "id": 2,
      "name": "Admin User",
      "role": "admin"
    },
    "recipient": {
      "id": 1,
      "name": "Agent User",
      "role": "agent"
    },
    "subject": "Welcome to the Agent Portal",
    "message": "Welcome to the Agent Portal!\n\nWe're excited to have you join our team. This portal provides you with all the tools you need to succeed as an agent.\n\nHere are some resources to get started:\n- Training materials in the Training section\n- Marketing materials in the Marketing section\n- Goal setting tools in the Goals section\n\nIf you have any questions, feel free to reply to this message.\n\nBest regards,\nAdmin Team",
    "is_read": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

#### Send Message

Sends a new message.

**URL**: `/api/agent/messages`

**Method**: `POST`

**Request Body**:

```json
{
  "recipient_id": 2,
  "subject": "Question about Commission Rates",
  "message": "Hello,\n\nI have a question about the commission rates for referrals. Can you please clarify how the tiered commission structure works?\n\nThank you,\nAgent"
}
```

**Response**:

```json
{
  "message": "Message sent successfully",
  "data": {
    "id": 5,
    "sender_id": 1,
    "recipient_id": 2,
    "subject": "Question about Commission Rates",
    "message": "Hello,\n\nI have a question about the commission rates for referrals. Can you please clarify how the tiered commission structure works?\n\nThank you,\nAgent",
    "is_read": false,
    "created_at": "2023-01-21T10:00:00Z",
    "updated_at": "2023-01-21T10:00:00Z"
  }
}
```

#### Reply to Message

Replies to an existing message.

**URL**: `/api/agent/messages/{id}/reply`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the message to reply to |

**Request Body**:

```json
{
  "message": "Thank you for the information. I have another question: how do I track my referrals?"
}
```

**Response**:

```json
{
  "message": "Reply sent successfully",
  "data": {
    "id": 6,
    "sender_id": 1,
    "recipient_id": 2,
    "subject": "Re: Welcome to the Agent Portal",
    "message": "Thank you for the information. I have another question: how do I track my referrals?",
    "is_read": false,
    "created_at": "2023-01-21T11:00:00Z",
    "updated_at": "2023-01-21T11:00:00Z"
  }
}
```

#### Mark Message as Read

Marks a message as read.

**URL**: `/api/agent/messages/{id}/read`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the message         |

**Response**:

```json
{
  "message": "Message marked as read",
  "data": {
    "id": 2,
    "is_read": true,
    "updated_at": "2023-01-21T12:00:00Z"
  }
}
```

#### Mark All Messages as Read

Marks all unread messages as read.

**URL**: `/api/agent/messages/read-all`

**Method**: `POST`

**Response**:

```json
{
  "message": "All messages marked as read",
  "data": {
    "count": 5
  }
}
```

#### Delete Message

Deletes a message.

**URL**: `/api/agent/messages/{id}`

**Method**: `DELETE`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the message         |

**Response**:

```json
{
  "message": "Message deleted successfully"
}
```

### Announcements

#### List Announcements

Retrieves a list of announcements.

**URL**: `/api/agent/announcements`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| is_read   | bool   | No       | Filter by read status                            |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "title": "New Commission Structure",
      "content_preview": "We're excited to announce a new commission structure...",
      "priority": "high",
      "is_read": true,
      "publish_at": "2023-01-01T00:00:00Z",
      "expires_at": "2023-02-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "title": "System Maintenance",
      "content_preview": "The system will be down for maintenance on...",
      "priority": "medium",
      "is_read": false,
      "publish_at": "2023-01-10T00:00:00Z",
      "expires_at": "2023-01-20T00:00:00Z",
      "created_at": "2023-01-10T00:00:00Z",
      "updated_at": "2023-01-10T00:00:00Z"
    },
    // More announcements...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "/api/agent/announcements",
    "per_page": 10,
    "to": 2,
    "total": 2,
    "unread_count": 1
  }
}
```

#### Get Announcement

Retrieves a specific announcement.

**URL**: `/api/agent/announcements/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the announcement    |

**Response**:

```json
{
  "data": {
    "id": 1,
    "title": "New Commission Structure",
    "content": "We're excited to announce a new commission structure that will take effect on February 1, 2023.\n\nThe new structure includes higher rates for top performers and additional bonuses for referrals that convert to premium subscriptions.\n\nPlease review the attached document for full details.",
    "priority": "high",
    "is_read": true,
    "read_at": "2023-01-02T10:30:00Z",
    "publish_at": "2023-01-01T00:00:00Z",
    "expires_at": "2023-02-01T00:00:00Z",
    "attachments": [
      {
        "id": 1,
        "filename": "commission_structure_2023.pdf",
        "url": "https://example.com/attachments/commission_structure_2023.pdf",
        "size": 1024000,
        "created_at": "2023-01-01T00:00:00Z"
      }
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

#### Mark Announcement as Read

Marks an announcement as read.

**URL**: `/api/agent/announcements/{id}/read`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the announcement    |

**Response**:

```json
{
  "message": "Announcement marked as read",
  "data": {
    "id": 2,
    "is_read": true,
    "read_at": "2023-01-21T12:00:00Z"
  }
}
```

### Support Tickets

#### List Support Tickets

Retrieves a list of support tickets.

**URL**: `/api/agent/support`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| status    | string | No       | Filter by status (open, closed)                  |
| priority  | string | No       | Filter by priority (low, medium, high)           |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "subject": "Login Issue",
      "description_preview": "I'm having trouble logging in to the portal...",
      "status": "closed",
      "priority": "high",
      "category": "technical",
      "reply_count": 3,
      "created_at": "2023-01-05T00:00:00Z",
      "updated_at": "2023-01-07T00:00:00Z",
      "resolved_at": "2023-01-07T00:00:00Z"
    },
    {
      "id": 2,
      "subject": "Commission Question",
      "description_preview": "I have a question about my recent commission payment...",
      "status": "open",
      "priority": "medium",
      "category": "billing",
      "reply_count": 1,
      "created_at": "2023-01-15T00:00:00Z",
      "updated_at": "2023-01-16T00:00:00Z",
      "resolved_at": null
    },
    // More tickets...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "/api/agent/support",
    "per_page": 10,
    "to": 2,
    "total": 2,
    "open_count": 1,
    "closed_count": 1
  }
}
```

#### Get Support Ticket

Retrieves a specific support ticket.

**URL**: `/api/agent/support/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the support ticket  |

**Response**:

```json
{
  "data": {
    "id": 1,
    "subject": "Login Issue",
    "description": "I'm having trouble logging in to the portal. When I enter my credentials, I get an error message saying 'Invalid credentials'. I've tried resetting my password but I'm still having the same issue.",
    "status": "closed",
    "priority": "high",
    "category": "technical",
    "resolved_at": "2023-01-07T00:00:00Z",
    "created_at": "2023-01-05T00:00:00Z",
    "updated_at": "2023-01-07T00:00:00Z",
    "replies": [
      {
        "id": 1,
        "user": {
          "id": 2,
          "name": "Support Team",
          "role": "admin"
        },
        "message": "Thank you for reporting this issue. Can you please provide your username so we can investigate?",
        "is_internal": false,
        "created_at": "2023-01-05T12:00:00Z"
      },
      {
        "id": 2,
        "user": {
          "id": 1,
          "name": "Agent User",
          "role": "agent"
        },
        "message": "My username is agent_user_1.",
        "is_internal": false,
        "created_at": "2023-01-06T09:00:00Z"
      },
      {
        "id": 3,
        "user": {
          "id": 2,
          "name": "Support Team",
          "role": "admin"
        },
        "message": "Thank you for providing your username. We've identified the issue and fixed it. Please try logging in again.",
        "is_internal": false,
        "created_at": "2023-01-07T00:00:00Z"
      }
    ]
  }
}
```

#### Create Support Ticket

Creates a new support ticket.

**URL**: `/api/agent/support`

**Method**: `POST`

**Request Body**:

```json
{
  "subject": "Marketing Material Issue",
  "description": "I'm having trouble downloading the marketing materials. When I click the download button, nothing happens.",
  "priority": "medium",
  "category": "technical"
}
```

**Response**:

```json
{
  "message": "Support ticket created successfully",
  "data": {
    "id": 3,
    "subject": "Marketing Material Issue",
    "description": "I'm having trouble downloading the marketing materials. When I click the download button, nothing happens.",
    "status": "open",
    "priority": "medium",
    "category": "technical",
    "created_at": "2023-01-21T13:00:00Z",
    "updated_at": "2023-01-21T13:00:00Z"
  }
}
```

#### Reply to Support Ticket

Adds a reply to a support ticket.

**URL**: `/api/agent/support/{id}/reply`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the support ticket  |

**Request Body**:

```json
{
  "message": "I've tried clearing my browser cache and cookies, but I'm still having the same issue."
}
```

**Response**:

```json
{
  "message": "Reply added successfully",
  "data": {
    "id": 4,
    "ticket_id": 3,
    "user_id": 1,
    "message": "I've tried clearing my browser cache and cookies, but I'm still having the same issue.",
    "is_internal": false,
    "created_at": "2023-01-21T14:00:00Z",
    "updated_at": "2023-01-21T14:00:00Z"
  }
}
```

#### Close Support Ticket

Closes a support ticket.

**URL**: `/api/agent/support/{id}/close`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the support ticket  |

**Response**:

```json
{
  "message": "Support ticket closed successfully",
  "data": {
    "id": 3,
    "status": "closed",
    "resolved_at": "2023-01-21T15:00:00Z",
    "updated_at": "2023-01-21T15:00:00Z"
  }
}
```

#### Reopen Support Ticket

Reopens a closed support ticket.

**URL**: `/api/agent/support/{id}/reopen`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the support ticket  |

**Response**:

```json
{
  "message": "Support ticket reopened successfully",
  "data": {
    "id": 3,
    "status": "open",
    "resolved_at": null,
    "updated_at": "2023-01-21T16:00:00Z"
  }
}
```

## Error Responses

### 401 Unauthorized

```json
{
  "error": "Unauthorized",
  "message": "Authentication token is invalid or expired"
}
```

### 403 Forbidden

```json
{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}
```

### 404 Not Found

```json
{
  "error": "Not Found",
  "message": "The requested resource was not found"
}
```

### 422 Validation Error

```json
{
  "error": "Validation Error",
  "message": "The given data was invalid",
  "errors": {
    "subject": [
      "The subject field is required"
    ],
    "message": [
      "The message field is required"
    ]
  }
}
```

### 500 Server Error

```json
{
  "error": "Server Error",
  "message": "An unexpected error occurred"
}
```