---
title: Send Message via API
updatedAt: 2026-04-02T15:34:33.000Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# Send Message via API

Send a message to a chat room on behalf of a specific user.

## POST /external/message/send

> ⚠️ **Regional endpoints:** Replace `chatbackend.watchers.io` with the endpoint matching your project region. See [Supported Regions](https://docs.watchers.io/docs/supported-regions) for details.
> | Region | Endpoint |
> | :--- | :--- |
> | Europe (default) | `chatbackend.watchers.io` |
> | North America | `chatbackend.us.watchers.io` |
> | South America | `chatbackend.sa.watchers.io` |
> | Asia | `chatbackend.hk.watchers.io` |
> | Africa | `chatbackend.za.watchers.io` |

### Authentication

This endpoint is available for external integrations only.

Required headers:

```http
X-Api-Key: <API_KEY>
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

* Requires role: EXTERNAL
* `X-Api-Key` is used to resolve the project via the environment service
* `Authorization: Bearer` token is validated against the project's bearer table
* Requests without valid credentials will be rejected

### Request Body

```json
{
  "userId": "string",
  "roomId": "string",
  "text": "string"
}
```

### Fields

| Field  | Type   | Required | Description                        |
| ------ | ------ | -------- | ---------------------------------- |
| userId | string | ✅        | ID of the user sending the message. Must be a non-empty string. |
| roomId | string | ✅        | Target chat room ID. Must be a non-empty string. |
| text   | string | ✅        | Message content. Must be a non-empty string. |

> ⚠️ All fields are validated: empty strings will be rejected with a 400 error.

### How it works

* The message is sent to the specified room
* The message is created as the provided user
* In the UI, it appears exactly like a regular user message

### Success Response

Returns the full message object with all relations:

```json
{
  "id": 12345,
  "text": "Hello from external API",
  "type": "USER",
  "isVisible": true,
  "isPinned": false,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "user": { "id": 1, "externalId": "12345", ... },
  "room": { "id": 1, "externalRoomId": "67890", ... },
  "talker": { "id": 1, ... },
  ...
}
```

### Errors

404 Not Found — invalid API key

```json
{
  "statusCode": 404,
  "message": "Project not found"
}
```

403 Forbidden — missing or invalid bearer token

```json
{
  "statusCode": 403,
  "message": "Bearer token is required"
}
```

```json
{
  "statusCode": 403,
  "message": "Wrong bearer token"
}
```

400 Bad Request — user not found

```json
{
  "statusCode": 400,
  "message": "User {userId} not found"
}
```

400 Bad Request — message creation failed

```json
{
  "statusCode": 400,
  "message": "Could not create message"
}
```

400 Bad Request — validation error (empty or missing fields)

```json
{
  "statusCode": 400,
  "message": ["text must be longer than or equal to 1 characters", ...]
}
```

### Security

* The endpoint is protected against impersonation
* Only authorized integrations can send messages
* `userId` must belong to a valid and accessible context

### Example

```curl
curl -X POST https://chatbackend.watchers.io/external/message/send   -H "X-Api-Key: YOUR_API_KEY"   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "userId": "12345",
    "roomId": "67890",
    "text": "Hello from external API"
  }'
```

### Use cases

* Bots and automated messaging
* External systems (CRM, betting engines, etc.)
* Event-driven messages (notifications, triggers)

### Notes

* This endpoint bypasses UI input and works programmatically
* Recommended for server-to-server integrations