Inicio API e integraciones | Claves, endpoints y webhooks Cómo crear, actualizar y eliminar contactos vía API

Cómo crear, actualizar y eliminar contactos vía API

Última actualización el Oct 02, 2026

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

Cuándo usar

  • Necesitas crear, consultar, actualizar o eliminar un contacto específico en Cloud Chat vía API
  • Quieres cambiar solo algunos campos de un contacto sin borrar los demás
  • Estás integrando Cloud Chat con otro sistema que gestiona contactos de forma individual

Requisitos previos

Este artículo cubre operaciones sobre un contacto a la vez mediante el endpoint REST estándar. Para importar o actualizar varios contactos a la vez, usa Cómo importar contactos de forma masiva vía API. Para solo leer datos, consulta Cómo consultar contactos, tickets y mensajes en tiempo real vía API.

Permisos por operación

Operación Permiso mínimo
Crear, consultar, actualizar Cualquier perfil de agente
Eliminar contacto Administrador
Consultar por correo electrónico (/contacts/email) Administrador

Si puedes crear y actualizar pero recibes 403 Forbidden al eliminar, tu token es de agente. Usa un token de usuario administrador para eliminar contactos.

Crear contacto

POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts

El body es un objeto JSON simple — al menos uno entre email, phone_number o identifier:

{
  "name": "Maria Silva",
  "email": "[email protected]",
  "phone_number": "+5511999998888",
  "identifier": "CRM-123",
  "additional_attributes": { "company_name": "Acme" },
  "custom_attributes": { "plano": "premium" }
}

  • Opcional: envía inbox_id (y source_id) para vincular el contacto a una bandeja de entrada desde el inicio.

  • Respuesta 200 con el contacto creado, incluyendo el id.

Consultar contacto

Por id:

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

Por correo electrónico exacto (requiere administrador):

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/[email protected]

Para buscar por texto libre (nombre, teléfono, empresa, parcial), usa el endpoint de búsqueda — ver Cómo consultar contactos, tickets y mensajes en tiempo real vía API, sección "Buscar contatos por texto livre" (Buscar contactos por texto libre).

Actualizar contacto

PUT https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

Envía solo los campos que quieres cambiar:

{
  "name": "Maria S. Silva",
  "custom_attributes": { "plano": "enterprise" }
}

A diferencia de la importación masiva con upsert: true, la actualización individual no borra los campos que no envíes.

  • Los custom_attributes se combinan con los ya existentes (no se borran los demás).

  • Para eliminar un atributo personalizado específico:

POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/destroy_custom_attributes

{ "custom_attributes": ["plano"] }
  • Respuesta 200 con el contacto actualizado.

Eliminar contacto

DELETE https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

  • Requiere usuario administrador.

  • Respuesta 200 en caso de éxito.

Si el contacto está en línea en el momento de la llamada, la eliminación se bloquea y devuelve 422. Inténtalo de nuevo cuando no esté activo.

Para eliminar solo las tags de los contactos (sin eliminar el contacto), consulta Cómo eliminar tags de contactos de forma masiva vía API.

Ejemplo de solicitud (actualizar)

curl -X PUT \
  'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{ "name": "Maria S. Silva" }'

Errores comunes

Status Significado
403 Forbidden Token sin permiso (eliminar requiere administrador)
422 Unprocessable Entity Datos inválidos, o intento de eliminar un contacto en línea
404 Not Found Contacto no encontrado en la cuenta

Dónde encontrar los parámetros

  • CLOUDCHAT_DOMAIN — dominio visible en la URL del navegador

  • ACCOUNT_ID — en "Configurações da conta" (Configuración de la cuenta)

  • API_TOKEN — en https://{CLOUDCHAT_DOMAIN}/app/accounts/{ACCOUNT_ID}/profile/settings

Observaciones