Source: https://docs.debitura.com/collection-partners/integration-guides/send-chat-messages

# Send Chat Messages

Send messages to creditors via the Collection Partner API.

<a id="overview"></a>

## Overview

Use `POST /cases/{id}/chats` to send messages to the creditor on a case. This is the programmatic equivalent of typing a message in the Partner Portal chat.

For reading messages (including creditor replies), use [`GET /cases/{id}/chats`](https://docs.debitura.com/api/collection-partner-api/cases.md#fetch-case-chats).

<a id="implementation"></a>

## Implementation

Sending a message requires identifying the sender — the team member who will appear as the author. Identify them with **either** `userEmail` **or** `userId`; at least one is required. Retrieve valid team members from [`GET /users`](https://docs.debitura.com/api/collection-partner-api/users.md#lists-team-members-belonging-to-the-authenticated-collection-par) before calling this endpoint.

```http
POST https://collectionpartner-api.debitura.com/cases/{id}/chats
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "message": "Could you please provide the original signed contract for this case?",
  "userEmail": "collector@agency.com"
}
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | **Yes** | The message text to send to the creditor (1–10,000 characters) |
| `userEmail` | string | **Yes\*** | Email of the active team member who will appear as the sender. Recommended over `userId`. Use `GET /users` to list valid users |
| `userId` | UUID | **Yes\*** | **Deprecated** — legacy alternative to `userEmail`. Still accepted for backwards compatibility |

\* Provide at least one of `userEmail` or `userId` (`userEmail` takes precedence if both are sent). If neither is supplied, the request returns `400` with error `MissingUserIdentifier`.

A successful call returns `200 OK` with the created chat message:

```json
{
  "id": "468d2906-6ba2-4534-b092-dafd54a1131e",
  "dateCreated": "2026-04-07T10:34:35.214Z",
  "dateUpdated": "2026-04-07T10:34:35.214Z",
  "role": 0,
  "roleLabel": "Partner",
  "message": "Could you please provide the original signed contract for this case?",
  "isSeen": false,
  "user": {
    "id": 1400,
    "dateCreated": "2026-01-13T08:30:50.561Z",
    "dateUpdated": "2026-01-13T08:30:50.561Z",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com"
  }
}
```

`roleLabel` names the sender: `Partner`, `Creditor`, or `Managed by partner` (a collection partner acting on behalf of the creditor). These values are stable. `role` carries the same information as a number (`0`, `1`, `2`); it is kept for existing integrations but deprecated, so read `roleLabel` instead.

<a id="what-happens-when-you-send-a-message"></a>

## What Happens When You Send a Message

1.  The message is posted in the case chat thread, attributed to the specified user
2.  The creditor receives an email notification about the new message
3.  For a production `Partner`\-role message, a task is created for the creditor to review. Test/demo messages suppress that task, and a `ManagedByPartner`\-role message routes a task to the collection partner instead.

The creditor can reply through the Debitura portal. Poll [`GET /cases/{id}/chats`](https://docs.debitura.com/api/collection-partner-api/cases.md#fetch-case-chats) to check for replies.

<a id="error-handling"></a>

## Error Handling

| Status | Cause |
| --- | --- |
| `400` | Empty or missing message; message too short or too long; neither `userEmail` nor `userId` provided (`MissingUserIdentifier`); or the resolved user is not an active member of your team |
| `404` | Case not found or not assigned to your agency |
| `500` | Internal server error |

<a id="whats-next"></a>

## What's Next

For the full API reference, see [Send a Chat Message](https://docs.debitura.com/api/collection-partner-api/cases.md#send-a-chat-message-on-a-case). To document collection activities instead of messaging the creditor directly, use [notes](https://docs.debitura.com/api/collection-partner-api/cases.md#create-a-note-on-a-case).