# Message Box API

Endpoint for external systems to push messages into API Connect's Message Box, where help desk agents can claim, resolve, reject, or spawn a ticket from them.

## Receiving a Message

```
POST https://connect.apinet.com/do/messageboxReceive
Content-Type: application/json
```

No session/cookie auth is required — this endpoint is intended for server-to-server calls. Authentication is a shared secret included in the request body.

### Request Body

```json
{
  "auth": "<shared secret>",
  "pk_system": 1,
  "source_name": "OrderSystem",
  "message_type": "order.created",
  "content": {
    "orderId": 123,
    "customer": "Acme Co"
  }
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `auth` | string | yes | Shared secret. Contact API Connect to obtain the current value. |
| `pk_system` | integer | yes | The system ID this message is for (must be a known/existing system in API Connect). |
| `source_name` | string | yes | Name of the sending system/integration, shown to agents (e.g. `"OrderSystem"`). |
| `message_type` | string | yes | Free-form string identifying the kind of message (e.g. `"order.created"`, `"support.escalation"`). No fixed enum — pick something descriptive and consistent per integration. |
| `content` | object \| array \| string \| number | yes | Arbitrary JSON payload with the message details. Stored as-is and shown to agents. |

Fields may be sent as top-level JSON body properties (as above), or as standard form fields (`application/x-www-form-urlencoded` / multipart) — either works.

### Response

Success:
```json
{
  "status": "success",
  "message": "",
  "pk_messagebox_message": 1
}
```

Error (bad/missing `auth`, unknown `pk_system`, or missing required field):
```json
{
  "status": "error",
  "message": "Unauthorized."
}
```

Other possible `message` values: `"Unknown pk_system."`, `"source_name, message_type, and content are required."`, `"Error recording message."`

### Example

```bash
curl -X POST https://connect.apinet.com/do/messageboxReceive \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "<shared secret>",
    "pk_system": 1,
    "source_name": "OrderSystem",
    "message_type": "order.created",
    "content": { "orderId": 123, "customer": "Acme Co" }
  }'
```

## Agent Workflow (for context, not called externally)

Once received, a message goes through this lifecycle, visible/actionable at `/{pk_system}/messagebox`:

1. **New** — unclaimed, visible to all agents.
2. **Claimed** — an agent has taken ownership.
3. **Resolved** — handled, optionally with a ticket spawned from it (`fk_ticket` set).
4. **Rejected** — dismissed, no action taken.

There is currently no endpoint for external systems to query message status or receive callbacks — this is a one-way ingest API.