Send Message via API

POST /external/message/send

⚠️

Regional endpoints: Replace chatbackend.watchers.io with the endpoint matching your project region. See 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:

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

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

Fields

⚠️

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:

{
  "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

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

403 Forbidden — missing or invalid bearer token

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

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

400 Bad Request — user not found

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

400 Bad Request — message creation failed

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

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

{
  "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 -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