Ricky logorickyDocs

Cambiar las etiquetas del contacto de una conversación

PATCH
/conversations/{conversation_id}/tags

Las etiquetas son del contacto de la conversación, no de la conversación: esto le agrega y quita etiquetas a ese contacto, así que todas las conversaciones del contacto las muestran, y responde con el contacto. El cambio es un evento de webhook contact.tags_changed; no hay evento de etiquetas de conversación.

Permiso: contacts:write.

Autorización

bearerAuth
headerAuthorizationBearer <clave>

Una clave de API de la organización, rky_live_…, creada en Configuración → API. Envíala solo desde un servidor.

Parámetros de ruta

conversation_id*string

ID de la conversación.

Formatouuid

Parámetros de cabecera

Idempotency-Key?string

Opcional. Un valor que eliges, único por escritura lógica, de 8 a 200 caracteres: un UUID o un ID de tu sistema, como order-10482-ready. Reintentar con la misma clave y el mismo cuerpo repite la primera respuesta en lugar de repetir la escritura.

Longitud8 <= length <= 200

Cuerpo de la solicitud

application/json
  1. body

Agrega y quita etiquetas en el contacto de la conversación. Sus demás etiquetas se mantienen.

add_tag_ids?array<>

Etiquetas que agregar. Consulta GET /tags.

Elementositems <= 30
Predeterminado[]
remove_tag_ids?array<>

Etiquetas que quitar.

Elementositems <= 30
Predeterminado[]

Cuerpo de la respuesta

Éxito.

application/json
  1. response
data*

Una persona del CRM.

curl -X PATCH 'https://getricky.ai/api/v1/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08/tags' \  -H 'Idempotency-Key: order-10482-ready' \  -H 'Content-Type: application/json' \  -d '{  "add_tag_ids": [    "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f"  ],  "remove_tag_ids": []}'
{  "data": {    "id": "3f6c2b1e-8d4a-4b7e-9a51-2c7d8e9f0a1b",    "first_name": "Ana",    "last_name": "Pérez",    "primary_email": "ana.perez@example.com",    "primary_phone": "+50760001234",    "company": "Casa Nativa",    "job_title": "Gerente de compras",    "birthday": "1990-08-13",    "city": "Panamá",    "region": "Panamá",    "country": "Panamá",    "street_address": "Calle 50, Edificio Global, piso 3",    "postal_code": null,    "website_url": "https://example.com",    "linkedin_url": null,    "source": "WhatsApp",    "notes": "Prefiere que la contacten por la tarde.",    "owner_user_id": "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",    "lead_status": "new",    "lifecycle_stage": "customer",    "custom_values": {      "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d": "Albrook Mall"    },    "identities": [      {        "id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e",        "channel_type": "whatsapp",        "external_id": "50760001234",        "display_name": "Ana Pérez",        "username": null      }    ],    "tags": [      {        "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",        "name": "Cliente frecuente",        "color": "gray"      }    ],    "last_activity_at": "2026-10-14T15:30:00.000Z",    "last_activity_preview": "¿Ya están mis lentes?",    "last_conversation_id": "9b2e4c61-7a3f-4d18-b5c2-6e0f1a2b3c4d",    "updated_at": "2026-10-14T15:30:00.000Z"  }}