Publicar mensajes en un canal

Referencia de POST /api/external/v1/chat/channels/:channelId/messages: publica un mensaje de texto con la identidad de tu aplicación.

Actualizado el 9 de octubre de 2026. 3 min de lectura

Incluido en todos los planes. Ver precios

Con este endpoint tu aplicación publica un mensaje de texto en un canal del Chat, firmado con su nombre y su logotipo. El mensaje aparece al momento a las personas del canal, como cualquier otro, y les llega como aviso.

Antes de publicar, UTILIA OS comprueba las dos puertas de Scopes y acceso por canal: el scope chat:messages:send y una concesión activa en el canal que incluya «Escribir mensajes».

El viaje de un mensaje

De Tu servidor a UTILIA OS:
POST /api/external/v1/chat/channels/:channelId/messages
Con X-Api-Key y el texto en content.
Nota en UTILIA OS:
Comprueba el plan, el scope, la concesión del canal y el límite de 600 mensajes por hora.
De UTILIA OS a Tu servidor:
201: el mensaje publicado (respuesta)
Con author.kind APP y el nombre de tu aplicación.
De UTILIA OS a Personas del canal:
Mensaje en el canal
Aparece al momento, firmado por tu aplicación, y llega como aviso.

4 pasos

POST

/api/external/v1/chat/channels/:channelId/messages

Publica un mensaje como la aplicación en un canal concedido

Petición

channelIdstring (ruta)obligatorio: Identificador del canal donde se publica.
contentstringobligatorio: Texto del mensaje. Hasta 4.000 caracteres; no puede quedar vacío tras quitar los espacios.
parentMessageIdstring: Mensaje al que responde, para publicar dentro de un hilo.
metadataobject: Datos libres de tu aplicación (nunca secretos). Se guardan con el mensaje.

El cuerpo no acepta organización ni autor: la organización sale de la clave de API y el autor es siempre tu aplicación.

Respuesta (201)

idstring: Identificador del mensaje.
channelIdstring: Canal donde se publicó.
contentstring | null: Texto del mensaje.
typestring: Tipo de mensaje; por esta vía, siempre TEXT.
authorobject: Autor: { kind, id, displayName }. Por esta vía, kind es siempre APP y displayName es el nombre de tu aplicación.
parentMessageIdstring | null: Mensaje al que responde, si va en un hilo.
mentionsstring[]: Menciones; por esta vía, siempre vacío.
createdAtstring: Fecha de creación (ISO 8601).
editedAtstring | null: Fecha de la última edición, o null.
isDeletedboolean: Si el mensaje está eliminado.

Límite

Cada aplicación puede publicar hasta 600 mensajes por hora por esta vía. Al superarlo, la respuesta es 429 RATE_LIMIT_EXCEEDED hasta que pasa la hora. Este límite se suma al general de la clave de API.

Errores

Código	`errorCode`	Cuándo
400	`VALIDATION_ERROR`	Falta `content` o pasa de 4.000 caracteres.
401		La clave de API falta o no es válida.
403	`MODULE_NOT_ENABLED`	El plan de tu organización no incluye el Chat.
403	`INSUFFICIENT_SCOPE`	La aplicación no tiene el scope `chat:messages:send`.
403	`APP_NOT_AUTHORIZED_IN_CHANNEL`	No hay concesión activa con «Escribir mensajes», la aplicación ya no es miembro, o no es un canal ni un grupo.
404	`CHANNEL_NOT_FOUND`	El canal no existe o es de otra organización.
422	`VALIDATION_ERROR`	El texto queda vacío al quitar los espacios.
429	`RATE_LIMIT_EXCEEDED`	Se superaron los 600 mensajes por hora.

Ejemplos

curl -X POST 'https://os.utilia.ai/api/external/v1/chat/channels/cnv_8f3a21/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: utl_tu_clave_de_api' \
  -d '{
    "content": "Lectura de las 09:00 — Temperatura de la sala de servidores: 21,4 °C"
  }'

Respuesta:

JSON

{
  "id": "msg_a1b2c3d4",
  "channelId": "cnv_8f3a21",
  "content": "Lectura de las 09:00 — Temperatura de la sala de servidores: 21,4 °C",
  "type": "TEXT",
  "author": {
    "kind": "APP",
    "id": "app_termometro",
    "displayName": "Termómetro"
  },
  "parentMessageId": null,
  "mentions": [],
  "createdAt": "2026-07-12T09:00:03.512Z",
  "editedAt": null,
  "isDeleted": false
}

Siguiente paso

Para que tu aplicación se entere de las respuestas del equipo y conteste, suscríbela a los webhooks de chat. El ejemplo del termómetro lo junta todo.

En esta página