Cómo actualizar y actuar en tickets vía API

La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de divergencia entre este artículo y la referencia, prevalece lo que está allí.

Cuándo usar

Quieres cambiar el estado (resolver, reabrir), la prioridad o el equipo de un ticket mediante una integración
Necesitas enviar mensajes automáticamente en un ticket existente
Necesitas gestionar labels (etiquetas) en tickets

Requisitos previos

API Key de administrador o supervisor — ver Cómo encontrar tu API Key en Cloud Chat
CLOUDCHAT_DOMAIN, ACCOUNT_ID, CONVERSATION_ID (ID interno) y/o DISPLAY_ID (ID visible en la UI)

Estas APIs escriben en producción. Los cambios impactan SLAs, métricas y la operación. Valida el estado actual del ticket antes de hacer cambios y prueba en un entorno controlado antes de usarlas en producción.

Sobre este artículo

Estas APIs permiten modificar datos reales de tickets — cambiar estado, prioridad, equipo y enviar mensajes. Para solo consultar datos (sin modificar), usa Cómo consultar contactos, tickets y mensajes en tiempo real vía API.

Autenticación

Todos los endpoints exigen:

Header	Valor
`content-type`	`application/json`
`api_access_token`	Token de administrador o supervisor

1. Cambiar el estado del ticket (resolver, reabrir, etc.)

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status

Body

{
  "status": "resolved"
}

Valores aceptados

Valor	Descripción
`open`	Reabrir ticket
`resolved`	Resolver ticket
`pending`	Marcar como pendiente

Ejemplo

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"status": "resolved"}'

Devuelve el objeto de la conversación actualizada con estado 200 OK.

El endpoint PUT /api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} no cambia el estado — solo acepta el campo priority. Para cambiar el estado, usa siempre el toggle_status de arriba.

2. Cambiar la prioridad del ticket

Endpoint

PUT https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}

Body

{
  "priority": "high"
}

Valores aceptados

Valor	Descripción
`nil` / `null`	Sin prioridad
`low`	Baja
`medium`	Media
`high`	Alta
`urgent`	Urgente

Ejemplo

curl -X PUT \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"priority": "high"}'

Este endpoint (PUT .../conversations/{ID}) acepta solamente el campo priority. Campos como status, team_id u otros se ignoran silenciosamente.

3. Cambiar estado, prioridad y equipo (Client API)

Para cambiar estado, prioridad y/o equipo en una sola llamada, usa la Client API:

Endpoint

PATCH https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}}

Este endpoint usa el display_id (ID visible en Cloud Chat), no el conversation_id interno.

Esta Client API exige token de administrador. Los tokens de supervisor o agente reciben 403 Forbidden. Si usas token de supervisor, cambia el status con el toggle_status (sección 1) y la priority con el PUT (sección 2).

Body

{
  "status": "resolved",
  "priority": "high",
  "team_id": "1"
}

Campos aceptados

Campo	Descripción
`status`	Estado del ticket (`open`, `resolved`, `pending`)
`priority`	Prioridad (`low`, `medium`, `high`, `urgent`)
`team_id`	ID del equipo para la reasignación

Todos los campos son opcionales — envía solo lo que quieras cambiar.

Si el team_id informado no existe en la cuenta, la API devuelve 422 con {"error": "Team not found"}.

Ejemplo

curl -X PATCH \
  'https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"status": "resolved"}'

4. Crear un mensaje en un ticket

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages

Body

{
  "content": "Olá! Segue atualização sobre sua solicitação.",
  "message_type": "outgoing"
}

Campos

Campo	Obligatorio	Descripción
`content`	Sí	Contenido del mensaje
`message_type`	Sí	`incoming` (mensaje del cliente) u `outgoing` (mensaje del agente/sistema)
`private`	No	`true` para nota interna (no visible para el cliente)

Ejemplo

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{
    "content": "Sua solicitação foi processada.",
    "message_type": "outgoing"
  }'

5. Gestionar labels (etiquetas) de un ticket

El endpoint PUT /conversations/{ID} no acepta el campo labels. Si envías labels en el body del PUT, la API devuelve 200 pero ignora silenciosamente el campo. Para gestionar labels, usa el endpoint dedicado de abajo.

Endpoint

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels

Body

{
  "labels": ["suporte", "prioridade-alta"],
  "append": true
}

Campos

Campo	Tipo	Obligatorio	Descripción
`labels`	array de strings	Sí	Lista de labels a aplicar
`append`	boolean	No	`true` agrega a las labels existentes. `false` u omitido reemplaza todas

Ejemplo

curl -X POST \
  'https://cloudchat.cloudhumans.com/api/v1/accounts/1/conversations/12345/labels' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"labels": ["suporte", "urgente"], "append": true}'

Campos que no se pueden cambiar vía PUT/PATCH

Algunos campos parecen editables pero la API los ignora silenciosamente (devuelve 200 sin error):

Campo	Situación	Qué hacer
`mail_subject`	Atributo dentro de `additional_attributes`. Solo puede definirse al crear el ticket. Los intentos de actualización vía PUT se ignoran	No hay workaround vía API. Si el asunto del correo debe ser diferente, crea un nuevo ticket
`labels`	Ignorado en el PUT/PATCH del ticket	Usa el endpoint dedicado `POST .../conversations/{ID}/labels` (sección 5)

Resumen: qué endpoint usar para cada acción

Acción deseada	Endpoint	Método
Cambiar estado (resolver, reabrir)	`.../conversations/{ID}/toggle_status`	`POST`
Cambiar prioridad	`.../conversations/{ID}`	`PUT`
Cambiar estado + prioridad + equipo	`/api/client/.../conversations/{DISPLAY_ID}`	`PATCH`
Crear mensaje en el ticket	`.../conversations/{ID}/messages`	`POST`
Gestionar labels	`.../conversations/{ID}/labels`	`POST`

Flujo seguro recomendado

Consulta el estado actual del ticket antes de modificarlo — ver Cómo consultar contactos, tickets y mensajes en tiempo real vía API
Valida si la acción es necesaria (ej.: no resolver un ticket que ya está resuelto)
Ejecuta el cambio usando el endpoint correcto de la tabla de arriba
Confirma el resultado verificando la respuesta de la API

Dónde encontrar los parámetros

CLOUDCHAT_DOMAIN — dominio visible en la URL del navegador
ACCOUNT_ID — en Configuración de la cuenta
CONVERSATION_ID — ID interno de la conversación (devuelto por las APIs de consulta)
DISPLAY_ID — ID visible en la interfaz de Cloud Chat (usado solo en la Client API)
API_TOKEN — en https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Observaciones

Para crear tickets nuevos vía API: Cómo crear tickets vía API en Cloud Chat
Para actualizar atributos personalizados en conversaciones: Cómo actualizar atributos personalizados en conversaciones vía API
Para consultar sin modificar datos: Cómo consultar contactos, tickets y mensajes en tiempo real vía API
Visión general de las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API