Gestionar conversaciones

Asigná responsables, cambiá estados y guardá datos de tu sistema en una conversación. Los ejemplos usan las variables de la introducción y el ID público 4821.

Asignar agente o equipo

Consultá GET .../inboxes/{inbox_id}/assignable_agents para elegir un agente válido de la bandeja. Después:

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821/assignments" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "assignee_id": 7 }'

Para un equipo, enviá {"team_id": 3} a la misma ruta. Para desasignar, enviá {"assignee_id": null}. Si querés actualizar equipo y agente, hacelo en requests separados: cuando ambos vienen juntos, el controlador prioriza assignee_id.

Validá los IDs antes de asignar. Un ID inexistente puede interpretarse como una desasignación. Además, la cuenta puede restringir las asignaciones a administradores.

Cambiar el estado

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821/toggle_status" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "status": "resolved" }'

Mandá siempre el estado explícito: sin status, la ruta alterna el estado. Resolver o reabrir puede disparar automatizaciones. No uses el estado como sustituto de un control explícito del asistente de IA.

Activar o desactivar el asistente de IA

El asistente se controla por conversación. POST .../conversations/4821/activate_bot lo activa y POST .../conversations/4821/deactivate_bot lo desactiva. No llevan body y responden 201 con la nota interna que representa el comando:

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821/activate_bot" \
  --header "api_access_token: $CRM_API_TOKEN"

El 201 confirma que el comando quedó registrado; el cambio se aplica de forma asincrónica. Verificá el resultado con GET .../conversations/4821/bot_status y leé data.bot_active. Un token de agent bot solo puede operar conversaciones de las bandejas donde está asignado.

Cuando una persona envía un mensaje en el hilo, el asistente se desactiva solo en esa conversación. Si tu integración envía el primer mensaje por API y querés que el asistente siga respondiendo, llamá a activate_bot después de crear el mensaje y confirmá bot_active antes de continuar.

También podés usar una nota privada de texto —el mismo mecanismo del botón del CRM— enviando activar, desactivar, desactivar permanente o reiniciar por POST .../messages con "private": true. Los endpoints solo cubren activar y desactivar; el resto de los comandos va por nota.

Agregar etiquetas sin borrar las existentes

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821/labels" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "labels": ["pedido-confirmado"], "mode": "append" }'

Sin mode: "append", labels reemplaza el conjunto completo. Un array vacío sin ese modo elimina las etiquetas actuales. Para quitar solo una, leé las etiquetas, calculá el conjunto final y enviá la lista; coordiná escrituras simultáneas para no perder cambios de otros usuarios.

Prioridad

POST .../conversations/4821/toggle_priority acepta:

{ "priority": "high" }

Los valores son urgent, high, medium, low o null para quitar la prioridad.

Atributos personalizados

Primero definí el atributo en Ajustes → Atributos personalizados, con el tipo y modelo correctos (contacto o conversación). Podés consultar las definiciones con GET .../custom_attribute_definitions.

POST .../conversations/4821/custom_attributes reemplaza el objeto completo. Para agregar un valor conservando los demás, leé la conversación, combiná los atributos y enviá el resultado. Este ejemplo necesita jq:

conversation=$(curl --fail-with-body \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821" \
  --header "api_access_token: $CRM_API_TOKEN") || exit 1

payload=$(printf '%s' "$conversation" | jq \
  '{custom_attributes: ((.custom_attributes // {}) + {numero_pedido: "ERP-2048"})}') || exit 1

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821/custom_attributes" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data "$payload"

La lectura y la escritura no son atómicas. Si más de un sistema actualiza estos campos, coordiná un único escritor o reconciliá los cambios. En los contactos, la actualización sí combina las claves enviadas con las existentes.

additional_attributes contiene metadatos del canal y del sistema. No lo uses como sustituto de tus atributos personalizados ni sobrescribas el origen de anuncios para guardar datos propios.

Verificar los cambios

Volvé a consultar GET .../conversations/4821 y comprobá status, labels, priority, custom_attributes, meta.assignee y meta.team. Para reaccionar a cambios, suscribite a webhooks; las actualizaciones pueden llegar repetidas o fuera de orden.