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.

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.