Custom Channel Integration

Use the private employee message API when an external chat system needs to send user messages to an Alloy AI teammate. This API is intended for custom corporate messengers, internal chat tools, support systems, or middleware that receives messages from another chat provider.

Base URL:

```text {api_url}/api/private/employee ```

Authenticate every request with your organization private API key. Send the key in one of these headers:

Missing or invalid keys return `401` with `{ "error": "Unauthorized access" }`.

Each request must include a `channel` value. Treat it as the stable identifier of your external chat system, for example `corporate-messenger`, `intranet-chat`, or `support-portal`.

For an ongoing chat, also send:

• `conversation.id`: the chat, room, thread, or dialog ID from your system.
• `contact.id`: the sender's user ID from your system.

Use the same `channel`, `conversation.id`, and `contact.id` on later requests so Alloy can continue the same chat history.

```text POST /api/private/employee/{employee_id}/messages ```

Sends one user message to an AI teammate and waits for the AI response.

`{employee_id}` is the AI teammate ID.

Request body

`conversation` and `contact` are all-or-nothing. Sending only one of them returns `400`.

Attachment item

Attachments are saved only for saved chats, meaning requests that include both `conversation` and `contact`. If decoded file size does not match `size`, the request returns `400`.

Saved chat vs one-off request

Use a saved chat when your external system has a conversation that should remain visible and continue over time:

• include both `conversation` and `contact`
• Alloy saves the incoming message
• Alloy can reuse the same chat on later calls when you send the same identifiers
• the response includes the saved incoming `messageId`

Use a one-off request when you only need an immediate answer and do not want to save chat history:

• omit both `conversation` and `contact`
• Alloy returns an AI response for that single message
• the response has `messageId: null`

Response

```json { "success": true, "data": { "runId": "workflow-run-id", "message": "AI teammate response", "messageId": "saved-incoming-message-id-or-null" } } ```

Errors

Example: one-off request

```bash curl -X POST "{api_url}/api/private/employee/{employee_id}/messages" -H "Authorization: Bearer {private_api_key}" -H "Content-Type: application/json" -d '{ "channel": "corporate-messenger", "message": "What is our PTO policy?" }' ```

Example: saved chat

```bash curl -X POST "{api_url}/api/private/employee/{employee_id}/messages" -H "Authorization: Bearer {private_api_key}" -H "Content-Type: application/json" -d '{ "channel": "corporate-messenger", "message": "I need help with invoice 123", "conversation": { "id": "room-42", "thread_id": null, "title": "Finance support" }, "contact": { "id": "user-777", "first_name": "Alex", "last_name": "Customer" } }' ```

Example: saved chat with attachment

```bash curl -X POST "{api_url}/api/private/employee/{employee_id}/messages" -H "api-key: {private_api_key}" -H "Content-Type: application/json" -d '{ "channel": "corporate-messenger", "message": "Here is the screenshot", "conversation": { "id": "room-42" }, "contact": { "id": "user-777" }, "attachments": [ { "name": "screenshot.png", "mime_type": "image/png", "size": 20482, "data": "iVBORw0KGgo..." } ] }' ```

```text GET /api/private/employee/{employee_id}/messages ```

Returns saved messages for a conversation previously used with `POST`.

Query parameters

Response

```json { "success": true, "data": [ { "id": "message-id", "conversationId": "conversation-id", "threadId": null, "content": "I need help with invoice 123", "type": "text", "sender": "customer", "status": "sent", "timestamp": 1780000000000 } ], "pagination": { "page": 1, "limit": 30, "total": 1, "totalPages": 1, "has_more": false } } ```

Message objects can include additional fields such as attachments, reply references, reaction state, sender display name, and timestamps.

Errors

Example

```bash curl "{api_url}/api/private/employee/{employee_id}/messages?channel=corporate-messenger&conversation_id=room-42&page=1&limit=30" -H "api-key: {private_api_key}" ```

A custom messenger bridge usually does this:

1. Receive a user message from the external chat system.
2. Convert the source chat system name to a stable `channel` value.
3. Convert the external chat ID to `conversation.id`.
4. Convert the external sender ID and name to `contact`.
5. Call `POST /api/private/employee/{employee_id}/messages`.
6. Send `data.message` from the Alloy response back to the external chat system.
7. Use `GET /api/private/employee/{employee_id}/messages` only when your integration needs to reload saved history.

This API is synchronous. The response body is the delivery path back to the external chat system; this route does not register an outbound webhook for custom channels.